Ask AI to find a contract, extract invoice details, or apply a consistent title and tags to your archived documents.
Copy a prompt into your agent with the oo Skill installed. Add your page links and source notes before running it.
Search archived contracts and extract renewal dates and notice requirements from their text.
/oo Paperless-ngx: Find the archived contract for [supplier]. Summarize its renewal date and cancellation notice period, cite the document ID, and flag anything not stated in the text.
Rename an invoice and add the selected tag while preserving its existing classification.
/oo Paperless-ngx: Rename document [ID] to [supplier — invoice number — date]. Add tag [tag ID], keeping its existing tags and other metadata.
Retrieve an archived document through a temporary download link.
/oo Paperless-ngx: Get a download URL for document [ID], using its original upload.
Find receipts for a period and package the original files into one ZIP download.
/oo Paperless-ngx: Find receipts dated [start date] through [end date] with tag [tag ID]. Package their original files into a ZIP and return the download link with the document list.
Set up oo CLI and the oo Skill in your agent.
Install OOMOL →Provide your Paperless-ngx API token and public instance URL.
Connect Paperless-ngx →Use /oo with the pages to read, the changes to make, and where to save the result.
Connection Guide →Choose Your Agent
Search document text and metadata, read archived records, update classifications, and retrieve original or archived files. The connection also supports document uploads, PDF operations, and archive administration according to your permissions.
Search the archive and read extracted text from selected documents.
Read current metadata before applying specified title or classification changes.
Retrieve an archived document through a temporary download link.
Upload documents from file URLs, combine PDFs, or export selected records as a ZIP archive.
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.
Leina 
Wanta 
paperless_ngx.list_documents 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 a correspondent with an optional matching rule. The owner defaults to the connected user. Requires the add_correspondent permission.
paperless_ngx.create_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 a correspondent. Documents that used it keep no correspondent. Requires the delete_correspondent permission on the correspondent.
paperless_ngx.delete_correspondent 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 one document type by id, including its document count. Requires the view_documenttype permission on the document type.
paperless_ngx.get_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 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 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 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 one storage path by id, including its document count. Requires the view_storagepath permission on the storage path.
paperless_ngx.get_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 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 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 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 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 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 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 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 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 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 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 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 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 a saved view together with its filter rules. Requires the delete_savedview permission on the view.
paperless_ngx.delete_saved_view 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 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 one workflow by id, including its triggers and actions. Requires the view_workflow permission.
paperless_ngx.get_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 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 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 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 one workflow trigger by id. Requires the view_workflowtrigger permission.
paperless_ngx.get_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 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 a workflow trigger, detaching it from any workflow that used it. Requires the delete_workflowtrigger permission.
paperless_ngx.delete_workflow_trigger 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 one workflow action by id. Requires the view_workflowaction permission.
paperless_ngx.get_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 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 a workflow action, detaching it from any workflow that used it. Requires the delete_workflowaction permission.
paperless_ngx.delete_workflow_action 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 Paperless-ngx user groups with pagination and name filters, ordered by name. Requires the view_group permission.
paperless_ngx.list_groups Get one Paperless-ngx user group by id with its permission codenames. Requires the view_group permission.
paperless_ngx.get_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 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 Permanently delete a Paperless-ngx user group. Members lose the permissions inherited from it. Requires the delete_group permission.
paperless_ngx.delete_group 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 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 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 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 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 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 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 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 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 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 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 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 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 a mail rule together with its processed mail records. Requires delete permission on the rule.
paperless_ngx.delete_mail_rule 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 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 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 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 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 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 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 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 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 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 the log files available on the Paperless-ngx server (paperless, mail and celery when present). Requires admin (staff) access.
paperless_ngx.list_logs Read the lines of one Paperless-ngx log file, optionally limited to the last N entries. Requires admin (staff) access.
paperless_ngx.get_log 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 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.
Yes. AI can read the extracted text of a document you have permission to view, including a selected file version.
The supplied tags list replaces the existing list. Read current metadata and include every tag you want to keep.
The instance must be reachable through a public URL. Localhost and private-network addresses cannot be used by this connection.
File downloads and ZIP exports return temporary links. Save the files while the links are available; ZIP exports must stay under 500 MiB.
Manage which optional storage OOMOL can use. You can change these choices from the footer at any time.