---
title: "List documents"
method: GET
path: "/v1/default/banks/{bank_id}/documents"
tags: ["Documents"]
---

# List documents

`GET /v1/default/banks/{bank_id}/documents`

## Request

- Base URL: `https://hindsight.vectorize.io` (the document declares no server; this is the origin it was published from)
- URL: `https://hindsight.vectorize.io/v1/default/banks/{bank_id}/documents`
- Auth: none declared
- TypeScript: <https://skmtc.dev/vectorize/apis/hindsight-http-api/docs/v1/default/banks/:bank_id/documents/get.ts> (a function with typed inputs; its response is checked against the schema)

List documents with pagination, optional search, and an optional time window. Most recently written first (`updated_at` descending) unless `time_field` selects another axis. Documents are the source content from which memory units are extracted.

## Path parameters

- `bank_id` string, required

## Query parameters

- `q` string, nullable: Case-insensitive substring filter on document ID or document text (e.g. 'report' matches 'report-2024' or any document containing 'report'). Meant for browsing and inspection, not for high-volume or latency-sensitive workloads — use recall for that. Matches are capped: past the cap, `total` is a lower bound and `total_is_estimate` is true. A store-owned backend may match approximately; each item's `matched_fields` says what matched.
- `tags` string[], nullable: Filter documents by tags
- `tags_match` 'any' | 'all' | 'any_strict' | 'all_strict' | 'exact': How to match tags: 'any', 'all', 'any_strict', 'all_strict', 'exact'
- `time_field` 'created_at' | 'updated_at', nullable: Time axis to filter and order by: `created_at` (when the document first arrived) or `updated_at` (its last write, the default ordering). Filtering and ordering both follow `time_field`, and rows with no value on that column are excluded — so `total` counts only rows carrying that timestamp, and can be 0 on a bank that is not empty.
- `start_date` string, nullable: Filter from this ISO datetime (inclusive)
- `end_date` string, nullable: Filter until this ISO datetime (exclusive)
- `limit` integer
- `offset` integer

## Headers

- `authorization` string, nullable

## Response `200`

Successful Response

- ListDocumentsResponse: Response model for list documents endpoint.
  - `items` DocumentListItem[], required
    - `id` string, required: Document ID
    - `bank_id` string: Bank the document belongs to
    - `content_hash` string, nullable: Hash of the document text, for idempotent retain
    - `created_at` string: When the document was first retained (ISO 8601)
    - `updated_at` string: When the document was last written (ISO 8601)
    - `text_length` integer: Length of the stored document text in characters
    - `memory_unit_count` integer: Number of memory units extracted from this document
    - `retain_params` object, nullable: Parameters used during retain
    - `document_metadata` object, nullable: Document metadata
    - `tags` string[]: Tags associated with this document
    - `matched_fields` string[]: Which fields matched the `q` search: 'id', 'original_text', or both. Empty when no `q` is given.
  - `total` integer, required
  - `limit` integer, required
  - `offset` integer, required
  - `total_is_estimate` boolean: True when a `q` search stopped at its match cap, so `total` is a lower bound rather than an exact count. Always false without `q`.

## Other responses

- `404`: The bank does not exist.
- `422`: Validation Error

## Changes

- **2026-11-07** `45e711cd0897`: 1 breaking, 7 info
  - the `query` request parameter `tags_match` was restricted to a list of enum values
  - added the new enum value `all` to the `query` request parameter `tags_match`
  - added the new enum value `all_strict` to the `query` request parameter `tags_match`
  - added the new enum value `any` to the `query` request parameter `tags_match`
  - …4 more
- **2026-10-04** `4fda98b75f63`: 3 warning, 14 info
  - for the `query` request parameter `limit`, the min was set to `0.00`
  - for the `query` request parameter `offset`, the min was set to `0.00`
  - removed the optional property `detail/items/url` from the response with the `422` status
  - added the new optional `query` request parameter `end_date`
  - …13 more
- **2026-05-15** `0d08f271b9db`: 3 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status
  - added the optional property `detail/items/url` to the response with the `422` status

[Operation history](https://skmtc.dev/vectorize/apis/hindsight-http-api/changes/v1/default/banks/:bank_id/documents/get.md)

---

[API](https://skmtc.dev/vectorize/apis/hindsight-http-api.md) - [All operations](https://skmtc.dev/vectorize/apis/hindsight-http-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vectorize/apis/hindsight-http-api/revisions/45e711cd0897?raw)