---
title: Use the Passage Retrieval API
slug: o86c8334
canonical_url: https://docs.coveo.com/en/o86c8334/
collection: build-a-search-ui
source_format: adoc
---
# Use the Passage Retrieval API
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](https://docs.coveo.com/en/180/).

* **Query pipelines configuration**

This API supports many [query pipeline](https://docs.coveo.com/en/180/) 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](#query-pipeline-feature-support)).

* **[machine learning](https://docs.coveo.com/en/188/) [models](https://docs.coveo.com/en/1012/)**

This API uses Coveo's advanced ML [models](https://docs.coveo.com/en/1012/), such as the [Automatic Relevance Tuning (ART)](https://docs.coveo.com/en/1013/) [model](https://docs.coveo.com/en/1012/), 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](https://docs.coveo.com/en/204/).

## Prerequisites

To use the Passage Retrieval API, make sure:

* You've [created a Passage Retrieval (CPR) model](https://docs.coveo.com/en/oaie5476/) and [associated it with a query pipeline](https://docs.coveo.com/en/oaie6403/).

* The query pipeline that's associated with the [CPR](https://docs.coveo.com/en/oaie9196/) [model](https://docs.coveo.com/en/1012/) **must** also be [associated with a Semantic Encoder (SE) model](https://docs.coveo.com/en/nb8b0088/).

* The [privileges](https://docs.coveo.com/en/228/) for your [CPR](https://docs.coveo.com/en/oaie9196/) [model](https://docs.coveo.com/en/1012/) include the following:

[cols="3",options="header"]
|===
|Service
|Domain
|Required [access level](https://docs.coveo.com/en/2818/)

|Machine Learning
|Allow content preview
|Enable
|===

## Limitations

* Due to the amount of processing required for [embeddings](https://docs.coveo.com/en/ncc87383/), the [CPR](https://docs.coveo.com/en/oaie9196/) [model](https://docs.coveo.com/en/1012/) is subject to [embedding limits](https://docs.coveo.com/en/oaod5329#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](https://docs.coveo.com/en/231/) per second (QPS) rate by half.

* Supported authentication methods are:

** OAuth 2.0

** [API keys](https://docs.coveo.com/en/105/)

** [Platform tokens](https://docs.coveo.com/en/n3ge0020/)

** [Search tokens](https://docs.coveo.com/en/56/)

* By default, the [CPR](https://docs.coveo.com/en/oaie9196/) [model](https://docs.coveo.com/en/1012/) supports only English content.

> **Tip**
>
> Coveo offers beta support for content retrieval in languages other than English.
> Learn more about [multilingual content retrieval and answer generation](https://docs.coveo.com/en/p5ne0024/).

### Query pipeline feature support

The Passage Retrieval API supports many [query pipeline](https://docs.coveo.com/en/180/) features, but some aren't supported or have limitations.

[cols="1,1,2",options="header"]
|===
|Feature
|Support status
|Notes

|[Conditions](https://docs.coveo.com/en/1959/)
|Partial
|Conditions based on `Referrer`, `Recommendation`, and `FacetsFilter` aren't supported.

|[A/B tests](https://docs.coveo.com/en/3255/)
|Not supported
|

|[Groups & Campaigns](https://docs.coveo.com/en/3283/)
|Supported
|

|[Search terms](https://docs.coveo.com/en/3440/)
|Partial
a|* [Stop words](https://docs.coveo.com/en/3406/) are supported.
* [Thesaurus](https://docs.coveo.com/en/3405/) isn't supported.

|[Result ranking](https://docs.coveo.com/en/3234/)
|Supported
|Includes [Featured results](https://docs.coveo.com/en/3376/) and [Ranking expressions](https://docs.coveo.com/en/3375/).

|[Machine learning](https://docs.coveo.com/en/2816/)
|Partial
|The only supported [model](https://docs.coveo.com/en/1012/) is [[Automatic Relevance Tuning (ART)](https://docs.coveo.com/en/3397/)(https://docs.coveo.com/en/1013/)].

|[Advanced](https://docs.coveo.com/en/3409/)
|Partial
a|* [Filters](https://docs.coveo.com/en/3410/) and [Ranking weights](https://docs.coveo.com/en/3412/).
* [Triggers](https://docs.coveo.com/en/3413/) aren't supported.
* Only a subset of [query parameter](https://docs.coveo.com/en/3411/) overrides are supported: `Index`, `LogicalIndex`, `LogicalIndexAggregation`, `MaximumAge`, `Tab`, and `PartialMatch`.
|===

## Request endpoint

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

```http
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](https://docs.coveo.com/en/204/):

[%collapsible]

**Details**

#### ```json

{

  "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"]

  }

}

```


<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]({site-baseurl}/o7qa1002/).

<6> `localization` (object, required): localization parameters

<7> `locale` (string, required): The {locale} for the search.

<8> `timezone` (string): The [tz database identifier](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) 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](https://docs.coveo.com/en/13#tag/Passages-V3).

### 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.

[%collapsible]

**Details**

#### ```json

{

  "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>

}

```


<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]({site-baseurl}/pa9c0434/).  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](https://docs.coveo.com/en/13#tag/Passages-V3).