API Reference

Beta

Retrieval

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Retrieve

RetrievalRetrieveResponse Beta.Retrieval.Retrieve(RetrievalRetrieveParamsparameters, CancellationTokencancellationToken = default)

POST/api/v1/retrieval/retrieve

Retrieve relevant chunks via hybrid search (vector + full-text), with filtering on built-in or user-defined metadata.

ParametersExpand Collapse

RetrievalRetrieveParams parameters

required string indexID

Body param: ID of the index to retrieve against.

required string query

Body param: Natural-language query to retrieve relevant chunks.

string? organizationID

Query param

formatuuid

string? projectID

Query param

formatuuid

IReadOnlyDictionary<string, CustomFilter?>? customFilters

Body param: Filters on user-defined metadata fields.

class FilterTypeUnionStrIntBoolFloat:

required Operator Operator

One of the following:

"eq"Eq

"gt"Gt

"gte"Gte

"in"In

"lt"Lt

"lte"Lte

"ne"Ne

"nin"Nin

required Value Value

One of the following:

string

Boolean

Double

IReadOnlyList<UnnamedSchemaWithArrayParent0>

One of the following:

string

Boolean

Double

IReadOnlyList<FilterTypeUnionIntFloat>

required Operator Operator

One of the following:

"eq"Eq

"gt"Gt

"gte"Gte

"in"In

"lt"Lt

"lte"Lte

"ne"Ne

"nin"Nin

required Value Value

One of the following:

Double

IReadOnlyList<Double>

Double? fullTextPipelineWeight

Body param: Weight of the full-text search pipeline (0-1).

Long? numCandidates

Body param: Number of candidates for approximate nearest neighbor search.

Rerank rerank

Body param: Reranking configuration applied after hybrid search. Enabled by default.

Boolean Enabled

Set to false to disable reranking.

Long? TopN

Number of results to return after reranking.

Double? scoreThreshold

Body param: Minimum score threshold for returned results.

StaticFilters? staticFilters

Body param: Filters on built-in document fields (page range, chunk index, etc.).

ParsedDirectoryFileID? ParsedDirectoryFileID

required Operator Operator

One of the following:

"eq"Eq

"gt"Gt

"gte"Gte

"in"In

"lt"Lt

"lte"Lte

"ne"Ne

"nin"Nin

required Value Value

One of the following:

string

IReadOnlyList<string>

Long? topK

Body param: Maximum number of results to return.

Double? vectorPipelineWeight

Body param: Weight of the vector search pipeline (0-1).

ReturnsExpand Collapse

class RetrievalRetrieveResponse:

Response containing retrieval results.

required IReadOnlyList<Result> Results

Ordered list of retrieved chunks.

required string Content

Text content of the retrieved chunk.

IReadOnlyDictionary<string, Metadata>? Metadata

User-defined metadata associated with the chunk.

One of the following:

string

Long

Double

Boolean

JsonElement

IReadOnlyList<string>

Double? RerankScore

Relevance score from the reranker, if reranking was applied.

Double? Score

Hybrid search relevance score.

StaticFields StaticFields

Built-in fields stored for every exported chunk.

IReadOnlyList<Attachment> Attachments

Attachments associated with the chunk

required string AttachmentName

Attachment-relative path, e.g. ‘screenshots/page_7.jpg’.

required string SourceID

File ID to pass as source_id when fetching the attachment.

required string Type

Attachment kind, e.g. ‘screenshot’, ‘items’.

Long? ChunkEndChar

End character offset of the chunk.

Long? ChunkIndex

Index of the chunk within the file.

Long? ChunkStartChar

Start character offset of the chunk.

Long? ChunkTokenCount

Token count of the chunk.

Long? PageRangeEnd

Last page number covered by this chunk.

Long? PageRangeStart

First page number covered by this chunk.

string? ParsedDirectoryFileID

ID of the parsed file.

Retrieve

C#

HTTP

TypeScript

Python

Go

Java

C#

CLI Tool

RetrievalRetrieveParams parameters = new()
{
    IndexID = "idx-abc123",
    Query = "What are the key findings?",
};

var retrieval = await client.Beta.Retrieval.Retrieve(parameters);

Console.WriteLine(retrieval);

200 example

{
  "results": [
    {
      "content": "content",
      "metadata": {
        "foo": "string"
      },
      "rerank_score": 0,
      "score": 0,
      "static_fields": {
        "attachments": [
          {
            "attachment_name": "attachment_name",
            "source_id": "source_id",
            "type": "type"
          }
        ],
        "chunk_end_char": 0,
        "chunk_index": 0,
        "chunk_start_char": 0,
        "chunk_token_count": 0,
        "page_range_end": 0,
        "page_range_start": 0,
        "parsed_directory_file_id": "parsed_directory_file_id"
      }
    }
  ]
}

Returns Examples

200 example

{
  "results": [
    {
      "content": "content",
      "metadata": {
        "foo": "string"
      },
      "rerank_score": 0,
      "score": 0,
      "static_fields": {
        "attachments": [
          {
            "attachment_name": "attachment_name",
            "source_id": "source_id",
            "type": "type"
          }
        ],
        "chunk_end_char": 0,
        "chunk_index": 0,
        "chunk_start_char": 0,
        "chunk_token_count": 0,
        "page_range_end": 0,
        "page_range_start": 0,
        "parsed_directory_file_id": "parsed_directory_file_id"
      }
    }
  ]
}