marcus/PaperlessMCP
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
PaperlessMCP/docs/API_REFERENCE.md
T
marcus e7b6d37cc9 feat: rename tool ids from dotted to underscore for claude.ai compat 
Update stale dotted tool-name references in tool descriptions and docs
to match the underscore tool ids required by claude.ai
(pattern ^[a-zA-Z0-9_-]{1,64}$).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 11:30:21 +02:00

548 lines
19 KiB
Markdown
Raw Permalink Blame History

# PaperlessMCP API Reference
Complete reference for all MCP tools provided by PaperlessMCP.
## Table of Contents
- [Health & Capabilities](#health--capabilities)
- [Document Operations](#document-operations)
- [Tag Operations](#tag-operations)
- [Correspondent Operations](#correspondent-operations)
- [Document Type Operations](#document-type-operations)
- [Storage Path Operations](#storage-path-operations)
- [Custom Field 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
Reference in New Issue View Git Blame Copy Permalink