Organization endpoints

This is for:

System Administrator
Important

On July 31, 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:

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)

  • <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).

Coveo Traffic panel

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

  • /rest/organizations/<ORG_ID>/searchinterfaces/<INTERFACE_ID>/html

Atomic

Note

Only available since Atomic v.2.23.4

If using the Atomic library, 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>'),1
    });

  searchInterface.executeFirstSearch();
})();
1 For a HIPAA organization, pass hipaa as an argument to getOrganizationEndpoints, as follows: 
getOrganizationEndpoints('<ORGANIZATION_ID>', 'hipaa')

Headless

Note

Only available since Headless v.2.12.0

Similarly, if using the Coveo Headless library, 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>'),1
  }
})
1 For a HIPAA organization, pass hipaa as an argument to getOrganizationEndpoints, as follows: 
getOrganizationEndpoints('<ORGANIZATION_ID>', 'hipaa')

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

For usage analytics API requests, 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/ua/v?*/analytics/*

  • /rest/v15/analytics/*

  • /rest/v14/analytics/*

Atomic and Headless

When using the Atomic or Headless libraries, specifying 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

HIPAA organization

EXAMPLE

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. These endpoints can be used for most Coveo API requests outside of UA. 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.