From 89c0ba34f40a704b2e31c50dcedd3d0201d2d331 Mon Sep 17 00:00:00 2001 From: shamoon <4887959+shamoon@users.noreply.github.com> Date: Sun, 8 Mar 2026 16:43:25 -0700 Subject: [PATCH] Update docs around this --- docs/api.md | 29 +++++++++++++---------------- 1 file changed, 13 insertions(+), 16 deletions(-) diff --git a/docs/api.md b/docs/api.md index 11ce3a8d5..9703e8eb7 100644 --- a/docs/api.md +++ b/docs/api.md @@ -369,41 +369,38 @@ operations, using the endpoint: `/api/bulk_edit_objects/`, which requires a json ## API Versioning -The REST API is versioned since Paperless-ngx 1.3.0. +The REST API is versioned. - Versioning ensures that changes to the API don't break older clients. - Clients specify the specific version of the API they wish to use with every request and Paperless will handle the request using the specified API version. -- Even if the underlying data model changes, older API versions will - always serve compatible data. -- If no version is specified, Paperless will serve version 1 to ensure - compatibility with older clients that do not request a specific API - version. +- Even if the underlying data model changes, supported older API + versions continue to serve compatible data. +- If no version is specified, Paperless serves the configured default + API version (currently `10`). +- Supported API versions are currently `9` and `10`. API versions are specified by submitting an additional HTTP `Accept` header with every request: ``` -Accept: application/json; version=6 +Accept: application/json; version=10 ``` -If an invalid version is specified, Paperless 1.3.0 will respond with -"406 Not Acceptable" and an error message in the body. Earlier -versions of Paperless will serve API version 1 regardless of whether a -version is specified via the `Accept` header. +If an invalid version is specified, Paperless responds with +`406 Not Acceptable` and an error message in the body. If a client wishes to verify whether it is compatible with any given server, the following procedure should be performed: -1. Perform an _authenticated_ request against any API endpoint. If the - server is on version 1.3.0 or newer, the server will add two custom - headers to the response: +1. Perform an _authenticated_ request against any API endpoint. The + server will add two custom headers to the response: ``` - X-Api-Version: 2 - X-Version: 1.3.0 + X-Api-Version: 10 + X-Version: ``` 2. Determine whether the client is compatible with this server based on