Paperless-ngx API Reference
Direct API access for advanced operations not covered by the convenience scripts.
Authentication
All requests require the Authorization header:
Base URL
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
Bulk edit documents
Search with date range
Get document statistics
Response Format
All endpoints return JSON. List endpoints use pagination:
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: