Use the Passage Retrieval API

This is for:

Developer

The Passage Retrieval API (PR API) allows developers to retrieve 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, allowing you to leverage your existing query pipelines.

  • Query pipelines configuration

    This API supports many query pipeline configurations, allowing you to customize the behavior of the PR API. However, some features aren’t supported or have limitations (see Query pipeline feature support).

  • 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

Query pipeline feature support

The Passage Retrieval API supports many query pipeline features, but some aren’t supported or have limitations.

Feature Support status Notes

Conditions

Partial

Conditions based on Referrer, Recommendation, and FacetsFilter aren’t supported.

A/B tests

Not supported

Groups & Campaigns

Supported

Search terms

Partial

Result ranking

Supported

Includes Featured results and Ranking expressions.

Machine learning

Partial

The only supported model is Automatic Relevance Tuning (ART).

Advanced

Partial

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": ["clickableuri"], 3
  "maxPassages": 5, 4
  "searchHub": "Main", 5

  "localization": { 6
    "locale": "en-CA", 7
    "timezone": "America/Montreal" 8
  },
  "context": { 9
    "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 (string[]): The additional fields to include in the response, maximum of 20 fields. The identifier of the document (primaryid) is always returned in the response, but you can choose to include metadata from other document fields.
4 maxPassages (number): The maximum number of passages to retrieve. Minimum is 1, maximum is 20. 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 origin level 1 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
7 locale (string, required): The locale for the search.
8 timezone (string): The tz database identifier of the user’s time zone.
9 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:

Note

The total response size is limited to 540 KB. If the response size exceeds the maximum, the Passage Retrieval API returns an error message.

 
{
  "items": [ 1
    {
      "text": "Solar energy has several benefits including reducing electricity bills, [...]", 2
      "relevanceScore": 0.95, 3
      "document": { 4
        "title": "The Benefits of Solar Energy",
        "primaryid": "GAYEG6LHNB2DQ4LLNBKVEUSHKUXDCMZWGEZS4ZDFMZQXK3DU",
        "clickableuri": "https://example.com/search/document-solar-energy"
      }
    }
  ],
  "responseId": "c0857557-5579-4f5e-8958-9befd7d1d4a8" 5
}
Details
1 items (object[]): 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. NOTE: 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 specify additional fields in the request payload, they’re included here as well.
5 responseId (string): A unique identifier for the response. You can use it to track the response in logs or for debugging.
Important

For more details, see the Passage Retrieval API reference.