Search products - Voyant API

{
  "items": [
    {
      "id": "main:550e8400-e29b-41d4-a716-446655440000:en",
      "title": "Paris City Tour",
      "source": "main",
      "locale": "en",
      "snippet": "Discover the beauty of <em>Paris</em> with our guided city tour",
      "workspaceId": "wksp_01h8z3y4x2w1v0u9t8s7r6q5p4",
      "type": "tour",
      "score": 1234,
      "priceFrom": {
        "value": 89.99,
        "currency": "EUR"
      },
      "thumbnailUrl": "https://cdn.voyantcloud.com/products/paris-tour.jpg"
    },
    {
      "id": "marketplace:provider_prod_123:en",
      "title": "Louvre Museum Skip-the-Line",
      "source": "marketplace",
      "locale": "en",
      "snippet": "Skip the lines at the <em>Paris</em> Louvre Museum",
      "providerId": "provider_abc",
      "type": "experience",
      "score": 1123
    }
  ],
  "page": 0,
  "nbPages": 5,
  "hitsPerPage": 20,
  "total": 87,
  "tookMs": 42,
  "facets": {
    "type": {
      "tour": 56,
      "experience": 22
    },
    "status": {
      "active": 70,
      "draft": 17
    }
  },
  "exhaustiveFacetsCount": true
}

{
  "error": "Invalid request parameters",
  "details": [
    {
      "path": ["pageSize"],
      "message": "Number must be less than or equal to 100"
    }
  ]
}

{
  "error": "Unauthorized"
}

{
  "error": "Search service unavailable"
}

Endpoint

GET https://api.voyantcloud.com/v1/products/search Search for products across your catalog with full-text search and faceting. Results include both workspace-owned products and marketplace products from providers you have access to, with automatic workspace isolation and provider filtering.

Authentication

string

required

Bearer token (e.g. Authorization: Bearer YOUR_API_KEY)

Query parameters

string

Search query string. If omitted, returns all products matching filters.

string

default:"en"

Locale for search. Options: en, ro

integer

default:"0"

Zero-based page number (for page-based pagination)

integer

default:"20"

Number of results per page (1-100)

integer

Starting offset (for offset-based pagination). Takes precedence over page if provided.

integer

Number of results (for offset-based pagination). Defaults to pageSize if not provided.

string

Filter by product type (e.g., tour, cruise, accommodation)

string

Filter by status (e.g., active, draft, archived)

string

B2B: Filter by organization visibility (UUID format)

string

Field to sort by. Available options:

price or priceFrom - Sort by starting price
created - Sort by creation date
updated - Sort by last update date (default)
departure - Sort by earliest departure date
relevance - Sort by text search relevance score

string

default:"desc"

Sort order. Options: asc, desc.

string

Advanced filtering using Typesense filter syntax. This allows filtering on any indexed field.Syntax:

Array contains: tags:=[Black Friday]
Exact match: status:=active
Multiple values (OR): tags:=[Black Friday, Featured]
Numeric comparison: priceFromValue:>100
AND conditions: tags:=[Black Friday] && type:=tour
OR conditions: type:=tour || type:=cruise

Remember to URL-encode the filters parameter value. For example, tags:=[Black Friday] becomes tags%3A%3D%5BBlack%20Friday%5D.

Request example

# Basic search
curl "https://api.voyantcloud.com/v1/products/search?q=paris&locale=en" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by tag (URL-encoded: tags:=[Black Friday])
curl "https://api.voyantcloud.com/v1/products/search?filters=tags%3A%3D%5BBlack%20Friday%5D" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Sort by price ascending (cheapest first)
curl "https://api.voyantcloud.com/v1/products/search?q=tour&sortBy=price&sortOrder=asc" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Combined: filter by tag + type, sort by departure date
curl "https://api.voyantcloud.com/v1/products/search?filters=tags%3A%3D%5BBlack%20Friday%5D%20%26%26%20type%3A%3Dtour&sortBy=departure&sortOrder=asc" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  "https://api.voyantcloud.com/v1/products/search?q=paris&locale=en",
  {
    headers: {
      Authorization: `Bearer ${process.env.VOYANT_API_KEY}`,
    },
  }
)

const results = await response.json()
console.log(results.items)

import requests
import os

response = requests.get(
  'https://api.voyantcloud.com/v1/products/search',
  params={'q': 'paris', 'locale': 'en'},
  headers={'Authorization': f"Bearer {os.environ['VOYANT_API_KEY']}"}
)

results = response.json()
print(results['items'])

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.voyantcloud.com/v1/products/search?q=paris&locale=en');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer ' . getenv('VOYANT_API_KEY')
]);

$response = curl_exec($ch);
$results = json_decode($response, true);
print_r($results['items']);
?>

Response

array

required

Array of product search results

Show Item properties

string

Product ID (objectID from search index)

string

Product title

string

Source type: main (workspace-owned), marketplace (provider product), or override (customized marketplace product)

string

Locale of the result

string

Highlighted snippet of matching text with <em> tags

string

Provider ID (if source: "marketplace" or source: "override")

string

Workspace ID (if source: "main")

string

Product type

number

Search relevance score

integer

Current page number (page-based pagination only)

integer

Total number of pages (page-based pagination only)

integer

Number of results per page (page-based pagination only)

integer

Current offset (offset-based pagination only)

integer

Number of results returned (offset-based pagination only)

integer

required

Total number of matching results

integer

required

Query execution time in milliseconds

object

Facet buckets and counts for the current query (all facet attributes returned).

boolean

Whether facet counts are exact (true) or approximate (false).

{
  "items": [
    {
      "id": "main:550e8400-e29b-41d4-a716-446655440000:en",
      "title": "Paris City Tour",
      "source": "main",
      "locale": "en",
      "snippet": "Discover the beauty of <em>Paris</em> with our guided city tour",
      "workspaceId": "wksp_01h8z3y4x2w1v0u9t8s7r6q5p4",
      "type": "tour",
      "score": 1234,
      "priceFrom": {
        "value": 89.99,
        "currency": "EUR"
      },
      "thumbnailUrl": "https://cdn.voyantcloud.com/products/paris-tour.jpg"
    },
    {
      "id": "marketplace:provider_prod_123:en",
      "title": "Louvre Museum Skip-the-Line",
      "source": "marketplace",
      "locale": "en",
      "snippet": "Skip the lines at the <em>Paris</em> Louvre Museum",
      "providerId": "provider_abc",
      "type": "experience",
      "score": 1123
    }
  ],
  "page": 0,
  "nbPages": 5,
  "hitsPerPage": 20,
  "total": 87,
  "tookMs": 42,
  "facets": {
    "type": {
      "tour": 56,
      "experience": 22
    },
    "status": {
      "active": 70,
      "draft": 17
    }
  },
  "exhaustiveFacetsCount": true
}

{
  "error": "Invalid request parameters",
  "details": [
    {
      "path": ["pageSize"],
      "message": "Number must be less than or equal to 100"
    }
  ]
}

{
  "error": "Unauthorized"
}

{
  "error": "Search service unavailable"
}

Error handling

400 Bad Request

Invalid query parameters.Possible causes:

pageSize exceeds 100
Invalid locale value
Invalid organizationId format

Solution: Check your query parameters match the documented formats and constraints.

401 Unauthorized

Missing or invalid API key.Solution: Check your Authorization: Bearer header is set correctly.

503 Service Unavailable

Search service is temporarily unavailable.Solution: Retry the request after a short delay. If the issue persists, contact support.

Features

Workspace isolation

All search results are automatically filtered to include only:

Products owned by your workspace (source: "main")
Marketplace products from providers you have active connections or grants for

Override precedence

If your workspace has created overrides for a marketplace product, the override version is returned instead of the base marketplace product, automatically de-duplicated.

Relevance ranking

Results are ranked by a relevance algorithm, which considers:

Text matching (query terms in title, description)
Popularity signals
Custom ranking factors

The search response includes a facets object, which contains all filterable attributes for the current result set. You can use these facets to build a filtered search UI. While you can use the top-level type and status parameters for basic filtering, the filters parameter provides advanced capabilities using Typesense filter syntax. Available facets:

type - Product type (tour, cruise, accommodation, etc.)
status - Product status (active, draft, archived)
categories - Category assignments
tags - Product tags
countries - Countries the product visits
regions - Geographic regions
priceFromCurrency - Price currency
source - Product source (main, marketplace, override)

Example: Filtering by multiple facets

Perform an initial search to get available facets.
Use the filters parameter in a subsequent request to refine the results.

async function searchWithFacets() {
  // Filter for tours tagged as "outdoor" using Typesense syntax
  const filters = 'type:=tour && tags:=[outdoor]';

  const params = new URLSearchParams({
    q: 'adventure',
    filters: filters,
    pageSize: 20,
    locale: 'en',
  });

  const response = await fetch(
    `https://api.voyantcloud.com/v1/products/search?${params}`,
    {
      headers: { Authorization: `Bearer ${process.env.VOYANT_API_KEY}` },
    }
  );

  return await response.json();
}

// More filter examples:
// By country: filters=countries:=[ro]
// By price range: filters=priceFromValue:>=100 && priceFromValue:<=500
// Multiple tags (OR): filters=tags:=[Black Friday, Featured]
// Multiple tags (AND): filters=tags:=[Black Friday] && tags:=[Featured]

This allows for dynamic and precise filtering based on any attribute indexed in the product catalog.

Use cases

Product search autocomplete

Build a search-as-you-type experience:

let searchTimeout

async function searchProducts(query) {
  clearTimeout(searchTimeout)

  searchTimeout = setTimeout(async () => {
    const response = await fetch(
      `https://api.voyantcloud.com/v1/products/search?q=${encodeURIComponent(query)}&pageSize=10`,
      {
        headers: { Authorization: `Bearer ${process.env.VOYANT_API_KEY}` },
      }
    )

    const results = await response.json()
    displayResults(results.items)
  }, 300) // Debounce 300ms
}

Filtered product search

Search with type and status filters:

async function searchTours(query, status = 'active') {
  const params = new URLSearchParams({
    q: query,
    type: 'tour',
    status,
    pageSize: 20,
    locale: 'en',
  })

  const response = await fetch(
    `https://api.voyantcloud.com/v1/products/search?${params}`,
    {
      headers: { Authorization: `Bearer ${process.env.VOYANT_API_KEY}` },
    }
  )

  return await response.json()
}

List products

Browse products with database filtering

Search facets

Search for facet values

Get product

Retrieve detailed product information

​Endpoint

​Authentication

​Query parameters

​Request example

​Response

​Error handling

​Features

​Workspace isolation

​Override precedence

​Relevance ranking

​Facet Filtering

​Use cases

​Product search autocomplete

​Filtered product search

​Related endpoints

List products

Search facets

Get product

Endpoint

Authentication

Query parameters

Request example

Response

Error handling

Features

Workspace isolation

Override precedence

Relevance ranking

Facet Filtering

Use cases

Product search autocomplete

Filtered product search

Related endpoints