Use the Passage Retrieval API

This is for:

Developer

The Passage Retrieval API (PR API) allows developers to extract specific sections of text (passages) from documents stored in Coveo. This enables efficient retrieval of ranked text data for various use cases, including enhancing large language models (LLMs).

The PR API offers the following key features:

  • Integration with Coveo Search API

    The PR API is built upon the existing Coveo Search API infrastructure, ensuring seamless integration with your current query pipelines.

  • Query pipelines configuration

    This API supports query pipeline configurations in the same way as the Coveo Search API, allowing you to customize the behavior of the PR API.

  • machine learning models

    This API uses Coveo’s advanced ML models, such as the Automatic Relevance Tuning (ART) model, to dynamically adjust and improve search relevance.

  • Contextual passage retrieval

    It’s specifically designed to return contextual pieces of information (passages) from documents enhancing the accuracy and relevance of responses generated by LLMs.

This article explains how to use the Passage Retrieval API to retrieve text passages from a Coveo index.

Prerequisites

To use the Passage Retrieval API, make sure:

Limitations

  • The embedding limits for your CPR model are the same as those for the RGA models (see Model embedding limits).

  • Performance is directly related to the number of documents and their average size. For example, doubling the average passages per document may reduce the queries per second (QPS) rate by half.

  • The pipeline used for the Passage Retrieval API must have a Semantic Encoder (SE) model associated with it.

  • Supported authentication methods are:

  • Currently, PR API only supports the English language. Once the language support is expanded, this article will be updated.

Request endpoint

To use the Passage Retrieval API, send a POST request to the following endpoint:

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

Content-Type: application/json
Accept: application/json
Authorization: Bearer <MyAccessToken>

Request payload

The following example shows the payload to retrieve passages from a Coveo index:

{
  "query": "What are the benefits of using solar energy?", 1
  "filter": "@source==\"acme\"", 2
  "additionalFields": [ 3
    "clickableuri"
  ],
  "maxPassages": 5, 4
  "searchHub": "Main", 5
  "localization": { 6
    "locale": "en-CA",
    "timezone": "America/Montreal"
  },
  "context": { 7
    "userAgeRange": "25-35",
    "userRoles": [
      "PremiumCustomer",
      "ProductReviewer"
    ]
  }
}
Details
1 query (string, required): The basic query expression, typically the keywords entered by the end user in a query box.
2 filter (string): The filter expression to apply to the query. This expression is used to restrict the search to a specific source or document type.
3 additionalFields (array of strings): The additional fields to include in the response, maximum of 5 fields.
4 maxPassages (number): The maximum number of passages to retrieve. Minimum is 1, maximum is 5. The passages are sorted by relevance score in descending order, so the first passage in the response is the most relevant one.
5 searchHub (string, required): The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates. Required in the payload or in the authentication token. See About the search hub.
6 localization (object, required): localization parameters

  • locale (string, required): The locale for the search.

  • timezone (string): The tz database identifier of the user’s time zone.
7 context (object): The custom context information to send along with the request. Consists of key-value pairs where the key is a string and the value is a string or an array of strings.
Important

For more details, see the Passage Retrieval API reference.

Response payload

The following example shows a response payload from the Passage Retrieval API:

{
  "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",
        "primaryid": "GAYEG6LHNB2DQ4LLNBKVEUSHKUXDCMZWGEZS4ZDFMZQXK3DU",
        "clickableuri": "https://example.com/search/document-solar-energy"
      }
    },
    {
      // another item
    }
  ],
  "responseId": "c0857557-5579-4f5e-8958-9befd7d1d4a8" 5
}
Details
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. The higher the value, the higher the relevance. The score computation is based on cosine similarity between the passage and the query.
Important

The computation logic may change in the future.
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.
5 responseId (string): A unique identifier for the response. It can be used to track the response in logs or for debugging purposes.
Important

For more details, see the Passage Retrieval API reference.