Documents
Documents tools exposed over the SuperBooks MCP API.
The documents domain exposes 4 tools, 1 of which is destructive.
Destructive tools are hidden from tools/list unless the credential holds
apis.all and the team has enabled destructive AI tools. See
Authentication.
Tools
documents_delete
Scope tier: destructive · Destructive — requires the two-gate check
Permanently delete a document by id. DESTRUCTIVE. Side-effects: (a) all tag assignments for this document are removed; (b) any transaction attachments that reference this document's stored file are also deleted, so the file stops appearing on those transactions; (c) the underlying stored file is permanently deleted. Returns deleted: false if the document was not found for this team — does not throw. Confirm with the user before calling.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | Document id (UUID) to delete. This action is permanent. |
documents_get
Scope tier: read
Fetch one document by id with the full row including OCR-extracted text (body, content), title/summary, tag, language, processing status, and assigned tag IDs. Returns null if not found for the current team.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | Document id (UUID). |
documents_list
Scope tier: read
List documents (uploaded files in the vault) for the current team, newest first. Excludes folder placeholders (*.folderPlaceholder). Supports filter by tag IDs, date range, and a free-text query q (case-insensitive substring match on name only). For phrase, fuzzy, or typo-tolerant text search, use documents_search. Cursor pagination: pass the cursor from the previous page to get the next one.
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string (nullable) | no | Case-insensitive substring match on the document name only. For typo-tolerant full-text search, use documents_search instead. |
tags | array of string (uuid) (nullable) | no | Filter to documents that have ANY of these tag IDs. |
start | string (nullable) | no | Inclusive lower bound on the document's date (YYYY-MM-DD). Both start and end must be provided together to take effect. |
end | string (nullable) | no | Inclusive upper bound on the document's date (YYYY-MM-DD). Both start and end must be provided together to take effect. |
cursor | string (nullable) | no | Pagination cursor from the previous page's cursor. Omit on the first page. |
pageSize | integer | no | Number of documents per page (1-100). Defaults to 20. Default: 20. |
documents_search
Scope tier: read
Full-text search documents by phrase, with substring and typo-tolerant matching on the document name. Use this (not documents_list) when the user asks to find documents by phrase, invoice number, vendor name, etc. — it handles typos and partial matches. Returns one page of results newest first by created_at; pass the returned cursor to fetch more.
| Parameter | Type | Required | Description |
|---|---|---|---|
q | string | yes | Free-text query — words are matched as prefix terms with English-language stemming, plus substring and fuzzy matching on the document name to catch near-miss spellings. |
start | string (nullable) | no | Optional inclusive lower bound on the document's date (YYYY-MM-DD). Both start and end must be provided together to filter by date. |
end | string (nullable) | no | Optional inclusive upper bound on the document's date (YYYY-MM-DD). Both start and end must be provided together to filter by date. |
tags | array of string (uuid) (nullable) | no | Optional list of tag IDs — narrows results to documents that have ANY of these tags assigned. |
cursor | string (nullable) | no | Pagination cursor from the previous page's cursor. Omit on the first page. |
pageSize | integer | no | Number of documents per page (1-100). Defaults to 20. Default: 20. |