From 63f5ad9ca49e7f9f3deb8a0a68b1e5a1121f80af Mon Sep 17 00:00:00 2001 From: shamoon <4887959+shamoon@users.noreply.github.com> Date: Sat, 30 Nov 2024 21:23:06 -0800 Subject: [PATCH] Docs start --- docs/api.md | 178 +--------------------------------------------------- 1 file changed, 3 insertions(+), 175 deletions(-) diff --git a/docs/api.md b/docs/api.md index 050443c19..3cbb5d24e 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,148 +1,8 @@ # The REST API -Paperless makes use of the [Django REST -Framework](https://django-rest-framework.org/) standard API interface. It -provides a browsable API for most of its endpoints, which you can -inspect at `http://:/api/`. This also documents -most of the available filters and ordering fields. - -The API provides the following main endpoints: - -- `/api/correspondents/`: Full CRUD support. -- `/api/custom_fields/`: Full CRUD support. -- `/api/documents/`: Full CRUD support, except POSTing new documents. - See [below](#file-uploads). -- `/api/document_types/`: Full CRUD support. -- `/api/groups/`: Full CRUD support. -- `/api/logs/`: Read-Only. -- `/api/mail_accounts/`: Full CRUD support. -- `/api/mail_rules/`: Full CRUD support. -- `/api/profile/`: GET, PATCH -- `/api/share_links/`: Full CRUD support. -- `/api/storage_paths/`: Full CRUD support. -- `/api/tags/`: Full CRUD support. -- `/api/tasks/`: Read-only. -- `/api/users/`: Full CRUD support. -- `/api/workflows/`: Full CRUD support. -- `/api/search/` GET, see [below](#global-search). - -All of these endpoints except for the logging endpoint allow you to -fetch (and edit and delete where appropriate) individual objects by -appending their primary key to the path, e.g. `/api/documents/454/`. - -The objects served by the document endpoint contain the following -fields: - -- `id`: ID of the document. Read-only. -- `title`: Title of the document. -- `content`: Plain text content of the document. -- `tags`: List of IDs of tags assigned to this document, or empty - list. -- `document_type`: Document type of this document, or null. -- `correspondent`: Correspondent of this document or null. -- `created`: The date time at which this document was created. -- `created_date`: The date (YYYY-MM-DD) at which this document was - created. Optional. If also passed with created, this is ignored. -- `modified`: The date at which this document was last edited in - paperless. Read-only. -- `added`: The date at which this document was added to paperless. - Read-only. -- `archive_serial_number`: The identifier of this document in a - physical document archive. -- `original_file_name`: Verbose filename of the original document. - Read-only. -- `archived_file_name`: Verbose filename of the archived document. - Read-only. Null if no archived document is available. -- `notes`: Array of notes associated with the document. -- `page_count`: Number of pages. -- `set_permissions`: Allows setting document permissions. Optional, - write-only. See [below](#permissions). -- `custom_fields`: Array of custom fields & values, specified as - `{ field: CUSTOM_FIELD_ID, value: VALUE }` - -!!! note - - Note that all endpoint URLs must end with a `/`slash. - -## Downloading documents - -In addition to that, the document endpoint offers these additional -actions on individual documents: - -- `/api/documents//download/`: Download the document. -- `/api/documents//preview/`: Display the document inline, without - downloading it. -- `/api/documents//thumb/`: Download the PNG thumbnail of a - document. - -Paperless generates archived PDF/A documents from consumed files and -stores both the original files as well as the archived files. By -default, the endpoints for previews and downloads serve the archived -file, if it is available. Otherwise, the original file is served. Some -document cannot be archived. - -The endpoints correctly serve the response header fields -`Content-Disposition` and `Content-Type` to indicate the filename for -download and the type of content of the document. - -In order to download or preview the original document when an archived -document is available, supply the query parameter `original=true`. - -!!! tip - - Paperless used to provide these functionality at `/fetch//preview`, - `/fetch//thumb` and `/fetch//doc`. Redirects to the new URLs are - in place. However, if you use these old URLs to access documents, you - should update your app or script to use the new URLs. - -## Getting document metadata - -The api also has an endpoint to retrieve read-only metadata about -specific documents. this information is not served along with the -document objects, since it requires reading files and would therefore -slow down document lists considerably. - -Access the metadata of a document with an ID `id` at -`/api/documents//metadata/`. - -The endpoint reports the following data: - -- `original_checksum`: MD5 checksum of the original document. -- `original_size`: Size of the original document, in bytes. -- `original_mime_type`: Mime type of the original document. -- `media_filename`: Current filename of the document, under which it - is stored inside the media directory. -- `has_archive_version`: True, if this document is archived, false - otherwise. -- `original_metadata`: A list of metadata associated with the original - document. See below. -- `archive_checksum`: MD5 checksum of the archived document, or null. -- `archive_size`: Size of the archived document in bytes, or null. -- `archive_metadata`: Metadata associated with the archived document, - or null. See below. - -File metadata is reported as a list of objects in the following form: - -```json -[ - { - "namespace": "http://ns.adobe.com/pdf/1.3/", - "prefix": "pdf", - "key": "Producer", - "value": "SparklePDF, Fancy edition" - } -] -``` - -`namespace` and `prefix` can be null. The actual metadata reported -depends on the file type and the metadata available in that specific -document. Paperless only reports PDF metadata at this point. - -## Documents additional endpoints - -- `/api/documents//notes/`: Retrieve notes for a document. -- `/api/documents//share_links/`: Retrieve share links for a document. -- `/api/documents//history/`: Retrieve history of changes for a document. +Paperless-ngx now ships with a fully-documented REST API and a browsable +web interface to explore it. The API browsable interface is available at +`/api/api/schema/swagger-ui/`. ## Authorization @@ -190,38 +50,6 @@ The REST api provides four different forms of authentication. [configuration](configuration.md#PAPERLESS_ENABLE_HTTP_REMOTE_USER_API)), you can authenticate against the API using Remote User auth. -## Global search - -A global search endpoint is available at `/api/search/` and requires a search term -of > 2 characters e.g. `?query=foo`. This endpoint returns a maximum of 3 results -across nearly all objects, e.g. documents, tags, saved views, mail rules, etc. -Results are only included if the requesting user has the appropriate permissions. - -Results are returned in the following format: - -```json -{ - total: number - documents: [] - saved_views: [] - correspondents: [] - document_types: [] - storage_paths: [] - tags: [] - users: [] - groups: [] - mail_accounts: [] - mail_rules: [] - custom_fields: [] - workflows: [] -} -``` - -Global search first searches objects by name (or title for documents) matching the query. -If the optional `db_only` parameter is set, only document titles will be searched. Otherwise, -if the amount of documents returned by a simple title string search is < 3, results from the -search index will also be included. - ## Searching for documents Full text searching is available on the `/api/documents/` endpoint. Two