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 the entire system. ⚠️ WARNING: method 'delete' permanently deletes documents and requires confirm=true. Select documents either by documents (IDs) or by all: true + filters — Paperless document filter names such as correspondent__id, tags__id__all, document_type__id, title_content, created__date__gte or query (full text); the filter form changes every matching document in one call, e.g. reassigning all documents from a duplicate correspondent before deleting it. Unknown filter keys are refused, and the result reports matched_documents. all=true is not supported for merge, split, delete_pages, edit_pdf or remove_password. Method remove_password strips a PDF password (needs password); with update_document=true the unlocked file is stored as a new version of the same document. Method reprocess accepts remote_ocr=true to use the configured remote OCR engine.

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.

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.

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 PDF was unlocked into a new version, page_count stays null. Don't use page_count to judge whether a document is readable; check its content.

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.

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.

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

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

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 change a field, see create_document_note.

Send a document via email to one or more recipients.

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

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

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.

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

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

⚠️ 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.

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.

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

Create a new tag with optional color, matching pattern, and matching algorithm for automatic document tagging.

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.

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

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.

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

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

Create a new correspondent with optional matching pattern and algorithm for automatic document assignment.

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.

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

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.

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.

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

Create a new document type with optional matching pattern and algorithm for automatic document classification.

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.

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

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.

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.

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

Create a new custom field with a specified data type (string, url, date, boolean, integer, float, monetary, documentlink, or select). For monetary fields, values must use currency code prefix format (e.g., USD10.00, GBP123.45) — NOT trailing symbol format (e.g., 10.00$).

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.

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

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.

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

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

Create a new storage path with a name, path template, and optional matching rules.

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.

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

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

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

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

Create a new saved view with filter rules and sort configuration.

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

⚠️ DESTRUCTIVE: Permanently delete a saved view.

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

Get a specific share link by ID with full details.

Create a share link for a document. Optionally set an expiration date and file version (archive or original). Share links can't be edited afterwards — to change the expiry, delete and recreate. To share several documents as one ZIP link, use create_share_link_bundle.

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

List all share links for a specific document.

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

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

Create ONE public share link for a ZIP of several documents. The ZIP is built in the background: the bundle starts as status 'pending' and becomes usable once get_share_link_bundle reports 'ready'. The slug identifies the public link.

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

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

List all workflow actions with optional pagination.

Get a specific workflow action by ID.

Create ONE standalone workflow action. On its own an action does nothing, and Paperless deletes actions that belong to no workflow whenever any workflow is updated. To build an automation, use create_workflow with the actions inline; to change an action inside a workflow, use update_workflow (or update_workflow_action with the action id from get_workflow).

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.

⚠️ DESTRUCTIVE: Permanently delete a workflow action.

List all workflow triggers with optional pagination.

Get a specific workflow trigger by ID.

Create ONE standalone workflow trigger. On its own a trigger does nothing, and Paperless deletes triggers that belong to no workflow whenever any workflow is updated. To build an automation, use create_workflow with the triggers inline; to change a trigger inside a workflow, use update_workflow (or update_workflow_trigger with the trigger id from get_workflow).

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

⚠️ DESTRUCTIVE: Permanently delete a workflow trigger.

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

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

Create a complete workflow — the automation Paperless actually runs — with its triggers and actions in one call. The workflow runs its actions in order whenever ANY of its triggers matches. Example: strip PDF passwords from API uploads = triggers [{type: 2, sources: [2]}] + actions [{type: 5, passwords: ["secret"]}]. Triggers and actions are given as full objects (same fields as create_workflow_trigger / create_workflow_action). Paperless rejects a remote OCR action (7) without a consumption-started trigger (1), and an apply-AI-suggestions action (8) with only consumption-started triggers.

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.

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

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

Get one mail account by ID (password masked).

Create an IMAP account for Paperless to fetch mail from. Nothing is fetched until a mail rule uses the account (create_mail_rule). Check the connection first with test_mail_account.

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

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

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

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.

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

Get one mail rule by ID.

Create a mail rule on a mail account: which folder and mails to consider, which attachments to import, and what to assign to the resulting documents.

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.

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

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

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.

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 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 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 file metadata for a document including checksums, file sizes, and archival information.

List all notes for a specific document.

Append a user-facing note (comment/annotation) to a document. Notes are separate from the document's searchable 'content' field — to change body text or other metadata fields, use update_document instead.

⚠️ DESTRUCTIVE: Delete a note from a document.

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.

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

Restore documents from the trash back to the system.

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

Get search term autocomplete suggestions based on the document index.

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

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.

Acknowledge/dismiss completed tasks to clear them from the task list.

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

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.

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