list_documents
List and filter Paperless-NGX documents by title, correspondent, tag, document type, storage path, or date. Use field IDs for accurate searches instead of free-text.
Instructions
List and filter documents by fields such as title, correspondent, document type, tag, storage path, creation date, and more. IMPORTANT: For queries like 'the last 3 contributions' or when searching by tag, correspondent, document type, or storage path, you should FIRST look up the correct ID — get_filing_options returns every tag, correspondent, document type and storage path in one call (or use list_tags / list_correspondents / list_document_types / list_storage_paths) — and then use that ID as a filter here. Only use the 'search' argument for free-text search when no specific field applies. Using the correct ID filter will yield much more accurate results. Note: Document content is excluded from results by default. Use 'get_document_content' to retrieve content when needed. To find near-duplicates of one document use more_like_id; to list everything Paperless has flagged as a duplicate use has_duplicates=true.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Only these document IDs — read several known documents in one call | |
| tag | No | ||
| page | No | Page number (1-based) | |
| fields | No | Return only these fields to keep the response small, e.g. ["title", "tags"]. id is always included. | |
| search | No | Case-insensitive substring match on title, correspondent name and content, read straight from the database (always current, unranked); every word must appear. For ranked full-text search with query syntax use search_documents. | |
| ordering | No | ||
| page_size | No | Number of items per page | |
| more_like_id | No | Find documents similar to the document with this ID | |
| storage_path | No | ||
| correspondent | No | ||
| document_type | No | ||
| has_duplicates | No | true = only documents Paperless flagged as possible duplicates (the same file as another document); false = only documents without. get_document lists the matching documents in duplicate_documents (list results leave that field empty). | |
| created__date__gte | No | ||
| created__date__lte | No | ||
| custom_field_query | No | Custom-field filter as a JSON expression passed as a string. A condition is [field, operator, value], where field is the custom field's name or ID. Combine conditions with ["AND", [cond, …]] or ["OR", [cond, …]], and negate with ["NOT", cond]. Valid operators depend on the field's data type (e.g. exact, in, isnull, exists, icontains, gt, gte, lt, lte, range); pick an invalid one and Paperless names the valid ones. Examples: '["Amount", "gte", 100]', '["AND", [["Due", "lt", "2026-10-01"], ["Paid", "exact", false]]]'. |