Files

4.5 KiB

Paperless-ngx API Reference

Direct API access for advanced operations not covered by the convenience scripts.

Authentication

All requests require the Authorization header:

Authorization: Token YOUR_API_TOKEN

Base URL

${PAPERLESS_URL}/api/

Core Endpoints

Documents

Method Endpoint Description
GET /api/documents/ List documents (paginated)
GET /api/documents/{id}/ Get document details
POST /api/documents/post_document/ Upload new document
PATCH /api/documents/{id}/ Update document metadata
DELETE /api/documents/{id}/ Delete document
GET /api/documents/{id}/download/ Download archived PDF
GET /api/documents/{id}/original/ Download original file
GET /api/documents/{id}/preview/ Get document preview
GET /api/documents/{id}/thumb/ Get thumbnail

Query Parameters for Documents

Parameter Description Example
query Full-text search ?query=invoice electricity
tags__id__in Filter by tag IDs (comma-sep) ?tags__id__in=1,2,3
document_type__id Filter by type ID ?document_type__id=2
correspondent__id Filter by correspondent ID ?correspondent__id=5
created__date__gte Created on or after ?created__date__gte=2025-01-01
created__date__lte Created on or before ?created__date__lte=2025-12-31
added__date__gte Added on or after ?added__date__gte=2025-01-01
ordering Sort field (prefix - for desc) ?ordering=-created
page_size Results per page ?page_size=25
page Page number ?page=2

Tags

Method Endpoint Description
GET /api/tags/ List all tags
POST /api/tags/ Create tag
GET /api/tags/{id}/ Get tag details
PATCH /api/tags/{id}/ Update tag
DELETE /api/tags/{id}/ Delete tag

Document Types

Method Endpoint Description
GET /api/document_types/ List all types
POST /api/document_types/ Create type
GET /api/document_types/{id}/ Get type details
PATCH /api/document_types/{id}/ Update type
DELETE /api/document_types/{id}/ Delete type

Correspondents

Method Endpoint Description
GET /api/correspondents/ List all correspondents
POST /api/correspondents/ Create correspondent
GET /api/correspondents/{id}/ Get correspondent details
PATCH /api/correspondents/{id}/ Update correspondent
DELETE /api/correspondents/{id}/ Delete correspondent

Mail

Method Endpoint Description
GET /api/mail_accounts/ List email accounts
GET /api/mail_rules/ List mail rules
POST /api/mail_accounts/{id}/test/ Test email connection

Saved Views

Method Endpoint Description
GET /api/saved_views/ List saved views
POST /api/saved_views/ Create saved view

Examples

Update document metadata

curl -X PATCH \
  -H "Authorization: Token $PAPERLESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Title", "correspondent": 5, "tags": [1, 2]}' \
  "$PAPERLESS_URL/api/documents/28/"

Bulk edit documents

curl -X POST \
  -H "Authorization: Token $PAPERLESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"documents": [1, 2, 3], "method": "modify_tags", "parameters": {"add_tags": [5]}}' \
  "$PAPERLESS_URL/api/documents/bulk_edit/"

Search with date range

curl -H "Authorization: Token $PAPERLESS_TOKEN" \
  "$PAPERLESS_URL/api/documents/?query=invoice&created__date__gte=2025-01-01&created__date__lte=2025-12-31"

Get document statistics

curl -H "Authorization: Token $PAPERLESS_TOKEN" \
  "$PAPERLESS_URL/api/statistics/"

Response Format

All endpoints return JSON. List endpoints use pagination:

{
  "count": 100,
  "next": "http://host/api/documents/?page=2",
  "previous": null,
  "all": [1, 2, 3, ...],
  "results": [...]
}

Error Handling

Status Meaning
200 Success
201 Created
400 Bad request (validation error)
401 Unauthorized (bad/missing token)
404 Not found
500 Server error

Error responses include a message:

{
  "detail": "Error description"
}