Paperless-ngx

⚠️ DESTRUCTIVE: Permanently delete a correspondent from the entire system. This will affect ALL documents that use this correspondent.

⚠️ DESTRUCTIVE: Permanently delete a custom field from the entire system. This will remove the field from ALL documents that use it.

Move a document to trash (soft-delete). The document remains recoverable until the trash is emptied or the retention window expires (~30 days). Use empty_trash for permanent deletion.

⚠️ DESTRUCTIVE: Delete a note from a document.

⚠️ DESTRUCTIVE: Permanently delete a document type from the entire system. This will affect ALL documents that use this type.

⚠️ DESTRUCTIVE: Permanently delete one non-root version of a document. The root (original) version can't be deleted — delete the document instead.

⚠️ DESTRUCTIVE: Permanently delete a mail account and stop fetching from it. Mail rules using it are deleted too. Already-imported documents are not affected.

⚠️ DESTRUCTIVE: Permanently delete a mail rule. Already-imported documents are not affected.

⚠️ DESTRUCTIVE: Permanently delete a saved view.

⚠️ DESTRUCTIVE: Permanently delete a share link. The shared URL will stop working.

⚠️ DESTRUCTIVE: Permanently delete a share link bundle. Its public link stops working; the documents are not affected.

⚠️ DESTRUCTIVE: Permanently delete a storage path from the entire system. This will affect ALL documents that use this storage path.

⚠️ DESTRUCTIVE: Permanently delete a tag from the entire system. This will remove the tag from ALL documents that use it. Use with extreme caution.

⚠️ DESTRUCTIVE: Permanently delete a workflow. Documents it already processed are not changed.

⚠️ DESTRUCTIVE: Permanently delete a workflow action.

⚠️ DESTRUCTIVE: Permanently delete a workflow trigger.

Download a document file by ID. Returns the document as a base64-encoded resource.

Download multiple documents as a ZIP archive. Returns base64-encoded ZIP file.

Manage correspondent objects themselves (permissions, delete). ⚠️ This does NOT assign correspondents to documents — use edit_documents_bulk with method 'set_correspondent' for that. WARNING: 'delete' permanently removes correspondents from the entire system.

Manage custom field definitions themselves (permissions, delete). ⚠️ This does NOT modify custom field values on documents — use edit_documents_bulk with method 'modify_custom_fields' for that. WARNING: 'delete' permanently removes custom fields from the entire system.

Manage document type objects themselves (permissions, delete). ⚠️ This does NOT assign document types to documents — use edit_documents_bulk with method 'set_document_type' for that. WARNING: 'delete' permanently removes document types from the entire system.

Apply ONE of a fixed set of operations to MANY documents at once. Methods: set_correspondent, set_document_type, set_storage_path, add_tag, remove_tag, modify_tags, modify_custom_fields, set_permissions, delete, reprocess, merge, split, rotate, delete_pages, edit_pdf, remove_password. For per-document field edits including title, content, created (date), archive_serial_number, or owner, use update_document instead — those fields are not editable here. Note: 'remove_tag' only removes the tag from the specified documents (tag stays in the system); 'delete_tag' permanently deletes the tag from th…

Manage tag objects themselves (permissions, delete). ⚠️ This does NOT add/remove tags on documents — use edit_documents_bulk with method 'add_tag'/'remove_tag'/'modify_tags' for that. WARNING: 'delete' permanently removes tags from the entire system.

Send a document via email to one or more recipients.

⚠️ DESTRUCTIVE: Permanently delete documents from the trash, or empty the entire trash. This action is irreversible.

Get a specific correspondent by ID with full details including matching rules.

Get a specific custom field by ID with full details including data type and extra configuration.

Get a specific document by ID with full details including correspondent, document type, tags, and custom fields. Note: Document content is excluded from results by default. Use 'get_document_content' to retrieve content when needed. Documents can have several file versions (`versions`; manage them with upload_document_version / update_document_version / delete_document_version). Content (get_document_content) and get_document_metadata follow the LATEST version, but page_count, original_file_name and archived_file_name always describe the ROOT (first) version — e.g. after a password-protected P…

Get LLM-based suggestions for a document: a title, existing correspondents/tags/document types/storage paths (IDs), and suggested_* NAMES for objects that don't exist yet, plus dates. Requires AI to be enabled in Paperless — otherwise it fails with 'AI is required for this feature'. For classifier suggestions that work without AI, use get_document_suggestions.

Get the text content of a specific document by ID. Use this when you need to read or analyze the actual document text. For long documents, read a slice with max_chars (and offset to continue) — e.g. max_chars: 2000 is usually enough to identify a document. Paperless stores the text without page boundaries, so slices are by characters, not pages.

Get the change history / audit log for a document, showing who changed what and when.

Get file metadata for a document including checksums, file sizes, and archival information.

Get a full-page preview image of a document. Returns the preview as a base64-encoded image resource.

Get classifier-based suggestions for a document's correspondent, tags, document type, storage path and dates. Returns IDs of EXISTING objects only. For LLM suggestions that can also propose a title and new objects, use get_document_ai_suggestions.

Get a document thumbnail (image preview) by ID. Returns the thumbnail as a base64-encoded WebP image resource.

Get a specific document type by ID with full details including matching rules.

Everything a document can be filed under, in one call: every tag, correspondent, document type, storage path and custom field (id + name; tags also is_inbox_tag, custom fields also data_type). Call this once before assigning metadata so you choose from the complete set instead of guessing, then use the ids with update_document or edit_documents_bulk. For matching rules or document counts use list_tags / list_correspondents / list_document_types / list_storage_paths.

Get one mail account by ID (password masked).

Get one mail rule by ID.

Get the next available Archive Serial Number (ASN) for document filing.

Get a specific saved view by ID with full details including filter rules.

Get a specific share link by ID with full details.

Get one share link bundle, including its build status (pending → processing → ready or failed), size and last_error.

Get system statistics including document counts, inbox status, file type breakdown, and storage information.

Get a specific storage path by ID with full details including matching rules.

Get Paperless server status: the Paperless-ngx version (pngx_version), install type, storage, and the health of the database, search index, classifier, task queue and last sanity check. Use this to find out which Paperless version you are talking to.

Get a specific tag by ID with full details including matching rules.

Get task counts: all, needs_attention (failed and unacknowledged), in_progress, completed.

Get per-task-type statistics over the last N days: totals, pending/success/failure counts, average duration and wait time, and last run/success/failure times.

Get one workflow by ID, including its full triggers and actions.

Get a specific workflow action by ID.

Get a specific workflow trigger by ID.

List tasks that are pending or running right now (at most 50). For finished tasks use list_tasks.

List all correspondents with optional filtering and pagination. Correspondents represent entities that send or receive documents.

List all custom fields. IMPORTANT: When a user query may refer to a custom field, you should fetch all custom fields up front (with a large enough page_size), cache them for the session, and search locally for matches by name before making further API calls. This reduces redundant requests and handles ambiguity efficiently.

List all notes for a specific document.

List all share links for a specific document.

List all document types. IMPORTANT: When a user query may refer to a document type or tag, you should fetch all document types and all tags up front (get_filing_options returns both, plus correspondents and storage paths, in one call), cache them for the session, and search locally for matches by name or slug before making further API calls. This reduces redundant requests and handles ambiguity between tags and document types efficiently.

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. …

List the IMAP accounts Paperless fetches mail from. Passwords are always masked.

List mail rules: which mails Paperless imports from which account, and how it assigns title, tags, correspondent and document type.

List all saved views with optional pagination. Saved views store filter/sort configurations for quick access.

List share link bundles (one public link to a ZIP of several documents) with optional status filter and pagination.

List all share links with optional filtering by creation date, expiration date, and pagination.

List all storage paths with optional filtering and pagination. Storage paths define where documents are stored on disk.

List all tags. IMPORTANT: When a user query may refer to a tag or document type, you should fetch all tags and all document types up front (get_filing_options returns both, plus correspondents and storage paths, in one call), cache them for the session, and search locally for matches by name or slug before making further API calls. This reduces redundant requests and handles ambiguity between tags and document types efficiently.

List background tasks with their status, type, trigger source and results. Useful for monitoring document consumption and other async operations. Use the filters to narrow the list; `limit` sets how many are returned. For only pending/running tasks use list_active_tasks; for totals use get_task_status_counts or get_task_summary.

List documents in the trash (soft-deleted documents). Document content is left out, as in list_documents.

List all workflow actions with optional pagination.

List all workflow triggers with optional pagination.

List workflows (each with its nested triggers and actions) with optional pagination.

⚠️ Fold other documents into one document as its versions: each document in merge_documents stops existing as a separate document and becomes a version of root_document_id. Use it when the same paper arrived twice (e.g. a scan and a later emailed copy). Runs asynchronously.

Upload a new document file (PDF, image, etc.) to Paperless-NGX with optional metadata. Upload is asynchronous: by default returns a task UUID (use list_tasks to track consumer progress) — the actual document ID is assigned only after the consumer has processed the file. Set poll=true to wait for the consumer to finish and return the final result (the new document_id on success, or the consumer error on failure) in a single call. Optional metadata: title, created (date), correspondent, document_type, storage_path, tags, archive_serial_number, custom_fields.

Fetch mail for one account now and run its rules, instead of waiting for the schedule. Runs in the background; see list_tasks with task_type mail_fetch.

Re-queue a share link bundle's ZIP build, e.g. after it failed or its documents changed. The link (slug) stays the same.

Restore documents from the trash back to the system.

Get search term autocomplete suggestions based on the document index.

Ranked full-text search through Paperless's search index (content, title and metadata). mode 'query' (default) takes advanced syntax — AND/OR/NOT, "quoted phrases", field:value, wildcards*; 'text' takes plain words with no syntax; 'title' searches titles only. The index is updated in the background and can lag behind or miss documents: if you expect matches but get none, use list_documents with `search`, which scans the database directly. For filtering by tag, correspondent, type or date use list_documents. Content is excluded from results; use get_document_content.

Test IMAP connection settings without saving them. Pass the full account fields. To test a SAVED account, pass its `id` together with the masked password exactly as get_mail_account returns it (all asterisks) — Paperless then uses the stored password (without `id` it would try the literal asterisks and report a login failure). Note: Paperless 3.2 answers an unreachable server or refused connection with a bare HTTP 500 rather than a message — treat a 500 as 'could not connect'.

Test a storage path template to see how it would resolve for documents. Useful for validating path templates before creating or updating storage paths.

Update fields on ONE correspondent (PATCH — only fields you supply are changed). Editable fields: name, match (matching pattern), matching_algorithm, is_insensitive. To assign this correspondent to documents, use edit_documents_bulk with method 'set_correspondent' or update_document instead.

Update fields on ONE custom field definition (PATCH — only fields you supply are changed). Editable fields: name, data_type, extra_data. ⚠️ Changing data_type on a field that already has values on documents may render those values invalid or unreadable — change data_type only on unused fields. To set a custom-field VALUE on a document, use update_document or edit_documents_bulk with method 'modify_custom_fields' instead.

Update fields on ONE document (PATCH — only fields you supply are changed). To change tags, prefer add_tags / remove_tags: they leave the other tags alone. `tags` REPLACES the whole list — any tag you leave out is removed. Every tag change returns tag_changes {added, removed}. Editable fields: title, correspondent, document_type, storage_path, tags, add_tags, remove_tags, content (raw searchable text), created (document date, YYYY-MM-DD), archive_serial_number, owner, custom_fields. For applying the same change to MANY documents, see edit_documents_bulk. To add a comment/annotation rather than…

Update fields on ONE document type (PATCH — only fields you supply are changed). Editable fields: name, match (matching pattern), matching_algorithm, is_insensitive. To assign this document type to documents, use edit_documents_bulk with method 'set_document_type' or update_document instead.

Rename a version of a document (change its version_label). Version IDs are listed in get_document's `versions`.

Update fields on ONE mail account (PATCH — only fields you supply are changed). Omit password to keep the stored one.

Update fields on ONE mail rule (PATCH — only fields you supply are changed). E.g. switch assign_correspondent_from to 4 to stop creating a correspondent per sender.

Update fields on ONE saved view (PATCH — only fields you supply are changed). Editable fields: name, show_on_dashboard, show_in_sidebar, sort_field, sort_reverse, filter_rules. Supplying filter_rules replaces the entire rule array (not a merge).

Update fields on ONE storage path (PATCH — only fields you supply are changed). Editable fields: name, path (path template), match (matching pattern), matching_algorithm, is_insensitive. To assign this storage path to documents, use edit_documents_bulk with method 'set_storage_path' or update_document instead.

Update fields on ONE tag (PATCH — only fields you supply are changed). Editable fields: name, color, match (matching pattern), matching_algorithm, is_insensitive, parent (parent tag ID for hierarchy). To add or remove this tag on documents, use edit_documents_bulk with method 'add_tag' / 'remove_tag' / 'modify_tags' instead.

Update ONE workflow (PATCH). name/order/enabled change only when passed. ⚠️ `triggers` and `actions`, when passed, REPLACE the workflow's whole list: entries with an `id` update that existing item, entries without an `id` are created, and existing items you leave out are DELETED. To edit one action, call get_workflow first and send back the complete list with your change.

Update fields on ONE workflow action (PATCH — only fields you supply are changed). Use get_workflow_action first to see its current shape. To change the actions of a whole workflow, see update_workflow.

Update fields on ONE workflow trigger (PATCH — only fields you supply are changed). Use get_workflow_trigger first to see its current shape.

Add a new file version to an EXISTING document instead of creating a new document — e.g. a corrected scan, a signed copy, or an unlocked PDF. The new file becomes the current version: content, search and downloads follow it, and earlier versions stay listed in the document's `versions` (see get_document). Processing is asynchronous like post_document; set poll=true to wait. To strip a PDF password you don't need to re-upload: use edit_documents_bulk method remove_password with update_document=true.