Search the archive
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
Request
- Base URL: https://api.custodo.ai
- URL: https://api.custodo.ai/api/v1/rest/documents
- Auth: HTTP bearer
Query parameters
Free text. Quoted phrases, or and a leading - all work. Omit to browse.
Document type, by its key (fattura_entrata) or its Italian name.
in_entrata for received documents, in_uscita for issued ones.
Pipeline state. ready is a document that finished processing.
Filed on or after this day (inclusive).
Filed on or before this day (inclusive).
Filters over EXTRACTED fields. field is a metadata key from the document type (call documents_list_types to see them). Use kind: "number" to compare numerically — a text comparison on an amount sorts "9" above "10".
Only documents under legal hold, or only those not.
Rows to return, 1–100. Default 20.
Opaque cursor from a previous call’s nextCursor, to continue.
concise (default) returns the fields you need to answer a question; detailed adds related records and costs more context.
Headers
The organisation to act in. An API key is bound to exactly one, so this is optional for a key and must match the one it was minted for.
Response
Done. data is the tool’s own answer.
Changes
No recorded changes to this operation across all 1 revision of this API.