PaperlessMCP/docs/API_REFERENCE.md

PaperlessMCP API Reference

Complete reference for all MCP tools provided by PaperlessMCP.

Table of Contents

• Health & Capabilities
• Document Operations
• Tag Operations
• Correspondent Operations
• Document Type Operations
• Storage Path Operations
• Custom Field Operations

---

Health & Capabilities

paperless.ping

Verify connectivity and authentication with Paperless-ngx.

Returns: Connection status and server version

paperless.capabilities

Return supported API endpoints and detected Paperless-ngx version information.

Returns: Available endpoints, bulk operations, and server capabilities

---

Document Operations

paperless.documents.search

Search for documents with full-text search and filters.

Parameter	Type	Required	Default	Description
query	string	No	-	Full-text search query
tags	string	No	-	Filter by tag IDs (comma-separated)
tagsExclude	string	No	-	Exclude tag IDs (comma-separated)
correspondent	int	No	-	Filter by correspondent ID
documentType	int	No	-	Filter by document type ID
storagePath	int	No	-	Filter by storage path ID
createdAfter	string	No	-	Filter by creation date (YYYY-MM-DD)
createdBefore	string	No	-	Filter by creation date (YYYY-MM-DD)
addedAfter	string	No	-	Filter by added date (YYYY-MM-DD)
addedBefore	string	No	-	Filter by added date (YYYY-MM-DD)
archiveSerialNumber	int	No	-	Filter by archive serial number
page	int	No	1	Page number
pageSize	int	No	25	Results per page (max: 100)
ordering	string	No	-	Sort field (e.g., 'created', '-created', 'title')
includeContent	bool	No	false	Include document content in results
contentMaxLength	int	No	500	Max content length when includeContent=true

Returns: Paginated list of document summaries

paperless.documents.get

Get a document by its ID.

Parameter	Type	Required	Description
id	int	Yes	Document ID

Returns: Complete document details including content

paperless.documents.download

Get download URLs for a document's original file, preview, and thumbnail.

Parameter	Type	Required	Description
id	int	Yes	Document ID

Returns: Object with original_url, preview_url, thumbnail_url

paperless.documents.preview

Get the preview URL for a document.

Parameter	Type	Required	Description
id	int	Yes	Document ID

Returns: Preview URL

paperless.documents.thumbnail

Get the thumbnail URL for a document.

Parameter	Type	Required	Description
id	int	Yes	Document ID

Returns: Thumbnail URL

paperless.documents.upload

Upload a new document to Paperless-ngx via base64-encoded content.

Parameter	Type	Required	Default	Description
fileContent	string	Yes	-	Base64-encoded file content
fileName	string	Yes	-	Original filename with extension
title	string	No	-	Document title
correspondent	int	No	-	Correspondent ID
documentType	int	No	-	Document type ID
storagePath	int	No	-	Storage path ID
tags	string	No	-	Tag IDs (comma-separated)
archiveSerialNumber	int	No	-	Archive serial number
created	string	No	-	Created date (YYYY-MM-DD)

Returns: Task ID and upload status

Note: For large files, use paperless.documents.upload_from_path instead.

paperless.documents.upload_from_path

Upload a document from a local file path. More reliable for large files.

Parameter	Type	Required	Default	Description
filePath	string	Yes	-	Absolute path to the file
title	string	No	filename	Document title
correspondent	int	No	-	Correspondent ID
documentType	int	No	-	Document type ID
storagePath	int	No	-	Storage path ID
tags	string	No	-	Tag IDs (comma-separated)
archiveSerialNumber	int	No	-	Archive serial number
created	string	No	-	Created date (YYYY-MM-DD)

Returns: Task ID, upload status, and file information

Features: Supports ~/ expansion, automatic retries, file validation

paperless.documents.update

Update document metadata.

Parameter	Type	Required	Default	Description
id	int	Yes	-	Document ID
title	string	No	-	New title
correspondent	int	No	-	Correspondent ID (use -1 to clear)
documentType	int	No	-	Document type ID (use -1 to clear)
storagePath	int	No	-	Storage path ID (use -1 to clear)
tags	string	No	-	Tag IDs to set (comma-separated)
archiveSerialNumber	int	No	-	Archive serial number
created	string	No	-	Created date (YYYY-MM-DD)

Returns: Updated document

paperless.documents.delete

Delete a document. Requires explicit confirmation.

Parameter	Type	Required	Default	Description
id	int	Yes	-	Document ID
confirm	bool	No	false	Must be true to confirm deletion

Returns: Deletion status or dry-run preview

Safety: Without confirm=true, returns a dry-run preview showing what would be deleted.

paperless.documents.bulk_update

Perform bulk operations on multiple documents.

Parameter	Type	Required	Default	Description
documentIds	string	Yes	-	Document IDs (comma-separated)
operation	string	Yes	-	Operation: add_tag, remove_tag, set_correspondent, set_document_type, set_storage_path, delete, reprocess
value	int	No	-	Parameter value (e.g., tag ID, correspondent ID)
dryRun	bool	No	true	Preview changes without applying
confirm	bool	No	false	Must be true to execute

Returns: Affected document IDs and operation status

Safety: Defaults to dry-run mode to prevent accidental changes.

paperless.documents.reprocess

Reprocess a document's OCR and content extraction.

Parameter	Type	Required	Default	Description
id	int	Yes	-	Document ID
confirm	bool	No	false	Must be true to confirm reprocessing

Returns: Processing status

---

Tag Operations

paperless.tags.list

List all tags with pagination.

Parameter	Type	Required	Default	Description
page	int	No	1	Page number
pageSize	int	No	25	Results per page (max: 100)
ordering	string	No	-	Sort field (e.g., 'name', '-document_count')

Returns: Paginated list of tags

paperless.tags.get

Get a tag by its ID.

Parameter	Type	Required	Description
id	int	Yes	Tag ID

Returns: Tag details

paperless.tags.create

Create a new tag.

Parameter	Type	Required	Default	Description
name	string	Yes	-	Tag name
color	string	No	-	Hex color (e.g., '#ff0000')
match	string	No	-	Match pattern for auto-tagging
matchingAlgorithm	int	No	0	Matching algorithm (see below)
isInboxTag	bool	No	false	Mark as inbox tag

Matching Algorithms:

• 0 - None
• 1 - Any word
• 2 - All words
• 3 - Literal match
• 4 - Regular expression
• 5 - Fuzzy match
• 6 - Auto

Returns: Created tag

paperless.tags.update

Update an existing tag.

Parameter	Type	Required	Description
id	int	Yes	Tag ID
name	string	No	New name
color	string	No	Hex color
match	string	No	Match pattern
matchingAlgorithm	int	No	Matching algorithm
isInboxTag	bool	No	Inbox tag status

Returns: Updated tag

paperless.tags.delete

Delete a tag. Requires explicit confirmation.

Parameter	Type	Required	Default	Description
id	int	Yes	-	Tag ID
confirm	bool	No	false	Must be true to confirm deletion

Returns: Deletion status or dry-run preview

paperless.tags.bulk_delete

Delete multiple tags.

Parameter	Type	Required	Default	Description
tagIds	string	Yes	-	Tag IDs (comma-separated)
dryRun	bool	No	true	Preview changes without applying
confirm	bool	No	false	Must be true to execute

Returns: Affected tag IDs and operation status

---

Correspondent Operations

paperless.correspondents.list

List all correspondents with pagination.

Parameter	Type	Required	Default	Description
page	int	No	1	Page number
pageSize	int	No	25	Results per page (max: 100)
ordering	string	No	-	Sort field (e.g., 'name', '-document_count', 'last_correspondence')

Returns: Paginated list of correspondents

paperless.correspondents.get

Get a correspondent by its ID.

Parameter	Type	Required	Description
id	int	Yes	Correspondent ID

Returns: Correspondent details

paperless.correspondents.create

Create a new correspondent.

Parameter	Type	Required	Default	Description
name	string	Yes	-	Correspondent name
match	string	No	-	Match pattern for auto-assignment
matchingAlgorithm	int	No	0	Matching algorithm

Returns: Created correspondent

paperless.correspondents.update

Update an existing correspondent.

Parameter	Type	Required	Description
id	int	Yes	Correspondent ID
name	string	No	New name
match	string	No	Match pattern
matchingAlgorithm	int	No	Matching algorithm

Returns: Updated correspondent

paperless.correspondents.delete

Delete a correspondent. Requires explicit confirmation.

Parameter	Type	Required	Default	Description
id	int	Yes	-	Correspondent ID
confirm	bool	No	false	Must be true to confirm deletion

Returns: Deletion status or dry-run preview

paperless.correspondents.bulk_delete

Delete multiple correspondents.

Parameter	Type	Required	Default	Description
correspondentIds	string	Yes	-	Correspondent IDs (comma-separated)
dryRun	bool	No	true	Preview changes without applying
confirm	bool	No	false	Must be true to execute

Returns: Affected correspondent IDs and operation status

---

Document Type Operations

paperless.document_types.list

List all document types with pagination.

Parameter	Type	Required	Default	Description
page	int	No	1	Page number
pageSize	int	No	25	Results per page (max: 100)
ordering	string	No	-	Sort field (e.g., 'name', '-document_count')

Returns: Paginated list of document types

paperless.document_types.get

Get a document type by its ID.

Parameter	Type	Required	Description
id	int	Yes	Document type ID

Returns: Document type details

paperless.document_types.create

Create a new document type.

Parameter	Type	Required	Default	Description
name	string	Yes	-	Document type name
match	string	No	-	Match pattern for auto-assignment
matchingAlgorithm	int	No	0	Matching algorithm

Returns: Created document type

paperless.document_types.update

Update an existing document type.

Parameter	Type	Required	Description
id	int	Yes	Document type ID
name	string	No	New name
match	string	No	Match pattern
matchingAlgorithm	int	No	Matching algorithm

Returns: Updated document type

paperless.document_types.delete

Delete a document type. Requires explicit confirmation.

Parameter	Type	Required	Default	Description
id	int	Yes	-	Document type ID
confirm	bool	No	false	Must be true to confirm deletion

Returns: Deletion status or dry-run preview

paperless.document_types.bulk_delete

Delete multiple document types.

Parameter	Type	Required	Default	Description
documentTypeIds	string	Yes	-	Document type IDs (comma-separated)
dryRun	bool	No	true	Preview changes without applying
confirm	bool	No	false	Must be true to execute

Returns: Affected document type IDs and operation status

---

Storage Path Operations

paperless.storage_paths.list

List all storage paths with pagination.

Parameter	Type	Required	Default	Description
page	int	No	1	Page number
pageSize	int	No	25	Results per page (max: 100)
ordering	string	No	-	Sort field (e.g., 'name', '-document_count')

Returns: Paginated list of storage paths

paperless.storage_paths.get

Get a storage path by its ID.

Parameter	Type	Required	Description
id	int	Yes	Storage path ID

Returns: Storage path details

paperless.storage_paths.create

Create a new storage path.

Parameter	Type	Required	Default	Description
name	string	Yes	-	Storage path name
path	string	Yes	-	Path template (e.g., {correspondent}/{document_type})
match	string	No	-	Match pattern for auto-assignment
matchingAlgorithm	int	No	0	Matching algorithm

Returns: Created storage path

paperless.storage_paths.update

Update an existing storage path.

Parameter	Type	Required	Description
id	int	Yes	Storage path ID
name	string	No	New name
path	string	No	Path template
match	string	No	Match pattern
matchingAlgorithm	int	No	Matching algorithm

Returns: Updated storage path

paperless.storage_paths.delete

Delete a storage path. Requires explicit confirmation.

Parameter	Type	Required	Default	Description
id	int	Yes	-	Storage path ID
confirm	bool	No	false	Must be true to confirm deletion

Returns: Deletion status or dry-run preview

paperless.storage_paths.bulk_delete

Delete multiple storage paths.

Parameter	Type	Required	Default	Description
storagePathIds	string	Yes	-	Storage path IDs (comma-separated)
dryRun	bool	No	true	Preview changes without applying
confirm	bool	No	false	Must be true to execute

Returns: Affected storage path IDs and operation status

---

Custom Field Operations

paperless.custom_fields.list

List all custom field definitions with pagination.

Parameter	Type	Required	Default	Description
page	int	No	1	Page number
pageSize	int	No	25	Results per page (max: 100)

Returns: Paginated list of custom field definitions

paperless.custom_fields.get

Get a custom field definition by its ID.

Parameter	Type	Required	Description
id	int	Yes	Custom field ID

Returns: Custom field details

paperless.custom_fields.create

Create a new custom field definition.

Parameter	Type	Required	Default	Description
name	string	Yes	-	Custom field name
dataType	string	Yes	-	Data type (see below)
selectOptions	string	No	-	Select options (comma-separated, for 'select' type)
defaultCurrency	string	No	-	Default currency (for 'monetary' type)

Data Types:

• string - Text value
• url - URL/link
• date - Date value
• boolean - True/false
• integer - Whole number
• float - Decimal number
• monetary - Currency amount
• documentlink - Link to another document
• select - Dropdown selection

Returns: Created custom field

paperless.custom_fields.update

Update an existing custom field definition.

Parameter	Type	Required	Description
id	int	Yes	Custom field ID
name	string	No	New name
selectOptions	string	No	Select options (comma-separated)
defaultCurrency	string	No	Default currency

Returns: Updated custom field

paperless.custom_fields.delete

Delete a custom field definition. Requires explicit confirmation.

Parameter	Type	Required	Default	Description
id	int	Yes	-	Custom field ID
confirm	bool	No	false	Must be true to confirm deletion

Returns: Deletion status or dry-run preview

paperless.custom_fields.assign

Assign a custom field value to a document.

Parameter	Type	Required	Description
documentId	int	Yes	Document ID
fieldId	int	Yes	Custom field ID
value	string	Yes	Value to assign (type depends on field)

Returns: Assignment status and assigned value