Use the Passage Retrieval API

This is for:

Developer

The Passage Retrieval API (PR API) allows developers to extract specific sections of text from documents stored in Coveo, enabling efficient retrieval of ranked textual 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 (passages) of information from documents, enhancing the accuracy and relevance of responses generated by LLMs.

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

Prerequisites

To use the Passage Retrieval API, make sure:

  • You created a Coveo Passage Retrieval (CPR) model associated with a query pipeline. The creation process is similar to creating an RGA model.

  • The privileges for your CPR model include the following:

    Service Domain Required access level

    Machine Learning

    Allow content preview

    Enable

    Search

    View all content

    Allowed

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.

  • Currently, PR API only supports English language. Once it’s changed, 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/alpha/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:

{
  "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
}
Details
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.
Important

For more details, see the Search 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",
        "permanentId": "permanentId",
        "clickableUri": "https://example.com/search/document-solar-energy"
      }
    },
    {
      // another item
    }
  ]
}
Details
1 items (array of objects): The array of passages.
2 text (string): Text content of the passage.
3 relevanceScore (number): The relevance score of the passage.
4 document (object): The document that contains this passage.
Important

For more details, see the Search API reference.