Paperless-NGX 3 Compatibility¶
Paperless NGX Dedupe is compatible with Paperless-NGX 3.x. The integration was checked against the Paperless-NGX 3.0.0 API v10 implementation and schemas.
API Version Negotiation¶
The client starts with an unversioned Accept: application/json request, reads Paperless's X-Api-Version response header, and pins later requests to that version. This supports the Paperless 3 default API while retaining compatibility with older Paperless 2 releases that reject an unsupported hard-coded API version.
Validated Surfaces¶
| App capability | Paperless API surface | Paperless 3 status |
|---|---|---|
| Connection and document count | /api/statistics/, /api/documents/ fallback | Compatible |
| Document sync and lookup | /api/documents/, /api/documents/{id}/ | Compatible |
| Correspondents, document types, tags, storage paths | Matching paginated endpoints | Compatible |
| Custom-field definitions and values | /api/custom_fields/, document custom_fields | Compatible; select option IDs preserved |
| Apply AI metadata | PATCH /api/documents/{id}/ | Compatible; custom fields use safe read-modify-write |
| Delete and bulk actions | Document DELETE, /api/documents/bulk_edit/ | Compatible for the operations used by this app |
| System metrics | /api/status/, /api/statistics/, entity endpoints | Compatible |
| Preview and thumbnail proxying | Document preview and thumb endpoints | Compatible |
Paperless 3's API v10 deprecates some legacy bulk-edit methods. This app does not use the deprecated merge, rotate, split, or page-deletion methods.
Metrics Permissions¶
Paperless 3 applies explicit permissions to system-wide observability:
paperless.view_system_monitoringis required for thestatuscollector unless the API user is staff or a superuser.paperless.view_global_statisticsis required for global statistics. Without it, Paperless returns counts scoped to objects visible to the API user.
The statistics and document collectors share one statistics request per scrape. Other entity collectors remain paginated because their metric labels require individual records.
Custom-Field Safety¶
Paperless treats a document custom_fields update as replacement of the entire list. The app therefore reads the current document immediately before applying recommendations, updates only the selected field IDs, preserves every unrelated value, and records the full before/after values for revert.