Paperless-ngx

Paperless-ngx (docs.paperless-ngx.com). Use this skill for ANY Paperless-ngx request — reading, creating, updating, and deleting data. Whenever a task involves Paperless-ngx, use this skill instead of calling the API directly.

Operate Paperless-ngx through your OOMOL-connected account. This skill calls the paperless_ngx connector with the oo CLI; OOMOL injects credentials server-side, so you never handle raw tokens.

Running an action

Assume the user has already installed the oo CLI, signed in, and connected Paperless-ngx. Do not run oo auth login or open the connection URL proactively — just run the action. Fall back to First-time setup only when a command actually fails with an auth or connection error.

1. Inspect the contract to get the authoritative input/output schema before building a payload:

bash

oo connector schema "paperless_ngx" --action "<action_name>"

2. Run the action with a JSON payload that matches the input schema:

bash

oo connector run "paperless_ngx" --action "<action_name>" --data '<json>' --json

• --data takes a JSON object string or @path/to/file.json; omit it to send {}.
• The response is { "data": ..., "meta": { "executionId": "..." } }; the execution id lives under meta.executionId.

Each action is listed below with a one-line description; actions that change state carry a [write] or [destructive] tag. Before constructing --data, fetch the action's live schema with oo connector schema to get its authoritative input fields.

Available actions

• 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.
• 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. [write]
• 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.
• 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. [destructive]
• 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).
• 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. [write]
• 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. [write]
• 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.
• create_correspondent — Create a correspondent with an optional matching rule. The owner defaults to the connected user. Requires the add_correspondent permission. [write]
• 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. [write]
• create_document_type — Create a document type with an optional matching rule. The owner defaults to the connected user. Requires the add_documenttype permission. [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [destructive]
• delete_correspondent — Delete a correspondent. Documents that used it keep no correspondent. Requires the delete_correspondent permission on the correspondent. [destructive]
• delete_custom_field — Delete a custom field definition together with every value stored for it on documents. Requires the delete_customfield permission. [destructive]
• 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. [destructive]
• 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. [destructive]
• delete_document_type — Delete a document type. Documents that used it keep no document type. Requires the delete_documenttype permission on the document type. [destructive]
• 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. [destructive]
• 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). [destructive]
• delete_group — Permanently delete a Paperless-ngx user group. Members lose the permissions inherited from it. Requires the delete_group permission. [destructive]
• 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. [destructive]
• delete_mail_rule — Delete a mail rule together with its processed mail records. Requires delete permission on the rule. [destructive]
• delete_saved_view — Delete a saved view together with its filter rules. Requires the delete_savedview permission on the view. [destructive]
• 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). [destructive]
• 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). [destructive]
• 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. [destructive]
• 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. [destructive]
• 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. [destructive]
• delete_workflow — Delete a workflow. Its triggers and actions are removed the next time any workflow is updated. Requires the delete_workflow permission. [destructive]
• delete_workflow_action — Delete a workflow action, detaching it from any workflow that used it. Requires the delete_workflowaction permission. [destructive]
• delete_workflow_trigger — Delete a workflow trigger, detaching it from any workflow that used it. Requires the delete_workflowtrigger permission. [destructive]
• 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.
• 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. [write]
• 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).
• 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).
• 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). [destructive]
• 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.
• get_correspondent — Get one correspondent by id, including its document count and last_correspondence date. Requires the view_correspondent permission on the correspondent.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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).
• 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.
• get_document_type — Get one document type by id, including its document count. Requires the view_documenttype permission on the document type.
• get_group — Get one Paperless-ngx user group by id with its permission codenames. Requires the view_group permission.
• get_log — Read the lines of one Paperless-ngx log file, optionally limited to the last N entries. Requires admin (staff) access.
• 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.
• 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.
• 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.
• 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.
• 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).
• 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.
• get_saved_view — Get one saved view by id with its filter rules and display settings. Requires the view_savedview permission on the view.
• 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).
• get_share_link — Get one share link by id, including its public share_url. Requires the view_sharelink permission and access to the link. [write]
• 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. [write]
• 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.
• get_storage_path — Get one storage path by id, including its document count. Requires the view_storagepath permission on the storage path.
• 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).
• get_tag — Get one tag by id, including its document count, parent and nested children. Requires the view_tag permission on the tag.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• get_workflow — Get one workflow by id, including its triggers and actions. Requires the view_workflow permission.
• get_workflow_action — Get one workflow action by id. Requires the view_workflowaction permission.
• get_workflow_trigger — Get one workflow trigger by id. Requires the view_workflowtrigger permission. [write]
• 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.
• 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.
• 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.
• 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.
• 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.
• 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). [write]
• 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.
• 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.
• list_groups — List Paperless-ngx user groups with pagination and name filters, ordered by name. Requires the view_group permission.
• list_logs — List the log files available on the Paperless-ngx server (paperless, mail and celery when present). Requires admin (staff) access.
• 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.
• 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.
• 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.
• 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.
• 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. [write]
• 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. [write]
• 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.
• 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.
• 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.
• 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. [destructive]
• 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.
• 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.
• 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.
• 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.
• 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. [write]
• 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. [write]
• 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.
• 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. [write]
• 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. [destructive]
• 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.
• 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). [destructive]
• 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).
• 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.
• 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.
• 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.
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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). [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [write]
• 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. [write]

Safety

• Untagged actions are reads (get / list / search) — safe to run directly.
• Actions tagged [write] change Paperless-ngx state — confirm the exact payload and effect with the user before running.
• Actions tagged [destructive] remove or overwrite data — always confirm the target and get explicit approval first.

First-time setup

These are one-time steps — do not repeat them on every call. Run a step only when a command fails for the matching reason.

• oo: command not found — install the oo CLI (other platforms: https://cli.oomol.com/install-guide.md):

  bash

  curl -fsSL https://cli.oomol.com/install.sh | bash    # macOS / Linux
  

  powershell

  irm https://cli.oomol.com/install.ps1 | iex           # Windows PowerShell
  

• Not signed in / authentication error — sign in to your OOMOL account once:

  bash

  oo auth login
  

• scope_missing / credential_expired / app_not_ready / app_not_found — Paperless-ngx is not connected, or the connection expired or lacks a scope. Connect once (auth type: API key) at:

  text

  https://console.oomol.com/app-connections?provider=paperless_ngx
  

• HTTP 402 / OOMOL_INSUFFICIENT_CREDIT — billing stop. Recharge at https://console.oomol.com/billing/token-recharge before retrying.

Resources

• Paperless-ngx homepage: https://docs.paperless-ngx.com