Headless proxy

This is for:

Developer

Coveo Headless engines and certain actions expose proxyBaseUrl options. You should only set this advanced option if you need to proxy Coveo API requests through your own server. In most cases, you shouldn’t set this option.

By default, no proxy is used and the Coveo API requests are sent directly to the Coveo platform through organization endpoints resolved from the ORGANIZATION_ID and ENVIRONMENT values provided in your engine configuration, such as <ORGANIZATION_ID>.org.coveo.com or <ORGANIZATION_ID>.org<ENVIRONMENT>.coveo.com, if the ENVIRONMENT values is specified and different from prod.

If you set this option, you must also implement the required proxy endpoints in your server, otherwise the Headless engine won’t work properly. The exact endpoints you need to implement depend on the proxyBaseUrl you want to set.

Analytics

Example
import { buildSearchEngine } from '@coveo/headless';

const searchEngine = buildSearchEngine({
  organizationId: 'my-org-id',
  accessToken: 'my-access-token',
  analytics: {
    proxyBaseUrl: 'https://search-proxy.example.com',
  },
});

If you set the proxyBaseUrl option in your engine analytics configuration, you must also implement the correct proxy endpoints in your server, depending on the analyticsMode you’re using.

If you’re using the next analytics mode, you must implement the following proxy endpoints:

The Event Protocol Reference provides documentation on the analytics event schemas that can be passed as request bodies to the above endpoints.

If you’re using the legacy analytics mode, your proxyBaseUrl must end with /rest/v15/analytics, and you must implement the following proxy endpoints:

Example
import { buildSearchEngine } from '@coveo/headless';

const searchEngine = buildSearchEngine({
  organizationId: 'my-org-id',
  accessToken: 'my-access-token',
  search: {
    proxyBaseUrl: 'https://search-proxy.example.com',
  },
});

If you’re setting the proxyBaseUrl option in your search engine or action configuration, you must also implement the correct proxy endpoints in your server, depending on the search API requests you want to proxy.

Case Assist

Example
import { buildCaseAssistEngine } from '@coveo/headless/case-assist';

const caseAssistEngine = buildCaseAssistEngine({
  caseAssistId: 'my-case-assist-id',
  organizationId: 'my-organization-id',
  accessToken: 'my-access-token',
  proxyBaseUrl: 'https://case-assist-proxy.example.com',
});

If you’re setting the proxyBaseUrl option in your case assist engine, action or state configuration, you must also implement the following proxy endpoints in your server, otherwise the case assist engine won’t work properly:

Commerce

Example
import { buildCommerceEngine } from '@coveo/headless/commerce';

const commerceEngine = buildCommerceEngine({
  configuration: {
    organizationId: 'my-org-id',
    accessToken: 'my-access-token',
    proxyBaseUrl: 'https://commerce-proxy.example.com',
  },
});

If you’re setting the proxyBaseUrl option in your commerce engine or action configuration, you must also implement the following proxy endpoints in your server, otherwise the commerce engine won’t work properly:

Insight engine

Example
import { buildInsightEngine } from '@coveo/headless/insight';

const searchEngine = buildInsightEngine({
  organizationId: 'my-org-id',
  accessToken: 'my-access-token',
  search: {
    proxyBaseUrl: 'https://insight-proxy.example.com',
  },
});

If you’re setting the proxyBaseUrl option in your insight engine configuration, you must also implement the following proxy endpoints in your server, otherwise the insight engine won’t work properly:

Recommendation engine

Example
import { buildRecommendationEngine } from '@coveo/headless/recommendation';

const RecommendationEngine = buildRecommendationEngine({
  configuration: {
    caseAssistId: 'my-case-assist-id',
    organizationId: 'my-organization-id',
    accessToken: 'my-access-token',
    proxyBaseUrl: 'https://recommendation-proxy.example.com',
  },
});

If you’re setting the proxyBaseUrl option in your recommendation engine configuration, you must also implement the following proxy endpoints in your server, otherwise the recommendation engine won’t work properly: