Passage Retrieval API: Upgrade from alpha to v3

This is for:

Developer

The public release of the Passage Retrieval API marks version 3 and introduces several changes and improvements over the alpha version. This article explains what changes are so you can upgrade your existing implementation.

Endpoints

v3/passages/retrieve

The alpha version of the Passage Retrieval API used the following endpoint:

https://<MyOrganizationId>.org.coveo.com/rest/search/alpha/passages/retrieve

That endpoint is now deprecated. The new endpoint for the Passage Retrieval API v3 is:

https://<MyOrganizationId>.org.coveo.com/rest/search/v3/passages/retrieve

The change highlights the version of the API you’re using and ensures that your implementation is up-to-date.

alpha/passages/retrieve/debug

This is a new endpoint and it’s in alpha. You can use it to debug the Passage Retrieval API requests and responses. See the details in the Passage Retrieval API reference.

New limitations

The v3 introduces new limitations:

Request changes

The request payload structure has changed drastically.

See an example of the alpha version payload structure 
{
  "searchContext": {
    "q": "What are the benefits of using solar energy?", 1
    "aq": "(NOT (@commonolderplatformcomponent OR @objecttype==\"Archived Content\"))", 2
    "tab": "All", 3
    "locale": "en", 4
    "debug": false, 5
    "timezone": "America/Toronto" 6
  },
  "numberOfPassages": 5
}
1 q (string): The basic query expression, typically the keywords entered by the end user in a query box.
2 aq (string): The advanced query filter to exclude specific content.
3 tab (string): The search tab to use.
4 locale (string): The locale for the search.
5 debug (boolean): The flag to enable or disable debugging.
6 timezone (string): The tz database identifier of the user’s time zone.

The new payload structure is shown below with the changes explained. For more details, see the Passage Retrieval API reference and Use the Passage Retrieval API.

{
  "query": "What are the benefits of using solar energy?", 1
  "filter": "@source==\"acme\"", 2
  "additionalFields": [ 3
    "clickableuri"
  ],
  "maxPassages": 5, 4
  "searchHub": "Main", 5
  "localization": {
    "locale": "en-CA", 6
    "timezone": "America/Montreal" 7
  },
  "context": { 8
    "userAgeRange": "25-35",
    "userRoles": [
      "PremiumCustomer",
      "ProductReviewer"
    ]
  }
}
1 searchContext.q =⇒ query (string, required). Moved and renamed.
2 searchContext.aq =⇒ filter (string). Moved and renamed.
3 additionalFields (array of strings): A new parameter to include additional fields in the response.
4 numberOfPassages =⇒ maxPassages (number). Renamed.
5 searchContext.searchHub ⇒ searchHub (string, required). Moved.
6 searchContext.locale =⇒ localization.locale (string, required). Moved and now required.
7 searchContext.timezone =⇒ localization.timezone (string). Moved.
8 searchContext.context =⇒ context (object). Moved.
Important

A number of parameters were completely removed from the request payload. See the details in the following table.
Removed parameter Notes

searchContext.dq

Can be set via query pipeline filters.

searchContext.cq

Can be set via query pipeline filters.

searchContext.pipeline

Can be set in a search token.

searchContext.referrer

-

searchContext.tab

-

searchContext.rankingFunctions

-

searchContext.queryFunctions

-

searchContext.debug

Replaced by the debug endpoint.

searchContext.pipelineRuleParameters

-

Response changes

See an example of the alpha version payload structure 
{
  "items": [ 1
    {
      "text": "Solar energy has several benefits including reducing electricity bills, providing a renewable energy source, and lowering carbon footprint.\",\n", 2
      "relevanceScore": 0.95, 3
      "document": { 4
        "title": "The Benefits of Solar Energy",
        "permanentId": "648a63d6a19545297692b4ae41a7d5e947c711be5f3c23dff69af3106960",
        "clickableuri": "https://example.com/search/document-solar-energy"
      }
    },
    {
      // another item
    }
  ]
}
1 items (array of objects): The array of passages.
2 text (string): Text content of the passage.
3 relevanceScore (number): A measure of how relevant a passage is to the query based on semantic similarity, as determined by the CPR model. The higher the value, the higher the relevance.
4 document (object): The document that contains this passage. By default, it includes only the title and primary ID of the document. If you specified additional fields in the request payload, they will be included here as well.

The new response payload structure has minor changes:

{
  "items": [
    {
      "text": "Solar energy has several benefits including reducing electricity bills, providing a renewable energy source, and lowering carbon footprint.\",\n",
      "relevanceScore": 0.95,
      "document": { 1
        "title": "The Benefits of Solar Energy",
        "primaryid": "GAYEG6LHNB2DQ4LLNBKVEUSHKUXDCMZWGEZS4ZDFMZQXK3DU", 2
        "clickableuri": "https://example.com/search/document-solar-energy"
      }
    },
    {
      // another item
    }
  ],
  "responseId": "c0857557-5579-4f5e-8958-9befd7d1d4a8" 3
}
1 document (object): If you specified additional fields in the request payload, they will be included here as well.
2 items[].document.permanentid =⇒ items[].document.primaryid (string). The document ID is replaced by the primary ID, a new field that uniquely identifies an index item.
3 responseId (string): A unique identifier for the response. It can be used to track the response in logs or for debugging purposes.