Leina 
Wanta 
Summarize Archived Documents
Search the archive and read extracted text from selected documents.
/oo Paperless-ngx: Search documents for [query], read document [ID] and summarize its extracted text.
Connect Paperless-ngx to Your AI Agent
Use AI with Paperless-ngx to search archived documents, summarize extracted text and update document metadata.
139 tools API key
Try a Paperless-ngx Task
Copy a prompt into your agent with the oo Skill installed. Add your page links and source notes before running it.
oo Skill Paperless-ngx
Organize Document Metadata
Read current metadata before applying specified title or classification changes.
/oo Paperless-ngx: Read document [ID], then set title [title] and complete tag list [tag IDs].
Retrieve an Archived File
Download a document as a temporary connector file URL.
/oo Paperless-ngx: Get a download URL for document [ID], using its original upload.
Start Working with Paperless-ngx
-
Install OOMOL
Set up oo CLI and the oo Skill in your agent.
Install OOMOL → -
Connect Paperless-ngx
Provide your Paperless-ngx API token and public instance URL.
Connect Paperless-ngx → -
Give Your Agent a Task
Use /oo with the pages to read, the changes to make, and where to save the result.
Connection Guide →
Choose Your Agent
- Paperless-ngx 3.0 or newer serving API version 10, with document view or change permissions.
- Use one search-index query mode per call. Updating tags or custom fields replaces their entire list.
Paperless-ngx Tools
Use AI with Paperless-ngx to search archived documents, summarize extracted text and update document metadata.
Summarize Archived Documents
Search the archive and read extracted text from selected documents.
Organize Document Metadata
Read current metadata before applying specified title or classification changes.
Retrieve an Archived File
Download a document as a temporary connector file URL.
139 tools
List Documents
List or search documents visible to the connected user, 25 per page by default. Filters mirror the Paperless-ngx query parameters: id, title, archive serial number, dates, correspondent, document type, storage path, tags, owner, custom fields, MIME type and content lookups can be combined; anything not modelled goes into additional_filters. query, text, title_search and more_like_id run a search-index query instead, returning results with __search_hit__ ordered by relevance, and only one of them may be used per call. Only root documents are listed; file versions appear inside each document's versions array. Requires the view_document permission.
paperless_ngx.list_documents Get Document
Get one document with its metadata, tags, custom fields, notes, file versions and duplicate_documents (other documents sharing the same checksum). content holds the extracted text of the latest version unless version selects another one. Requires the view_document permission and view access to the document.
paperless_ngx.get_document Update Document
Partially update a document: title, content, correspondent, document type, storage path, tags, creation date, archive serial number, custom fields, inbox tag removal, owner and object permissions. Only the provided fields are sent (PATCH); tags and custom_fields replace the whole list. Changing owner or set_permissions requires being the owner or a superuser. The response carries the full permissions object. Requires the change_document permission and change access to the document.
paperless_ngx.update_document Delete Document
Move a document and all of its file versions to the trash. Trashed documents stay restorable until the configured trash delay (30 days by default) expires and are removed from the search index immediately. Requires the delete_document permission and delete access to the document.
paperless_ngx.delete_document Get Document Root
Resolve the root document of any document id, including ids of file versions and trashed documents. For a root document the answer is its own id. Requires view access to the root document.
paperless_ngx.get_document_root Get Document Metadata
Get file-level metadata of a document: checksums, sizes, MIME type, media file names, whether an archived PDF exists, parser metadata (such as PDF info and XMP fields) of the original and archived files, and the detected content language. Reads the latest version unless version is given. Requires view access to the document.
paperless_ngx.get_document_metadata Get Document Suggestions
Get correspondent, tag, document type, storage path and date suggestions for a document from the matching rules and the trained classifier. Results are cached until the document or classifier changes. Requires change access to the document (403 otherwise).
paperless_ngx.get_document_suggestions Get Document Ai Suggestions
Ask the configured language model for a title, tags, correspondent, document type, storage path and dates for a document. Existing objects the model picked are returned as ids, new names it proposed are returned separately. Requires AI to be enabled on the instance: otherwise Paperless-ngx answers 400 AI is required for this feature, an invalid AI configuration yields 400 and a model timeout yields 503. The call blocks while the model answers, and requires change access to the document.
paperless_ngx.get_document_ai_suggestions Download Document
Download the file of a document and hand it back as a temporary connector file URL. By default the archived PDF is served when it exists, otherwise the original upload; original=true always serves the original. The preview endpoint of Paperless-ngx serves exactly the same bytes with an inline disposition, so it is not exposed as a separate action. Works for trashed documents and file versions. Requires view access to the document; files above 200 MiB are rejected.
paperless_ngx.download_document Get Document Thumbnail
Download the WebP thumbnail of a document (or of one of its file versions) and hand it back as a temporary connector file URL. Requires view access to the document.
paperless_ngx.get_document_thumbnail List Document Notes
List the notes attached to a document, newest first, each with its author. Requires the view_note permission and view access to the document.
paperless_ngx.list_document_notes Add Document Note
Add a note to a document on behalf of the connected user and return the complete note list. Also bumps the document's modified timestamp and re-indexes it. Requires the add_note permission and change access to the document.
paperless_ngx.add_document_note Delete Document Note
Delete one note from a document and return the remaining notes. Requires the delete_note permission and change access to the document; a note id that does not belong to the document yields 404.
paperless_ngx.delete_document_note List Document Share Links
List the share links of a document that have not expired yet, newest first. Requires change access to the document (Paperless-ngx treats reading share links as a sharing operation).
paperless_ngx.list_document_share_links Get Document History
Get the audit trail of a document: every logged create, update, delete and access entry for the document and its custom field values, newest first, with the changed fields and the acting user. Requires the audit log to be enabled on the instance (PAPERLESS_AUDIT_LOG_ENABLED, otherwise 400 Audit log is disabled), the auditlog.view_logentry permission, and the connected user must own the document, be a superuser, or the document must be unowned.
paperless_ngx.get_document_history Email Document
Send one document as an email attachment through the mail server configured on the Paperless-ngx instance. The archived PDF is attached when it exists unless use_archive_version is false. Paperless-ngx routes this through its collection email endpoint with a single document id. Requires the view_document permission, view access to the document and a configured outgoing mail server (otherwise a 500 Error emailing documents).
paperless_ngx.email_document Email Documents
Send several documents as attachments of one email through the mail server configured on the Paperless-ngx instance. Archived PDFs are attached when they exist unless use_archive_version is false. Requires the view_document permission, view access to every document (403 otherwise) and a configured outgoing mail server (otherwise a 500 Error emailing documents).
paperless_ngx.email_documents Update Document Version
Upload a new file version for a document. The connector downloads fileUrl server side and posts it as multipart form field document; Paperless-ngx consumes it in the background as a new version of the root document, keeping title, tags and other metadata shared. Returns the Celery task id to poll with get_task. Requires the change_document permission and change access to the root document; unsupported file types are rejected with 400.
paperless_ngx.update_document_version Delete Document Version
Permanently delete one non-root file version of a document. The root (original) version cannot be deleted this way; delete the document instead (400 otherwise). Requires delete access to the root document.
paperless_ngx.delete_document_version Update Document Version Label
Set or clear the label of one file version of a document, including the root version. Requires change access to the root document.
paperless_ngx.update_document_version_label Get Next Asn
Get the next free archive serial number: the highest ASN currently in use plus one, or 1 when none is assigned. Trashed documents keep their ASN reserved.
paperless_ngx.get_next_asn Upload Document
Upload a file for consumption as a new document. The connector downloads fileUrl server side (at most 100 MiB) and posts it as multipart form field document together with the optional title, creation date, correspondent, document type, storage path, tags, archive serial number and custom field values. Paperless-ngx sniffs the file type from the bytes and rejects unsupported types with 400; consumption (OCR, matching, workflows) runs in the background, so the action returns the Celery task id to poll with get_task, whose result_data.document_id identifies the new document once it succeeded. The connected user becomes the owner. Requires the add_document permission.
paperless_ngx.upload_document Bulk Edit Documents
Apply one metadata change to many documents at once: set the correspondent, document type or storage path, add or remove tags, add or remove custom fields, or replace owner and permissions. Select documents explicitly or with all plus filters. Metadata methods require the global change_document permission plus change access on every document; set_permissions additionally requires that the connected user owns every document (or it is unowned) unless they are a superuser. Legacy document-editing methods (delete, reprocess, rotate, merge, split, delete_pages, edit_pdf, remove_password) are still accepted but deprecated; use the dedicated actions instead.
paperless_ngx.bulk_edit_documents Delete Documents
Move documents to the trash (soft delete). Versions of a selected root document are trashed with it. Trashed documents can be listed with list_trash and brought back with restore_trash_documents until the trash is emptied, which happens automatically after the instance's trash delay (30 days by default). Requires the global change_document permission plus change access on every selected document (403 Insufficient permissions otherwise); superusers bypass these checks. Also requires the global delete_document permission and that the connected user owns every document (or it is unowned).
paperless_ngx.delete_documents Reprocess Documents
Re-run parsing (text extraction, OCR and archive PDF generation) for documents from their original files. Each document is queued as a separate background task and its content and archive file are replaced when the task finishes; the response is OK as soon as the tasks are queued. Requires the global change_document permission plus change access on every selected document (403 Insufficient permissions otherwise); superusers bypass these checks.
paperless_ngx.reprocess_documents Rotate Documents
Rotate every page of the selected PDF documents by the given number of degrees. The rotated file is consumed in the background as a new version of each root document, keeping its metadata; documents that are not PDFs are skipped with a warning while the response is still OK. Requires the global change_document permission plus change access on every selected document (403 Insufficient permissions otherwise); superusers bypass these checks. Also requires that the connected user owns every document (or it is unowned).
paperless_ngx.rotate_documents Merge Documents
Merge the PDFs of the given documents, in the given order, into a single new document that is consumed in the background and owned by the connected user. Documents whose file cannot be read as a PDF are skipped. With metadata_document_id the new document copies that document's metadata and takes its title with " (merged)" appended. Requires the global change_document permission plus change access on every selected document (403 Insufficient permissions otherwise); superusers bypass these checks. Also requires the global add_document permission; with delete_originals the global delete_document permission and ownership of every document are required as well.
paperless_ngx.merge_documents Merge Documents As Versions
Turn existing top-level documents into file versions of one root document without creating a new file. The source documents disappear from the document list, give up their archive serial numbers (the root takes the first one if it has none) and become versions of the root, effective immediately. Only top-level documents can be selected and the sources must not have versions of their own. Requires the global change_document permission plus change access on every selected document (403 Insufficient permissions otherwise); superusers bypass these checks. Also requires ownership of every document (or that it is unowned) and the global delete_document permission.
paperless_ngx.merge_documents_as_versions Edit Document Pdf
Rebuild the PDF of one document from a list of page operations: keep, reorder, duplicate, rotate or drop pages, and optionally split them into several output documents. By default each output is consumed in the background as a new document owned by the connected user (metadata copied when include_metadata is true), and delete_original then trashes the source afterwards, handing its archive serial number over when there is a single output. With update_document true, a single output is consumed as a new version of the same document instead. Requires the global change_document permission plus change access on every selected document (403 Insufficient permissions otherwise); superusers bypass these checks. Also requires ownership of the document (or that it is unowned), the global add_document permission unless update_document is true, and the global delete_document permission when delete_original is true.
paperless_ngx.edit_document_pdf Remove Document Password
Remove the password protection from encrypted PDF documents using the given password. Documents that are not encrypted are skipped. By default the unprotected PDF is consumed in the background as a new document owned by the connected user (metadata copied when include_metadata is true) and delete_original then trashes the protected original; with update_document true it becomes a new version of the same document instead. A wrong password fails the whole request with 400. Requires the global change_document permission plus change access on every selected document (403 Insufficient permissions otherwise); superusers bypass these checks. Also requires ownership of every document (or that it is unowned), the global add_document permission unless update_document is true, and the global delete_document permission when delete_original is true without update_document.
paperless_ngx.remove_document_password Bulk Download Documents
Download several documents as one zip archive handed back as a temporary connector file URL. Select documents explicitly or with all plus filters; the latest version of each root document is packed. content chooses archived PDFs (falling back to the original when a document has no archive version), original files, or both, and follow_formatting names the entries after the configured filename format instead of the document title. The zip is built on the instance and may take a while; it must stay under the 500 MiB connector limit. Requires view access to every document (403 otherwise).
paperless_ngx.bulk_download_documents Get Selection Data
For a set of documents, count how many of them use each correspondent, tag, document type, storage path and custom field. Every object of each kind is returned, including those used by none of the documents, so a caller can tell whether an object applies to all, some or none of the selection before a bulk edit. Every document must exist (400 otherwise) and be visible to the connected user (403 otherwise).
paperless_ngx.get_selection_data List Trash
List the documents currently in the trash (soft deleted), newest created first, with the same fields as a regular document plus deleted_at. Superusers see every trashed document; other users only see trashed documents they own or that are unowned, explicit shares do not count. This endpoint supports pagination only, no filters or ordering.
paperless_ngx.list_trash Restore Trash Documents
Restore documents from the trash so they appear in the document list again and are re-added to the search index. Every id must be a trashed document (400 otherwise) and the connected user needs delete permission on each of them (403 otherwise).
paperless_ngx.restore_trash_documents Empty Trash
Permanently delete trashed documents together with their files. When documents is omitted, every trashed document the connected user sees in list_trash is deleted (all of them for a superuser). This cannot be undone. The connected user needs delete permission on each affected document (403 otherwise).
paperless_ngx.empty_trash Chat With Documents
Ask the Paperless-ngx AI assistant a question that is answered from your documents (retrieval-augmented generation over the LLM index). With document_id the answer is based only on that document, which must exist (400 Document not found otherwise) and be viewable by the connected user (403 otherwise); without it every document visible to the user is searched. Requires AI to be enabled in the application configuration (400 AI is required for this feature otherwise), the global view_document permission and a built LLM index. Paperless-ngx streams the reply; the connector waits for the stream to finish and returns the whole text.
paperless_ngx.chat_with_documents List Tags
List tags visible to the connected user with their document counts and nested children. Supports id and case-insensitive name filters, the is_root flag for top-level tags only, ordering and pagination. Requires the view_tag permission.
paperless_ngx.list_tags Get Tag
Get one tag by id, including its document count, parent and nested children. Requires the view_tag permission on the tag.
paperless_ngx.get_tag Create Tag
Create a tag with an optional color, matching rule, inbox flag and parent tag. The owner defaults to the connected user. Requires the add_tag permission.
paperless_ngx.create_tag Update Tag
Partially update a tag; only the provided fields are changed and null clears nullable fields such as parent. Requires the change_tag permission on the tag; changing owner or set_permissions additionally requires being the owner or a superuser.
paperless_ngx.update_tag Delete Tag
Delete a tag. Documents keep their other tags; child tags are re-parented by the tree model. Requires the delete_tag permission on the tag.
paperless_ngx.delete_tag List Correspondents
List correspondents visible to the connected user with their document counts. Supports id and case-insensitive name filters, ordering and pagination; set last_correspondence to true to include the date of the newest document per correspondent. Requires the view_correspondent permission.
paperless_ngx.list_correspondents Get Correspondent
Get one correspondent by id, including its document count and last_correspondence date. Requires the view_correspondent permission on the correspondent.
paperless_ngx.get_correspondent Create Correspondent
Create a correspondent with an optional matching rule. The owner defaults to the connected user. Requires the add_correspondent permission.
paperless_ngx.create_correspondent Update Correspondent
Partially update a correspondent; only the provided fields are changed. Requires the change_correspondent permission on the correspondent; changing owner or set_permissions additionally requires being the owner or a superuser.
paperless_ngx.update_correspondent Delete Correspondent
Delete a correspondent. Documents that used it keep no correspondent. Requires the delete_correspondent permission on the correspondent.
paperless_ngx.delete_correspondent List Document Types
List document types visible to the connected user with their document counts. Supports id and case-insensitive name filters, ordering and pagination. Requires the view_documenttype permission.
paperless_ngx.list_document_types Get Document Type
Get one document type by id, including its document count. Requires the view_documenttype permission on the document type.
paperless_ngx.get_document_type Create Document Type
Create a document type with an optional matching rule. The owner defaults to the connected user. Requires the add_documenttype permission.
paperless_ngx.create_document_type Update Document Type
Partially update a document type; only the provided fields are changed. Requires the change_documenttype permission on the document type; changing owner or set_permissions additionally requires being the owner or a superuser.
paperless_ngx.update_document_type Delete Document Type
Delete a document type. Documents that used it keep no document type. Requires the delete_documenttype permission on the document type.
paperless_ngx.delete_document_type List Storage Paths
List storage paths visible to the connected user with their document counts. Supports id and case-insensitive name and path filters, ordering and pagination. Requires the view_storagepath permission.
paperless_ngx.list_storage_paths Get Storage Path
Get one storage path by id, including its document count. Requires the view_storagepath permission on the storage path.
paperless_ngx.get_storage_path Create Storage Path
Create a storage path from a filename template and an optional matching rule. Use test_storage_path first to preview how the template renders. The owner defaults to the connected user. Requires the add_storagepath permission.
paperless_ngx.create_storage_path Update Storage Path
Partially update a storage path; only the provided fields are changed. Changing path schedules a background task that renames and moves every document using the storage path. Requires the change_storagepath permission on the storage path; changing owner or set_permissions additionally requires being the owner or a superuser.
paperless_ngx.update_storage_path Delete Storage Path
Delete a storage path. Documents that used it fall back to the default filename format and are moved in the background. Requires the delete_storagepath permission on the storage path.
paperless_ngx.delete_storage_path Test Storage Path
Render a storage path template against an existing document to preview the resulting file path, including the document's file extension, without saving anything. Only requires that the document is visible to the connected user; invalid templates are rejected with a validation error.
paperless_ngx.test_storage_path List Custom Fields
List custom field definitions with the number of documents using each one. Supports id and case-insensitive name filters, ordering and pagination. Custom fields carry no object-level permissions; requires the view_customfield permission.
paperless_ngx.list_custom_fields Get Custom Field
Get one custom field definition by id, including its select options or default currency and the number of documents using it. Requires the view_customfield permission.
paperless_ngx.get_custom_field Create Custom Field
Create a custom field definition. Select fields need extra_data.select_options with at least one labelled option (ids are generated), monetary fields may set extra_data.default_currency. Requires the add_customfield permission.
paperless_ngx.create_custom_field Update Custom Field
Partially update a custom field definition; only the provided fields are changed. For select fields extra_data.select_options must be sent in full on every update, even when only renaming the field, keeping existing option ids so document values survive. Changing data_type of a field that already has values is not supported by the Paperless-ngx UI and can make stored values unreadable. Requires the change_customfield permission.
paperless_ngx.update_custom_field Delete Custom Field
Delete a custom field definition together with every value stored for it on documents. Requires the delete_customfield permission.
paperless_ngx.delete_custom_field List Saved Views
List saved document views visible to the connected user with their filter rules and display settings. Only ordering by name and pagination are supported; there are no field filters. Requires the view_savedview permission.
paperless_ngx.list_saved_views Get Saved View
Get one saved view by id with its filter rules and display settings. Requires the view_savedview permission on the view.
paperless_ngx.get_saved_view Create Saved View
Create a saved document view from a name and a list of filter rules, optionally with sort order, page size, display mode and display fields. Dashboard and sidebar visibility are user preferences stored through update_ui_settings, not view fields. The owner defaults to the connected user. Requires the add_savedview permission.
paperless_ngx.create_saved_view Update Saved View
Partially update a saved view; only the provided fields are changed and filter_rules, when given, replaces the whole rule list. Requires the change_savedview permission on the view; changing owner or set_permissions additionally requires being the owner or a superuser.
paperless_ngx.update_saved_view Delete Saved View
Delete a saved view together with its filter rules. Requires the delete_savedview permission on the view.
paperless_ngx.delete_saved_view Bulk Edit Objects
Set the owner and permissions of, or delete, many tags, correspondents, document types or storage paths at once. Non-superusers need the change or delete model permission and must own (or the objects must be unowned) every targeted object, otherwise Paperless-ngx answers 403 Insufficient permissions. Deletion is immediate and not reversible.
paperless_ngx.bulk_edit_objects List Workflows
List workflows with their nested triggers and actions, ordered by order. The endpoint supports only pagination; it has no filters or ordering options. Requires the view_workflow permission.
paperless_ngx.list_workflows Get Workflow
Get one workflow by id, including its triggers and actions. Requires the view_workflow permission.
paperless_ngx.get_workflow Create Workflow
Create a workflow with its triggers and actions in one call. Nested triggers and actions without an id are created; entries with an id update that existing trigger or action in place. Remote OCR actions need a consumption started trigger and apply AI suggestions actions need a trigger of another type. Requires the add_workflow permission.
paperless_ngx.create_workflow Update Workflow
Partially update a workflow. Only the provided fields are sent. When triggers or actions is provided it replaces the whole set: entries with an id are updated in place, entries without an id are created, and triggers or actions left out are detached and deleted. Requires the change_workflow permission.
paperless_ngx.update_workflow Delete Workflow
Delete a workflow. Its triggers and actions are removed the next time any workflow is updated. Requires the delete_workflow permission.
paperless_ngx.delete_workflow List Workflow Triggers
List workflow triggers across all workflows. The endpoint supports only pagination; it has no filters or ordering options. Requires the view_workflowtrigger permission.
paperless_ngx.list_workflow_triggers Get Workflow Trigger
Get one workflow trigger by id. Requires the view_workflowtrigger permission.
paperless_ngx.get_workflow_trigger Create Workflow Trigger
Create a standalone workflow trigger. Consumption started (type 1) triggers need filter_filename, filter_path or filter_mailrule. Objects not attached to any workflow are deleted automatically the next time any workflow is updated, so attach it promptly through update_workflow or create_workflow. Requires the add_workflowtrigger permission.
paperless_ngx.create_workflow_trigger Update Workflow Trigger
Partially update a workflow trigger. Only the provided fields are sent. When the trigger is (or becomes) a consumption started trigger, Paperless-ngx requires filter_filename, filter_path or filter_mailrule in the same request even if unchanged. Requires the change_workflowtrigger permission.
paperless_ngx.update_workflow_trigger Delete Workflow Trigger
Delete a workflow trigger, detaching it from any workflow that used it. Requires the delete_workflowtrigger permission.
paperless_ngx.delete_workflow_trigger List Workflow Actions
List workflow actions across all workflows. The endpoint supports only pagination; it has no filters or ordering options. Requires the view_workflowaction permission.
paperless_ngx.list_workflow_actions Get Workflow Action
Get one workflow action by id. Requires the view_workflowaction permission.
paperless_ngx.get_workflow_action Create Workflow Action
Create a standalone workflow action. Email (3), webhook (4), password removal (5) and apply AI suggestions (8) actions require their email, webhook, passwords or ai_suggestion_fields data. Objects not attached to any workflow are deleted automatically the next time any workflow is updated, so attach it promptly through update_workflow or create_workflow. Requires the add_workflowaction permission.
paperless_ngx.create_workflow_action Update Workflow Action
Partially update a workflow action. Only the provided fields are sent; nested email and webhook objects replace the stored settings. Requires the change_workflowaction permission.
paperless_ngx.update_workflow_action Delete Workflow Action
Delete a workflow action, detaching it from any workflow that used it. Requires the delete_workflowaction permission.
paperless_ngx.delete_workflow_action List Share Links
List share links visible to the connected user (own links plus links shared with them), with optional creation and expiration time filters. Each result carries share_url, the public download URL. Requires the view_sharelink permission.
paperless_ngx.list_share_links Get Share Link
Get one share link by id, including its public share_url. Requires the view_sharelink permission and access to the link.
paperless_ngx.get_share_link Create Share Link
Create a public share link for one document. The link is owned by the connected user, who must be allowed to view the document. The response includes slug and the derived share_url; share links cannot be edited afterwards, so delete and recreate to change the expiration or file version. Requires the add_sharelink permission.
paperless_ngx.create_share_link Delete Share Link
Delete a share link so its public URL stops working. Requires the delete_sharelink permission and ownership of the link (or superuser).
paperless_ngx.delete_share_link List Share Link Bundles
List share link bundles visible to the connected user, filterable by status, contained documents and creation or expiration time. Each result carries share_url and the build status. Requires the view_sharelinkbundle permission.
paperless_ngx.list_share_link_bundles Get Share Link Bundle
Get one share link bundle by id, including its build status, size and public share_url. Use it to poll a bundle after create_share_link_bundle or rebuild_share_link_bundle until status is ready. Requires the view_sharelinkbundle permission.
paperless_ngx.get_share_link_bundle Create Share Link Bundle
Create a share link bundle: one public link serving a zip archive of several documents. The connected user must be allowed to view every document and duplicate ids are rejected. The zip is built by a background task, so the bundle is returned with status pending; poll get_share_link_bundle until it is ready. Bundles cannot be edited afterwards. Requires the add_sharelinkbundle permission.
paperless_ngx.create_share_link_bundle Rebuild Share Link Bundle
Discard the built zip archive of a share link bundle and queue it for rebuilding, for example after its documents changed. The bundle is returned with status pending; Paperless-ngx rejects the request with 400 while a build is still processing. Requires the change_sharelinkbundle permission.
paperless_ngx.rebuild_share_link_bundle Delete Share Link Bundle
Delete a share link bundle and its zip archive so the public URL stops working. Requires the delete_sharelinkbundle permission and ownership of the bundle (or superuser).
paperless_ngx.delete_share_link_bundle List Tasks
List Paperless-ngx background tasks (document consumption, classifier training, sanity checks, mail fetches and other jobs) with pagination and filters. Non-staff users see their own tasks plus unowned system tasks; staff users see every task. Requires the view_paperlesstask permission.
paperless_ngx.list_tasks Get Task
Get one background task by its Celery task UUID, the id returned by upload_document, update_document_version, run_task and other asynchronous actions. Poll it until status is success, failure or revoked; a successful consume task reports the new document id in result_data.document_id (also the first entry of related_document_ids), while a rejected duplicate reports the existing document in result_data.duplicate_of.
paperless_ngx.get_task Get Task By Id
Get one background task by its numeric row id (the id field of list_tasks), as opposed to the Celery UUID used by get_task.
paperless_ngx.get_task_by_id Acknowledge Tasks
Mark background tasks as acknowledged (dismissed from the task list). Pass tasks with the numeric task row ids, or all true to acknowledge every visible unacknowledged task; exactly one of the two must be given. Requires the change_paperlesstask permission.
paperless_ngx.acknowledge_tasks Get Task Summary
Get aggregated background task statistics per task type over the last N days: counts by outcome, average run and wait times and the timestamps of the latest run, success and failure. Superusers, staff and users with the view_system_monitoring permission see all tasks; everyone else sees their own tasks plus unowned system tasks.
paperless_ngx.get_task_summary Get Task Status Counts
Get the number of visible background tasks in total and per status group: needs_attention (failure or revoked), in_progress (pending or started) and completed (success). Accepts the same filters as list_tasks except status and is_complete, which the counts already break down.
paperless_ngx.get_task_status_counts List Active Tasks
List the background tasks that are currently pending or started, newest first, capped at 50 entries and not paginated. Non-staff users see their own tasks plus unowned system tasks.
paperless_ngx.list_active_tasks Run Task
Manually start a maintenance task in the background: train_classifier retrains the automatic matching classifier, sanity_check verifies the document files and database, llm_index updates the AI index. Only these three task types can be dispatched, and only by a superuser. Returns the Celery task UUID to poll with get_task.
paperless_ngx.run_task List Users
List Paperless-ngx user accounts with pagination and username filters, ordered by username. The built-in consumer and AnonymousUser accounts are never listed. Requires the view_user permission.
paperless_ngx.list_users Get User
Get one Paperless-ngx user account by id, including group memberships, direct and inherited permission codenames and whether MFA is enabled. Requires the view_user permission.
paperless_ngx.get_user Create User
Create a Paperless-ngx user account. Only username is required; without a password the account cannot log in with a password until one is set. Granting is_staff or is_superuser requires the caller to be a superuser. Requires the add_user permission.
paperless_ngx.create_user Update User
Partially update a Paperless-ngx user account; only the provided fields change and groups or user_permissions replace the whole list. Changing is_staff or is_superuser, or modifying a superuser at all, requires the caller to be a superuser. Requires the change_user permission.
paperless_ngx.update_user Delete User
Permanently delete a Paperless-ngx user account. Objects owned by the user become unowned. Deleting a superuser requires the caller to be a superuser. Requires the delete_user permission.
paperless_ngx.delete_user Deactivate User Totp
Remove the TOTP multi-factor authenticator of a user so they can log in with a password only. Callers may deactivate their own TOTP; deactivating another user's requires the caller to be a superuser. Fails with 404 when the user has no TOTP authenticator.
paperless_ngx.deactivate_user_totp List Groups
List Paperless-ngx user groups with pagination and name filters, ordered by name. Requires the view_group permission.
paperless_ngx.list_groups Get Group
Get one Paperless-ngx user group by id with its permission codenames. Requires the view_group permission.
paperless_ngx.get_group Create Group
Create a Paperless-ngx user group. Paperless-ngx requires the permissions list on create, so it is sent as an empty list when omitted. Requires the add_group permission.
paperless_ngx.create_group Update Group
Partially update a Paperless-ngx user group; only the provided fields change and permissions replaces the whole list. Requires the change_group permission.
paperless_ngx.update_group Delete Group
Permanently delete a Paperless-ngx user group. Members lose the permissions inherited from it. Requires the delete_group permission.
paperless_ngx.delete_group Get Profile
Get the profile of the user that owns the API token: name, email, linked social accounts, whether a password and MFA are set, and the API token itself (redacted from logs).
paperless_ngx.get_profile Update Profile
Update the name, email or password of the user that owns the API token. Only the provided fields change; a password made only of asterisks is ignored. Returns the updated profile including the API token (redacted from logs).
paperless_ngx.update_profile List Mail Accounts
List the mail accounts Paperless-ngx fetches documents from, ordered by id. Only accounts the connected user owns, that are unowned, or that were shared with the user are visible. Passwords are returned as an asterisk placeholder. The endpoint supports no ordering or field filters beyond paging.
paperless_ngx.list_mail_accounts Get Mail Account
Get one mail account by id. Only accounts the connected user owns, that are unowned, or that were shared with the user are visible. The password is returned as an asterisk placeholder.
paperless_ngx.get_mail_account Create Mail Account
Create an IMAP mail account that Paperless-ngx can fetch documents from. Requires the add_mailaccount permission. The account only becomes useful once a mail rule references it; use test_mail_account to verify the credentials first.
paperless_ngx.create_mail_account Update Mail Account
Partially update a mail account. Only the provided fields are sent; pass null to clear nullable fields. A password consisting only of asterisks (the placeholder returned by reads) is ignored and leaves the stored password unchanged. Requires change permission on the account.
paperless_ngx.update_mail_account Delete Mail Account
Delete a mail account together with every mail rule and processed mail record that belongs to it. Requires delete permission on the account.
paperless_ngx.delete_mail_account Test Mail Account
Test whether Paperless-ngx can log in to a mailbox with the given IMAP settings without saving anything. Pass id of an existing account together with the asterisk password placeholder to test the stored credentials (including OAuth tokens, which are refreshed when expired); this requires change permission on that account, while testing new settings requires the add_mailaccount permission. A failed login is reported as an error with status 400 and the message Unable to connect to server.
paperless_ngx.test_mail_account Process Mail Account
Queue an immediate fetch of one mail account instead of waiting for the scheduled mail check. Paperless-ngx starts a mail_fetch background task and answers OK without a task id; inspect the tasks list (task_type mail_fetch) or list_processed_mail to see the outcome. Requires view permission on the account.
paperless_ngx.process_mail_account List Mail Rules
List mail rules ordered by their order field. Only rules the connected user owns, that are unowned, or that were shared with the user are visible. The endpoint supports no ordering or field filters beyond paging.
paperless_ngx.list_mail_rules Get Mail Rule
Get one mail rule by id. Only rules the connected user owns, that are unowned, or that were shared with the user are visible.
paperless_ngx.get_mail_rule Create Mail Rule
Create a mail rule that tells Paperless-ngx which mails of an account to consume and how to file the resulting documents. Requires the add_mailrule permission and change permission on the referenced account. Actions 2 (move) and 5 (tag) need action_parameter.
paperless_ngx.create_mail_rule Update Mail Rule
Partially update a mail rule. Only the provided fields are sent; pass null to clear nullable fields. When changing action to 2 (move) or 5 (tag), send action_parameter in the same request because Paperless-ngx validates the pair together. Requires change permission on the rule.
paperless_ngx.update_mail_rule Delete Mail Rule
Delete a mail rule together with its processed mail records. Requires delete permission on the rule.
paperless_ngx.delete_mail_rule List Processed Mail
List the mails that mail rules have already processed, newest processed first by default, optionally filtered by rule or status. Only records the connected user owns, that are unowned, or that were shared with the user are returned.
paperless_ngx.list_processed_mail Get Processed Mail
Get one processed mail record by id. Only records the connected user owns, that are unowned, or that were shared with the user are visible.
paperless_ngx.get_processed_mail Bulk Delete Processed Mail
Delete several processed mail records at once so the corresponding mails can be fetched again on the next run. Paperless-ngx checks delete permission on every record first and rejects the whole request with status 403 if any is not permitted; ids that do not exist are silently skipped.
paperless_ngx.bulk_delete_processed_mail Get Statistics
Get document statistics for the connected user: document totals, inbox counts, MIME type breakdown, character count, object counts and the current archive serial number. Users with the global statistics permission see instance-wide numbers, everyone else sees only the documents they can access.
paperless_ngx.get_statistics Get System Status
Get the Paperless-ngx system status: server version, install type, storage usage, database and migration state, Redis and Celery health, search index, classifier, sanity check and LLM index status plus a 30 day task summary. Requires the system status permission (superuser or a user with the view_paperlesstask permission).
paperless_ngx.get_system_status Get Remote Version
Check the latest released Paperless-ngx version on GitHub and whether it is newer than the connected instance. The instance performs the GitHub lookup and caches it for 15 minutes; when the lookup fails it reports version 0.0.0 with update_available false.
paperless_ngx.get_remote_version Get Ui Settings
Get the UI settings, effective permissions and basic identity (id, username, staff and superuser flags, groups) of the user that owns the API token. The settings object also carries server facts such as the Paperless-ngx version, app title, trash delay, audit log, email and AI availability.
paperless_ngx.get_ui_settings Update Ui Settings
Replace the stored UI settings of the connected user with the given settings object. Paperless-ngx overwrites the whole settings document, so send the complete object as returned by get_ui_settings with your changes applied; the update_checking.backend_setting value is never stored.
paperless_ngx.update_ui_settings Get Application Config
Get the instance-wide application configuration (OCR, archive generation, barcode, remote OCR and AI settings, app title and logo). Values set to null fall back to the corresponding environment variable. Requires the view_applicationconfiguration permission.
paperless_ngx.get_application_config Update Application Config
Partially update the instance-wide application configuration. Only the fields in values are changed; pass null to reset a field to its environment default. Changing the AI embedding settings makes Paperless-ngx rebuild the LLM index in the background. Requires the change_applicationconfiguration permission.
paperless_ngx.update_application_config List Logs
List the log files available on the Paperless-ngx server (paperless, mail and celery when present). Requires admin (staff) access.
paperless_ngx.list_logs Get Log
Read the lines of one Paperless-ngx log file, optionally limited to the last N entries. Requires admin (staff) access.
paperless_ngx.get_log Global Search
Search across documents, saved views, tags, correspondents, document types, storage paths, users, groups, mail rules, mail accounts, workflows and custom fields by name or title, returning at most three matches per object type. Documents are matched through the full text index unless db_only is true, in which case only titles are compared.
paperless_ngx.global_search Autocomplete Search
Get search term completions for a partial word from the full text index, ordered by how many of the user's documents contain each candidate.
paperless_ngx.autocomplete_search No matching tools.
Frequently Asked Questions
Can I read extracted document text?
Yes. get_document includes extracted text for the selected version, subject to document view access.
What happens when I update tags?
The supplied tags list replaces the existing list. Read current metadata and include every tag you want to keep.
What should I specify in my request?
Use one search-index query mode per call. Updating tags or custom fields replaces their entire list.