paperless-ngx

# Paperless-ngx Skill Manage documents in Paperless-ngx via its REST API using HTTP requests. ## Configuration Requires environment variables: - `PAPERLESS_URL`: Base URL (e.g., `https://paperless.example.com`) - `PAPERLESS_TOKEN`: API token from Paperless-ngx settings ## Authentication Include token in all requests: ``` Authorization: Token $PAPERLESS_TOKEN ``` ## Core Operations ### Search Documents ```bash curl -s "$PAPERLESS_URL/api/documents/?query=invoice" \ -H "Authorization: Token $PAPERLESS_TOKEN" ``` Filter options: `correspondent__id`, `document_type__id`, `tags__id__in`, `created__date__gte`, `created__date__lte`, `added__date__gte`. ### Get Document Details ```bash curl -s "$PAPERLESS_URL/api/documents/{id}/" \ -H "Authorization: Token $PAPERLESS_TOKEN" ``` ### Download Document ```bash # Original file curl -s "$PAPERLESS_URL/api/documents/{id}/download/" \ -H "Authorization: Token $PAPERLESS_TOKEN" -o document.pdf # Archived (OCR'd) version curl -s "$PAPERLESS_URL/api/documents/{id}/download/?original=false" \ -H "Authorization: Token $PAPERLESS_TOKEN" -o document.pdf ``` ### Upload Document ```bash curl -s "$PAPERLESS_URL/api/documents/post_document/" \ -H "Authorization: Token $PAPERLESS_TOKEN" \ -F "document=@/path/to/file.pdf" \ -F "title=Document Title" \ -F "correspondent=1" \ -F "document_type=2" \ -F "tags=3" \ -F "tags=4" ``` Optional fields: `title`, `created`, `correspondent`, `document_type`, `storage_path`, `tags` (repeatable), `archive_serial_number`, `custom_fields`. ### Update Document Metadata ```bash curl -s -X PATCH "$PAPERLESS_URL/api/documents/{id}/" \ -H "Authorization: Token $PAPERLESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"title": "New Title", "correspondent": 1, "tags": [1, 2]}' ``` ### Delete Document ```bash curl -s -X DELETE "$PAPERLESS_URL/api/documents/{id}/" \ -H "Authorization: Token $PAPERLESS_TOKEN" ``` ## Organization Endpoints ### Tags ```bash # List tags curl -s "$PAPERLESS_URL/api/tags/" -H "Authorization: Token $PAPERLESS_TOKEN" # Create tag curl -s -X POST "$PAPERLESS_URL/api/tags/" \ -H "Authorization: Token $PAPERLESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "Important", "color": "#ff0000"}' ``` ### Correspondents ```bash # List correspondents curl -s "$PAPERLESS_URL/api/correspondents/" -H "Authorization: Token $PAPERLESS_TOKEN" # Create correspondent curl -s -X POST "$PAPERLESS_URL/api/correspondents/" \ -H "Authorization: Token $PAPERLESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "ACME Corp"}' ``` ### Document Types ```bash # List document types curl -s "$PAPERLESS_URL/api/document_types/" -H "Authorization: Token $PAPERLESS_TOKEN" # Create document type curl -s -X POST "$PAPERLESS_URL/api/document_types/" \ -H "Authorization: Token $PAPERLESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "Invoice"}' ``` ## Bulk Operations ```bash curl -s -X POST "$PAPERLESS_URL/api/documents/bulk_edit/" \ -H "Authorization: Token $PAPERLESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "documents": [1, 2, 3], "method": "add_tag", "parameters": {"tag": 5} }' ``` Methods: `set_correspondent`, `set_document_type`, `add_tag`, `remove_tag`, `delete`, `reprocess`. ## Task Status After upload, check task status: ```bash curl -s "$PAPERLESS_URL/api/tasks/?task_id={uuid}" \ -H "Authorization: Token $PAPERLESS_TOKEN" ``` ## Response Handling - List endpoints return `{"count": N, "results": [...]}` with pagination - Single objects return the object directly - Use `?page=2` for pagination - Add `?ordering=-created` for sorting (prefix `-` for descending)