# Retrieval

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

### Parameters

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

  - `string? projectID`

    Query param

  - `IReadOnlyDictionary<string, CustomFilter?>? customFilters`

    Body param: Filters on user-defined metadata fields.

    - `class FilterTypeUnionStrIntBoolFloat:`

      - `required Operator Operator`

        - `"eq"Eq`

        - `"gt"Gt`

        - `"gte"Gte`

        - `"in"In`

        - `"lt"Lt`

        - `"lte"Lte`

        - `"ne"Ne`

        - `"nin"Nin`

      - `required Value Value`

        - `string`

        - `Boolean`

        - `Double`

        - `IReadOnlyList<UnnamedSchemaWithArrayParent0>`

          - `string`

          - `Boolean`

          - `Double`

    - `IReadOnlyList<FilterTypeUnionIntFloat>`

      - `required Operator Operator`

        - `"eq"Eq`

        - `"gt"Gt`

        - `"gte"Gte`

        - `"in"In`

        - `"lt"Lt`

        - `"lte"Lte`

        - `"ne"Ne`

        - `"nin"Nin`

      - `required Value Value`

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

        - `"eq"Eq`

        - `"gt"Gt`

        - `"gte"Gte`

        - `"in"In`

        - `"lt"Lt`

        - `"lte"Lte`

        - `"ne"Ne`

        - `"nin"Nin`

      - `required Value Value`

        - `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).

### Returns

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

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

### Example

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

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

Console.WriteLine(retrieval);
```

#### Response

```json
{
  "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"
      }
    }
  ]
}
```

## Find Files

`RetrievalFindPageResponse Beta.Retrieval.Find(RetrievalFindParamsparameters, CancellationTokencancellationToken = default)`

**post** `/api/v1/retrieval/files/find`

Search for files by name.

### Parameters

- `RetrievalFindParams parameters`

  - `required string indexID`

    Body param: ID of the index to search within.

  - `string? organizationID`

    Query param

  - `string? projectID`

    Query param

  - `string? fileName`

    Body param: Exact file name to match.

  - `string? fileNameContains`

    Body param: Substring match on file name (case-insensitive).

  - `Long? pageSize`

    Body param: The maximum number of items to return. The service may return fewer than this value. If unspecified, a default page size will be used. The maximum value is typically 1000; values above this will be coerced to the maximum.

  - `string? pageToken`

    Body param: A page token, received from a previous list call. Provide this to retrieve the subsequent page.

### Returns

- `class RetrievalFindPageResponse:`

  Paginated file find results.

  - `required IReadOnlyList<RetrievalFindResponse> Items`

    The list of items.

    - `required string FileID`

      ID of the file.

    - `required string FileName`

      Display name of the file.

  - `string? NextPageToken`

    A token, which can be sent as page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.

  - `Long? TotalSize`

    The total number of items available. This is only populated when specifically requested. The value may be an estimate and can be used for display purposes only.

### Example

```csharp
RetrievalFindParams parameters = new() { IndexID = "idx-abc123" };

var page = await client.Beta.Retrieval.Find(parameters);
await foreach (var item in page.Paginate())
{
    Console.WriteLine(item);
}
```

#### Response

```json
{
  "items": [
    {
      "file_id": "file_id",
      "file_name": "file_name"
    }
  ],
  "next_page_token": "next_page_token",
  "total_size": 0
}
```

## Grep File

`RetrievalGrepPageResponse Beta.Retrieval.Grep(RetrievalGrepParamsparameters, CancellationTokencancellationToken = default)`

**post** `/api/v1/retrieval/files/grep`

Grep within a file's parsed content using a regex pattern.

### Parameters

- `RetrievalGrepParams parameters`

  - `required string fileID`

    Body param: ID of the file to grep.

  - `required string indexID`

    Body param: ID of the index the file belongs to.

  - `required string pattern`

    Body param: Regex pattern to search for.

  - `string? organizationID`

    Query param

  - `string? projectID`

    Query param

  - `Long? contextChars`

    Body param: Number of characters of context to include before and after the matched pattern in the content field of the response

  - `Long? pageSize`

    Body param: The maximum number of items to return. The service may return fewer than this value. If unspecified, a default page size will be used. The maximum value is typically 1000; values above this will be coerced to the maximum.

  - `string? pageToken`

    Body param: A page token, received from a previous list call. Provide this to retrieve the subsequent page.

### Returns

- `class RetrievalGrepPageResponse:`

  Paginated grep results for a file.

  - `required IReadOnlyList<RetrievalGrepResponse> Items`

    The list of items.

    - `required string Content`

      Matched text content.

    - `required Long EndChar`

      End character offset of the match.

    - `required Long StartChar`

      Start character offset of the match.

  - `string? NextPageToken`

    A token, which can be sent as page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.

  - `Long? TotalSize`

    The total number of items available. This is only populated when specifically requested. The value may be an estimate and can be used for display purposes only.

### Example

```csharp
RetrievalGrepParams parameters = new()
{
    FileID = "file_id",
    IndexID = "idx-abc123",
    Pattern = "revenue|profit",
};

var page = await client.Beta.Retrieval.Grep(parameters);
await foreach (var item in page.Paginate())
{
    Console.WriteLine(item);
}
```

#### Response

```json
{
  "items": [
    {
      "content": "content",
      "end_char": 0,
      "start_char": 0
    }
  ],
  "next_page_token": "next_page_token",
  "total_size": 0
}
```

## Read File

`RetrievalReadResponse Beta.Retrieval.Read(RetrievalReadParamsparameters, CancellationTokencancellationToken = default)`

**post** `/api/v1/retrieval/files/read`

Read the parsed text content of a specific file.

### Parameters

- `RetrievalReadParams parameters`

  - `required string fileID`

    Body param: ID of the file to read.

  - `required string indexID`

    Body param: ID of the index the file belongs to.

  - `string? organizationID`

    Query param

  - `string? projectID`

    Query param

  - `Long? maxLength`

    Body param: Maximum number of characters to read from the offset.

  - `Long offset`

    Body param: Starting character offset.

### Returns

- `class RetrievalReadResponse:`

  File read result.

  - `required string Content`

    Parsed text content of the file.

### Example

```csharp
RetrievalReadParams parameters = new()
{
    FileID = "file_id",
    IndexID = "idx-abc123",
};

var response = await client.Beta.Retrieval.Read(parameters);

Console.WriteLine(response);
```

#### Response

```json
{
  "content": "content"
}
```