Organization endpoints

This is for:

In this article

Search endpoint
Analytics endpoint
Admin endpoint
Integrations

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

If you’re unsure what your organization endpoints are, you can call the global configuration endpoint to find out.

Alternatively, you can view your current and recommended endpoints in the Coveo Administration Console, in the Traffic (platform-ca | platform-eu | platform-au) subtab of the Settings page, along with other details.

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 (i.e., 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>'),
    });

  searchInterface.executeFirstSearch();
})();

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>'),
  }
})

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 to https://<ORG_ID>.org.coveo.com/rest/ua or https://<ORG_ID>.orghipaa.coveo.com/rest/ua, depending on whether your organization is HIPAA or not. For example:

<div class="CoveoAnalytics" data-endpoint="https://<ORG_ID>.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 above. 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 will be automatically redirected to the proper region endpoint.

Integrations

Certain Coveo integrations require a configuration that differs from what is explained above in this article.

Coveo for Sitecore

To configure organization endpoints in a Coveo for Sitecore deployment, see Organization endpoints and multi-region support.

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.