Paperless-ngx — Reference

Links

• Website: https://docs.paperless-ngx.com
• API docs: https://docs.paperless-ngx.com/api/
• GitHub: https://github.com/paperless-ngx/paperless-ngx

Authentication

API requests use either a token or basic auth. Get a token via the /api/token/ endpoint.

# Get API token
TOKEN=$(curl -s -X POST https://paperless.eva-00.network/api/token/ \
  -d "username=claude&password=<password>" | python3 -c "import json,sys; print(json.load(sys.stdin)['token'])")

# Use token in requests
curl -s -H "Authorization: Token $TOKEN" https://paperless.eva-00.network/api/...

API — Documents

List documents

curl -s -H "Authorization: Token $TOKEN" \
  "https://paperless.eva-00.network/api/documents/" | python3 -c \
  "import json,sys; [print(f'{d[\"id\"]} {d[\"title\"]}') for d in json.load(sys.stdin)['results']]"

Search documents (full-text)

curl -s -H "Authorization: Token $TOKEN" \
  "https://paperless.eva-00.network/api/documents/?query=tax+return+2025"

Find similar documents

curl -s -H "Authorization: Token $TOKEN" \
  "https://paperless.eva-00.network/api/documents/?more_like_id=42"

Upload a document

curl -s -X POST -H "Authorization: Token $TOKEN" \
  -F "document=@/path/to/file.pdf" \
  -F "title=Invoice 2025-03" \
  -F "tags=5" \
  -F "tags=12" \
  https://paperless.eva-00.network/api/documents/post_document/

Returns a task UUID. The document is queued for OCR and processing.

Download a document

# Original file
curl -s -H "Authorization: Token $TOKEN" \
  -o document.pdf \
  https://paperless.eva-00.network/api/documents/42/download/

# Archived (OCR'd) version
curl -s -H "Authorization: Token $TOKEN" \
  -o document_archived.pdf \
  https://paperless.eva-00.network/api/documents/42/download/?original=false

Get document metadata

curl -s -H "Authorization: Token $TOKEN" \
  https://paperless.eva-00.network/api/documents/42/metadata/

Update document fields

curl -s -X PATCH -H "Authorization: Token $TOKEN" \
  -H "Content-Type: application/json" \
  https://paperless.eva-00.network/api/documents/42/ \
  -d '{"title": "New Title", "correspondent": 3}'

API — Organization

List correspondents / tags / document types

curl -s -H "Authorization: Token $TOKEN" https://paperless.eva-00.network/api/correspondents/
curl -s -H "Authorization: Token $TOKEN" https://paperless.eva-00.network/api/tags/
curl -s -H "Authorization: Token $TOKEN" https://paperless.eva-00.network/api/document_types/

Create a tag

curl -s -X POST -H "Authorization: Token $TOKEN" \
  -H "Content-Type: application/json" \
  https://paperless.eva-00.network/api/tags/ \
  -d '{"name": "receipts", "color": "#ff0000"}'

API — Tasks

Check consumption task status

curl -s -H "Authorization: Token $TOKEN" \
  https://paperless.eva-00.network/api/tasks/?task_id=<uuid>

CLI — manage.py

Run via Docker exec on LXC 124.

ssh [email protected] "pct exec 124 -- docker exec paperless python3 manage.py <command>"

Common commands

# Create superuser
docker exec -it paperless python3 manage.py createsuperuser

# Rebuild search index
docker exec paperless python3 manage.py document_index reindex

# Re-run OCR on all documents
docker exec paperless python3 manage.py document_retagger --use-first

# Export all documents
docker exec paperless python3 manage.py document_exporter /opt/paperless/export/

# Import documents from export
docker exec paperless python3 manage.py document_importer /opt/paperless/export/

# Check database consistency
docker exec paperless python3 manage.py document_sanity_checker

What the API/CLI Cannot Do

Gap	Workaround
Cannot configure OCR settings via API	Set via environment variables in docker-compose
Cannot manage mail rules via API	Use the web UI (Settings → Mail)
Cannot bulk-delete documents via API	Delete one by one, or use manage.py
Cannot configure matching algorithms via API	Use the web UI
No CLI for remote administration	Must docker exec into the container on LXC 124
Cannot preview document thumbnails via API	Use /api/documents/{id}/thumb/ (undocumented but works)
Task queue status not exposed via API	Check Redis or Loki logs: {container="paperless"} \|= "task"