Refactor docs: slim README, separate API reference

- Condensed README to ~190 lines (was 870+) - Moved full API reference to docs/API_REFERENCE.md - Added tools summary table with link to full docs - Removed redundant nested README 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-13 14:09:02 -05:00
parent 63f355d404
commit 51d4798597
3 changed files with 626 additions and 1105 deletions
@@ -0,0 +1,547 @@
+# 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