Docs start

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://<paperless-host>:<port>/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/<pk>/download/`: Download the document.
--   `/api/documents/<pk>/preview/`: Display the document inline, without
-    downloading it.
--   `/api/documents/<pk>/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/<pk>/preview`,
-    `/fetch/<pk>/thumb` and `/fetch/<pk>/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/<id>/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/<id>/notes/`: Retrieve notes for a document.
--   `/api/documents/<id>/share_links/`: Retrieve share links for a document.
--   `/api/documents/<id>/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