Organization endpoints
Organization endpoints
This is for:
System Administrator
On December 9, 2024, Coveo will deprecate older endpoints and make other endpoint-related changes. However, since Coveo can’t review your code, it’s up to you to ensure that your implementation isn’t impacted by these changes. We therefore strongly encourage you to check your Coveo implementation and make the necessary changes as soon as possible, if applicable. See Endpoint deprecation and other endpoint-related changes for details. |
Until 2023, depending on where your primary deployment region was located, you needed to use region-specific endpoints to send Coveo API requests.
For example, if your primary region was Ireland, you needed to use platform-eu.cloud.coveo.com/rest/search
to send requests to the Search API.
To improve separation of concerns, resiliency, and make multi-region and data residency deployments smoother, we’ve introduced organization endpoints.
Besides the generic platform endpoints (platform-<REGION>.cloud.coveo.com
), which will keep working, we now generate three kinds of endpoints for each Coveo organization, based on its ID:
-
<ORG_ID>.org.coveo.com
(Search requests) -
<ORG_ID>.analytics.org.coveo.com
(Usage Analytics logging) -
<ORG_ID>.admin.org.coveo.com
(organization administration)
Similarly, in addition to platformhipaa.cloud.coveo.com
, we now generate three kinds of endpoints for each HIPAA organization, based on its ID:
-
<ORG_ID>.orghipaa.coveo.com
(Search requests) -
<ORG_ID>.analytics.orghipaa.coveo.com
(Usage Analytics logging) -
<ORG_ID>.admin.orghipaa.coveo.com
(organization administration)
With these new endpoints, you no longer need to keep track of the location of your primary deployment region. These endpoints are region agnostic and will automatically route requests to the region offering the lowest latency. Whether your deployment strategy is data residency or multi-region, we recommend using the newly created organization-specific endpoints for more seamless interaction with Coveo APIs and to facilitate query rerouting if a problem occurs.
You can review your current and recommended endpoints in your organization settings, under Traffic (platform-ca | platform-eu | platform-au).
Alternatively, you can call the global configuration endpoint.
Search endpoint
For Search requests and to retrieve user action history, use:
-
<ORG_ID>.org.coveo.com/rest/search
for a non-HIPAA organization -
<ORG_ID>.orghipaa.coveo.com/rest/search
for a HIPAA organization
Those endpoints cover requests made to:
-
/rest/search/*
-
/rest/organizations/<ORG_ID>/machinelearning/user/actions
For technical reasons, request to the following are supported through redirections to the primary deployment region (that is, slower response times may be observed when queries are routed to satellite regions).
-
/rest/organizations/<ORG_ID>/commerce/*
-
/rest/organizations/<ORG_ID>/caseassists/*
-
/rest/organizations/<ORG_ID>/insight/*
-
/rest/organizations/<ORG_ID>/ipxinterface/v1/interfaces/<INTERFACE_ID>/loader
Atomic
v3
Atomic v3 automatically enforces the use of organization endpoints.
v2
Note
Only available since Atomic v.2.23.4 |
If using the Atomic library v2, set the organizationEndpoints
parameter using the getOrganizationEndpoints
function when initializing your atomic-search-interface
, as seen below.
The library will infer which endpoints to use.
(async () => {
await customElements.whenDefined('atomic-search-interface');
const searchInterface = document.querySelector('#search');
await searchInterface.initialize({
accessToken:'<ACCESS_TOKEN>',
organizationId: '<ORGANIZATION_ID>',
organizationEndpoints: await searchInterface.getOrganizationEndpoints('<ORGANIZATION_ID>'),
});
searchInterface.executeFirstSearch();
})();
For a HIPAA organization, pass hipaa as an argument to getOrganizationEndpoints , as follows:
|
Headless
v3
Headless v3 automatically enforces the use of organization endpoints.
v2
Note
Only available since Headless v.2.12.0 |
If using the Coveo Headless library v2, set the organizationEndpoints
parameter using the getOrganizationEndpoints
function in your SearchEngineConfiguration
when initializing your Headless Search Engine (or analogously for other kinds of engines), as seen below.
The library will infer which endpoints to use.
export const headlessEngine = buildSearchEngine({
configuration: {
organizationId: "<ORGANIZATION_ID>",
accessToken: "<ACCESS_TOKEN>",
organizationEndpoints: getOrganizationEndpoints('<ORGANIZATION_ID>'),
}
})
For a HIPAA organization, pass hipaa as an argument to getOrganizationEndpoints , as follows:
|
JavaScript Search Framework
If using the Coveo JavaScript Search Framework, set your search endpoint to https://<ORG_ID>.org.coveo.com/rest/search
or https://<ORG_ID>.orghipaa.coveo.com/rest/search
, depending on whether your organization is HIPAA or not.
For example:
Coveo.SearchEndpoint.configureCloudV2Endpoint("<ORG_ID>", "<SEARCH_TOKEN>", "https://<ORG_ID>.org.coveo.com/rest/search");
Analytics endpoint
To log usage analytics, use:
-
<ORG_ID>.analytics.org.coveo.com/rest/ua/
for a non-HIPAA organization -
<ORG_ID>.analytics.orghipaa.coveo.com/rest/ua/
for a HIPAA organization
These analytics endpoints let ad blockers distinguish between analytics and non-analytics requests sent to the Coveo platform. As a result, ad blockers can target and block requests to log UA events specifically, preventing issues with Search requests.
Those endpoints cover requests made to:
-
/rest/v15/analytics/*
-
/rest/v14/analytics/*
Atomic and Headless
If using the v3 Atomic or Headless libraries, the libraries enforce the use of organization endpoints for analytics logging.
If using v3, specify the organizationEndpoints
parameter using the getOrganizationEndpoints
function, as above, will allow the library to infer which analytics endpoint to target.
JavaScript Search Framework
If using the Coveo JavaScript Search Framework, set your analytics component data-endpoint
property.
The property must use one of the following formats depending on your JavaScript Search Framework version and whether your organization is HIPAA or not.
Non-HIPAA organization
-
Coveo JavaScript Search Framework v2.8864 (April 2020) or later:
https://<ORG_ID>.analytics.org.coveo.com/rest/ua
-
Coveo JavaScript Search Framework v2.8521 (March 2020) or earlier:
https://<ORG_ID>.analytics.org.coveo.com/
HIPAA organization
-
Coveo JavaScript Search Framework v2.8864 (April 2020) or later:
https://<ORG_ID>.analytics.orghipaa.coveo.com/rest/ua
-
Coveo JavaScript Search Framework v2.8521 (March 2020) or earlier:
https://<ORG_ID>.analytics.orghipaa.coveo.com/
For a non-HIPAA organization that’s using Coveo JavaScript Search Framework v2.8864 or later:
<div class="CoveoAnalytics" data-endpoint="https://myorganization-bfghkjfjb674jh5egjk.analytics.org.coveo.com/rest/ua"></div>
Admin endpoint
Use <ORG_ID>.admin.org.coveo.com
and <ORG_ID>.admin.orghipaa.coveo.com
instead of platform-<REGION>.cloud.coveo.com
and platformhipaa.cloud.coveo.com
to perform administrative API calls, including reading UA reports.
These endpoints can be used for most Coveo API requests outside UA logging.
While they can technically be used for Search, we recommend against doing so, in favour of the search endpoints introduced earlier.
A further advantage is that you no longer need to know your main region to navigate to the Administration Console.
As a test, type in <ORG_ID>.admin.org.coveo.com
with your specific <ORG_ID>
into your browser to access the Administration Console.
You’ll be automatically redirected to the proper region endpoint.
Integrations
Certain Coveo integrations require a configuration that differs from what’s explained in the preceding sections of this article.
Coveo for Sitecore
To configure organization endpoints in a Coveo for Sitecore deployment, see Migrate to organization endpoints.
Coveo for Salesforce
To configure organization endpoints for a Coveo for Salesforce deployment, see Using the Advanced Configuration page.
Coveo for ServiceNow
By default, Coveo for ServiceNow integrations use organization endpoints for search and usage analytics requests. No additional configuration is required. However, if you need to configure Coveo for ServiceNow requests to go through a proxy server or a specific region endpoint in a multi-region deployment, you can disable the organization endpoints feature.