Returns information about this software.

Authenticate with account name and password. The account name is comprised of the collective id and user id separated by slash, backslash or whitespace.

If successful, an authentication token is returned that can be used for subsequent calls to protected routes.

If the account has two-factor auth enabled, the returned token must be used to supply the second factor.

After a login with account name and password, a second factor must be supplied (only for accounts that enabled it) in order to complete login.

If the code is correct, a new token is returned that can be used for subsequent calls to protected routes.

Initiates the "Authorization Code Flow" as described in the OpenID Connect specification. This only is enabled, if an external provider has been configured correctly in the config file.

This will redirect to the external provider to authenticate the user. Once authenticated, the user is redirected back to the /resume endpoint.

This URL is used to redirect the user back to the application by the authentication provider after login is completed.

This will then try to find (or create) the account at docspell using information about the user provided by the authentication provider. If the required information cannot be found, the user cannot be logged into the application.

If the process completed successfully, this endpoint redirects into the web application which will take over from here.

Authenticate with a token. This can be used to get a new authentication token based on another valid one.

This route informs the server about a logout. This is not strictly necessary.

Requests to enable two factor authentication for this user. A secret key is generated and returned. The client is expected to insert it into some OTP application. Currently, only time based OTP is supported.

The request body is empty.

Confirms using two factor authentication by sending a one time password. If the password is correct, this enables two factor authentication for the current user.

If there exists no unapproved otp request or the password is not correct, an error is returned. If 2fa is already enabled for this account, success is returned.

Disables two factor authentication for the current user. If the user has no two factor authentication enabled, an error is returned.

It requires to specify a valid otp.

After this completes successfully, two factor auth can be enabled again by initializing it anew.

Checks if a file with the given SHA-256 checksum is in docspell. The id is a source id configured by a collective.

The result shows all items that contains a file with the given checksum.

Upload a file to docspell for processing. The id is a source id configured by a collective. Files are submitted for processing which eventually resuts in an item in the inbox of the corresponding collective.

The request must be a multipart/form-data request, where the first part has name meta, is optional and may contain upload metadata as JSON. Checkout the structure ItemUploadMeta at the end if it is not shown here. Other parts specify the files. Multiple files can be specified, but at least on is required.

The upload meta data can be used to tell, whether multiple files are one item, or if each file should become a single item. By default, each file will be a one item.

Upload a file to docspell for processing. The id is a source id configured by a collective. Files are submitted for processing which eventually resuts in an item in the inbox of the corresponding collective. This endpoint associates the files to an existing item identified by its itemId.

The request must be a multipart/form-data request, where the first part has name meta, is optional and may contain upload metadata as JSON. Checkout the structure ItemUploadMeta at the end if it is not shown here. Other parts specify the files. Multiple files can be specified, but at least on is required.

Upload meta data is ignored.

Checks if a file with the given SHA-256 checksum is in docspell.

The result shows all items that contains a file with the given checksum.

Upload files to docspell for processing. This route is meant for authenticated users that upload files to their account.

Everything else is the same as with the /open/upload/item/{id} endpoint.

The request must be a "multipart/form-data" request, where the first part is optional and may contain upload metadata as JSON. Other parts specify the files. Multiple files can be specified, but at least one is required.

The upload meta data can be used to tell, whether multiple files are one item, or if each file should become a single item. By default, each file will be a one item.

Upload files to docspell for processing. This route is meant for authenticated users that upload files to their account. This endpoint will associate the files to an existing item identified by its itemId.

Everything else is the same as with the /open/upload/item/{itemId}/{id} endpoint.

The request must be a "multipart/form-data" request, where the first part is optional and may contain upload metadata as JSON. Other parts specify the files. Multiple files can be specified, but at least on is required.

The upload meta data is ignored, since the item already exists.

Upload a file to docspell for processing. The id is a collective name. This route only exists, if enabled by an admin in the configuration. The route might be protected by different methods, all configurable via the configuration:

• A specific header must be prestent
• username/password via HTTP Basic mechanism
• a specific source ip

Files are submitted for processing to the specified collective, which eventually resuts in an item in their inbox.

The request must be a multipart/form-data request, where the first part has name meta, is optional and may contain upload metadata as JSON. Checkout the structure ItemUploadMeta at the end if it is not shown here. Other parts specify the files. Multiple files can be specified, but at least on is required.

Checks if a file with the given SHA-256 checksum is in docspell. The id is the collective name. This route only exists, if it is enabled in the configuration file.

The result shows all items that contains a file with the given checksum.

Clears the full-text index and inserts all data from the database. This migh take a while to complete. The response returns immediately. A task is submitted that will be executed by a job executor. Note that this affects all data of all collectives.

This is an admin route, so you need to provide the secret from the config file as header Docspell-Admin-Secret.

Clears the full-text index for all data belonging to the current collective and inserts the data from the database. The response is immediately returned and a task is submitted that will be executed by a job executor.

Clears the full-text index and inserts all data from the database. This migh take a while to complete. The response returns immediately. A task is submitted that will be executed by a job executor. Note that this affects all data of all collectives.

This is an admin route, so you need to provide the secret from the config file as header Docspell-Admin-Secret.

Resets a user password to some random string which is returned as the result. This is an admin route, so you need to specify the secret from the config file via a http header Docspell-Admin-Secret.

Removes the OTP setup for the given user account. The account can login afterwards with a correct password. A second factor is not required. Two factor auth can be setup again for this account.

Submits a task that re-generates preview images of all attachments. Each existing preview image will be replaced.

This can be used after changing the preview settings.

If only preview images of selected attachments should be regenerated, see the /sec/attachment/{id}/preview endpoint.

This is an admin route, you need to specify the secret from the config file via a http header Docspell-Admin-Secret.

Docspell converts PDF files into PDF/A files by default, if the OcrMyPDF tool is configured.

This endpoint can be used to submit a task that runs this on all files that have not been converted yet in this way.

This conversion tool has been added in version 0.9.0 and so older files can be "migrated" this way, or maybe after enabling the tool (it is optional).

The task finds all files collective and submits a task for each file to convert. These tasks are submitted with a low priority so that normal processing can still proceed.

The body of the request should be empty.

Submits a task that will copy all files of the application (from the default file repository) into another file repository as specified in the request. The request may define ids of file repository configurations that must be present in the config file. An empty list means to copy to all enabled file repositories from te default file repository.

Submits a task that goes through the files and compares the stored checksum (at the time of inserting) against a newly calculated one.

This endpoint calculates the number of files and (uncompressed) size of the zip file that would be created with this request.

It also checks against configured thresholds and tells whether the server allows to ask for a download using this query.

A job is submitted to create a ZIP file containing all the files that are included in the given query.

Once the job is done, the returned ID can be used to download the zip file.

If a job is running (created via the submit endpoint) to prepare a zip file for download, it is cancelled. The id is the download id as defined in the prefetch or submit responses.

Download the zip file to the given id.

Deletes the zip file to the given id.

This endpoint calculates the number of files and (uncompressed) size of the zip file that would be created with this request.

It also checks against configured thresholds and tells whether the server allows to ask for a download using this query.

This variant adds the query of the share and the fileType property in the request is ignored. It is always fixed to converted.

A job is submitted to create a ZIP file containing all the files that are included in the given query.

Once the job is done, the returned ID can be used to download the zip file.

This variant adds the query of the share and the fileType property in the request is ignored. It is always fixed to converted.

Download the zip file to the given id.

Allows to check whether an integration endpoint is enabled for a collective. The collective is given by the id parameter. It returns not found (404) if the endpoint is disabled (either globally by an admin or by a specific collective). It returns 403 (or 401 if http-basic is enabled) if authorization fails.

The response body is empty (an empty json object).

Upload a file to docspell for processing. The id is a collective name. This route only exists, if enabled by an admin in the configuration. The route might be protected by different methods, all configurable via the configuration:

• A specific header must be prestent
• username/password via HTTP Basic mechanism
• a specific source ip

Files are submitted for processing to the specified collective, which eventually resuts in an item in their inbox.

The request must be a multipart/form-data request, where the first part has name meta, is optional and may contain upload metadata as JSON. Checkout the structure ItemUploadMeta at the end if it is not shown here. Other parts specify the files. Multiple files can be specified, but at least on is required.

Checks if a file with the given SHA-256 checksum is in docspell. The id is the collective name. This route only exists, if it is enabled in the configuration file.

The result shows all items that contains a file with the given checksum.

Create a new account by creating a collective and user.

When signup mode is set to "invite", docspell requires an invitation key when signing up. These keys can be created here. Creating such keys requires an admin role, and since docspell has no such concept, a password from the configuration file is required for this action.

Given the share id and optionally a password, it verifies the correctness of the given data. As a result, a token is returned that must be used with all share/* routes. If the password is missing, but required, the response indicates this. Then the requests needs to be replayed with the correct password to retrieve the token.

The token is also added as a session cookie to the response.

The token is used to avoid passing the user define password with every request.

Allows to run a search query in the shared documents. The input data structure is the same as with a standard query. The searchMode parameter is ignored here.

Instead of returning the results of a query, uses it to return a summary, constraint to the share.

Get detailed information about an item.

Get information about the binary file belonging to the attachment with the given id.

Get the binary file belonging to the attachment with the given id. The binary is a pdf file. If conversion failed, then the original file is returned.

This provides a preview of the attachment rendered in a browser.

It currently uses a third-party javascript library (viewerjs) to display the preview. This works by redirecting to the viewerjs url with the attachment url as parameter. Note that the resulting url that is redirected to is not stable. It may change from version to version. This route, however, is meant to provide a stable url for the preview.