---
title: "Search the archive"
method: GET
path: "/api/v1/rest/documents"
tags: ["Documents"]
---

# Search the archive

`GET /api/v1/rest/documents`

## Request

- Base URL: `https://api.custodo.ai`
- URL: `https://api.custodo.ai/api/v1/rest/documents`
- Auth: HTTP bearer

Find documents. Combines free text, document type, direction, pipeline status, a date window and metadata field filters in ONE call — prefer it over listing everything and filtering yourself. Free text is ranked and matches the title, the extracted fields and the converted body; the last word is treated as a prefix, so a half-typed word still matches. With free text each document carries `page`: the page of the file the words are on (null when the file has no pages) — cite it, and read around it with documents_get_content. Every document carries `untrusted_summary`: two or three lines on what it is (who, what, about what), written when it was processed — read the summaries to pick the right document, and to say what a document is without opening it; null until it has been processed. Returns at most 100 rows per call; page with `cursor`. Prefer several narrow searches over one broad one.

**Examples**

- Find the invoices from Rossi over €5.000 last quarter
  `GET /api/v1/rest/documents?type=fattura_entrata&from=2026-04-01&to=2026-06-30&metadata=%5B%7B%22field%22%3A%22fornitore%22%2C%22op%22%3A%22contains%22%2C%22kind%22%3A%22text%22%2C%22value%22%3A%22Rossi%22%7D%2C%7B%22field%22%3A%22totale%22%2C%22op%22%3A%22gt%22%2C%22kind%22%3A%22number%22%2C%22value%22%3A5000%7D%5D`
- What did we file about the Bianchi contract?
  `GET /api/v1/rest/documents?query=contratto+Bianchi`

## Query parameters

- `query` string
- `type` string
- `direction` 'in_entrata' | 'in_uscita'
- `status` 'pending' | 'converting' | 'extracting' | 'indexing' | 'ready' | 'failed'
- `from` string
- `to` string
- `legal_hold` boolean
- `limit` integer
- `cursor` string
- `response_format` 'concise' | 'detailed'

## Headers

- `X-Tenant-Id` string, uuid

## Response `200`

Done. `data` is the tool’s own answer.

- RestResult
  - `ok` true, required
  - `data` unknown, required

## Other responses

- `400`: The arguments did not validate: `error.message` names the field, what it expects and what arrived.
- `401`: No API key, or one that is malformed, unknown, revoked or expired.
- `403`: The call never ran: the module is off for this organisation, the credential lacks the permission or the module, the tier does not cover it, or the tool is destructive and the key was not minted for that.
- `422`: The tool ran and refused, in a sentence of its own (`TOOL_REFUSED`): the message says what to change. Retrying the same call will not help.
- `429`: The API key has spent its minute, or its day. Every request a key makes counts. See `Retry-After`.

---

[API](https://skmtc.dev/custodo/apis/custodo-integrazioni.md) · [All operations](https://skmtc.dev/custodo/apis/custodo-integrazioni/llms.txt) · [OpenAPI document](https://skmtc.dev/custodo/apis/custodo-integrazioni/revisions/16d336d3ec2a?raw)