Headless proxy
Headless proxy
This is for:
DeveloperCoveo 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
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:
-
POST
/
to proxy requests toPOST
<ORGANIZATION_ID>.analytics.org<ENVIRONMENT|>.coveo.com/rest/organizations/{ORGANIZATION_ID}/events/v1
-
POST
/validate
to proxy requests toPOST
<ORGANIZATION_ID>.analytics.org<ENVIRONMENT|>.coveo.com/rest/organizations/{ORGANIZATION_ID}/events/v1/validate
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:
-
POST
/click
to proxy requests toPOST
<ORGANIZATION_ID>.analytics.org<ENVIRONMENT|>.coveo.com/rest/v15/analytics/click
-
POST
/collect
to proxy requests toPOST
<ORGANIZATION_ID>.analytics.org<ENVIRONMENT|>.coveo.com/rest/v15/analytics/collect
-
POST
/custom
to proxy requests toPOST
<ORGANIZATION_ID>.analytics.org<ENVIRONMENT|>.coveo.com/rest/v15/analytics/custom
-
GET
/monitoring/health
to proxy requests toGET
<ORGANIZATION_ID>.analytics.org<ENVIRONMENT|>.coveo.com/rest/v15/analytics/monitoring/health
-
POST
/search
to proxy requests toPOST
<ORGANIZATION_ID>.analytics.org<ENVIRONMENT|>.coveo.com/rest/v15/analytics/search
-
POST
/searches
to proxy requests toPOST
<ORGANIZATION_ID>.analytics.org<ENVIRONMENT|>.coveo.com/rest/v15/analytics/searches
-
GET
/status
to proxy requests toGET
<ORGANIZATION_ID>.analytics.org<ENVIRONMENT|>.coveo.com/rest/v15/analytics/status
-
POST
/view
to proxy requests toPOST
<ORGANIZATION_ID>.analytics.org<ENVIRONMENT|>.coveo.com/rest/v15/analytics/view
-
DELETE
/visit
to proxy requests toDELETE
<ORGANIZATION_ID>.analytics.org<ENVIRONMENT|>.coveo.com/rest/v15/analytics/visit
-
GET
/visit
to proxy requests toGET
<ORGANIZATION_ID>.analytics.org<ENVIRONMENT|>.coveo.com/rest/v15/analytics/visit
Search
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.
-
POST
/
to proxy requests toPOST
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/search/v2
-
POST
/plan
to proxy requests toPOST
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/search/v2/plan
-
POST
/querySuggest
to proxy requests toPOST
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/search/v2/querySuggest
-
POST
/facet
to proxy requests toPOST
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/search/v2/facet
-
POST
/html
to proxy requests toPOST
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/search/v2/html
-
GET
/fields
to proxy requests toGET
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/search/v2/fields
Case Assist
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:
-
POST
/classify
to proxy requests toPOST
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/organizations/<ORGANIZATION_ID>/caseassists/<CASE_ASSIST_ID>/classify
-
POST
/documents/suggest
to proxy requests toPOST
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/organizations/<ORGANIZATION_ID>/caseassists/<CASE_ASSIST_ID>/documents/suggest
Commerce
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:
-
POST
/facet
to proxy requests toPOST
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/organizations/<ORGANIZATION_ID>/commerce/v2/facet
-
POST
/listing
to proxy requests toPOST
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/organizations/<ORGANIZATION_ID>/commerce/v2/listing
-
POST
/productSuggest
to proxy requests toPOST
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/organizations/<ORGANIZATION_ID>/commerce/v2/search/productSuggest
-
POST
/querySuggest
to proxy requests toPOST
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/organizations/<ORGANIZATION_ID>/commerce/v2/search/querySuggest
-
POST
/recommendations
to proxy requests toPOST
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/organizations/<ORGANIZATION_ID>/commerce/v2/recommendations
-
POST
/search
to proxy requests toPOST
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/organizations/<ORGANIZATION_ID>/commerce/v2/search
Insight engine
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:
-
GET
/interface
to proxy requests toGET
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/organizations/<ORGANIZATION_ID>/insight/v1/configs/<CONFIG_ID>/interface
-
POST
/querySuggest
to proxy requests toPOST
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/organizations/<ORGANIZATION_ID>/insight/v1/configs/<CONFIG_ID>/querySuggest
-
GET
/quickview
to proxy requests toGET
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/organizations/<ORGANIZATION_ID>/insight/v1/configs/<CONFIG_ID>/quickview
-
POST
/search
to proxy requests toPOST
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/organizations/<ORGANIZATION_ID>/insight/v1/configs/<CONFIG_ID>/search
Recommendation engine
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:
-
POST
/
to proxy requests toPOST
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/search/v2
-
POST
/plan
to proxy requests toPOST
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/search/v2/plan
-
POST
/querySuggest
to proxy requests toPOST
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/search/v2/querySuggest
-
POST
/facet
to proxy requests toPOST
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/search/v2/facet
-
POST
/html
to proxy requests toPOST
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/search/v2/html
-
GET
/fields
to proxy requests toGET
<ORGANIZATION_ID>.org<ENVIRONMENT|>.coveo.com/rest/search/v2/fields