Docspell (0.42.0)

Download OpenAPI specification:Download

License: AGPLv3

This is the remote API to Docspell. Docspell is a free document management system focused on small groups or families.

The routes can be divided into protected, unprotected routes and admin routes. The unprotected, or open routes are at /open/* while the protected routes are at /sec/* and admin routes are at /admin/*. Open routes don't require authenticated access and can be used by any user. The protected routes require an authenticated user. The admin routes require a special http header with a value from the config file. They are disabled by default, you need to specify a secret in order to enable admin routes.

Information

Get version information.

Returns information about this software.

Responses

Response samples

Content type
application/json
{
  • "version": "string",
  • "builtAtMillis": 0,
  • "builtAtString": "string",
  • "gitCommit": "string",
  • "gitVersion": "string"
}

Authentication

Authenticate with account name and password.

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.

Request Body schema: application/json
account
required
string
password
required
string
rememberMe
boolean

Responses

Request samples

Content type
application/json
{
  • "account": "string",
  • "password": "string",
  • "rememberMe": true
}

Response samples

Content type
application/json
{
  • "collective": "string",
  • "user": "string",
  • "success": true,
  • "message": "string",
  • "token": "string",
  • "validMs": 0,
  • "requireSecondFactor": true
}

Provide the second factor to finalize authentication

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.

Request Body schema: application/json
token
required
string
otp
required
string <password>
rememberMe
required
boolean

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "otp": "pa$$word",
  • "rememberMe": true
}

Response samples

Content type
application/json
{
  • "collective": "string",
  • "user": "string",
  • "success": true,
  • "message": "string",
  • "token": "string",
  • "validMs": 0,
  • "requireSecondFactor": true
}

Authenticates via OIDC at the external provider given by its id

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.

path Parameters
providerId
required
string <ident>

Responses

The callback URL for the authentication provider

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.

path Parameters
providerId
required
string <ident>

Responses

Authentication with a token

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

Authorizations:
authTokenHeader

Responses

Response samples

Content type
application/json
{
  • "collective": "string",
  • "user": "string",
  • "success": true,
  • "message": "string",
  • "token": "string",
  • "validMs": 0,
  • "requireSecondFactor": true
}

Logout.

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

Authorizations:
authTokenHeader

Responses

Initialize two factor auth via OTP

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.

Authorizations:
authTokenHeader

Responses

Response samples

Content type
application/json
{
  • "authenticatorUrl": "http://example.com",
  • "secret": "string",
  • "authType": "totp",
  • "issuer": "string"
}

Confirms two factor authentication

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.

Request Body schema: application/json
otp
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "otp": "pa$$word"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Disables two factor authentication.

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.

Request Body schema: application/json
otp
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "otp": "pa$$word"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Upload

Check if a file is in docspell (via source).

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.

path Parameters
id
required
string

An identifier

checksum
required
string

A SHA-256 checksum

Responses

Response samples

Content type
application/json
{
  • "exists": true,
  • "items": [
    ]
}

Upload files to docspell (via source).

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.

path Parameters
id
required
string

An identifier

Request Body schema: multipart/form-data
object (ItemUploadMeta)

Meta information for an item upload. The user can specify some structured information with a binary file.

Additional metadata is not required. However, if there is some specified, you have to specifiy whether the corresponding files should become one single item or if an item is created for each file.

file
Array of strings <binary> [ items <binary > ]

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Upload files to an existing item (via source).

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.

path Parameters
id
required
string

An identifier

itemId
required
string

An identifier for an item

Request Body schema: multipart/form-data
object (ItemUploadMeta)

Meta information for an item upload. The user can specify some structured information with a binary file.

Additional metadata is not required. However, if there is some specified, you have to specifiy whether the corresponding files should become one single item or if an item is created for each file.

file
Array of strings <binary> [ items <binary > ]

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Check if a file is in docspell (authenticated).

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.

Authorizations:
authTokenHeader
path Parameters
checksum
required
string

A SHA-256 checksum

Responses

Response samples

Content type
application/json
{
  • "exists": true,
  • "items": [
    ]
}

Upload files to docspell (authenticated).

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.

Authorizations:
authTokenHeader
Request Body schema: multipart/form-data
object (ItemUploadMeta)

Meta information for an item upload. The user can specify some structured information with a binary file.

Additional metadata is not required. However, if there is some specified, you have to specifiy whether the corresponding files should become one single item or if an item is created for each file.

file
Array of strings <binary> [ items <binary > ]

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Upload files to an existing item (authenticated).

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.

Authorizations:
authTokenHeader
path Parameters
itemId
required
string

An identifier for an item

Request Body schema: multipart/form-data
object (ItemUploadMeta)

Meta information for an item upload. The user can specify some structured information with a binary file.

Additional metadata is not required. However, if there is some specified, you have to specifiy whether the corresponding files should become one single item or if an item is created for each file.

file
Array of strings <binary> [ items <binary > ]

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Upload files to docspell (Integration Endpoint).

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.

path Parameters
id
required
string

An identifier

Request Body schema: multipart/form-data
object (ItemUploadMeta)

Meta information for an item upload. The user can specify some structured information with a binary file.

Additional metadata is not required. However, if there is some specified, you have to specifiy whether the corresponding files should become one single item or if an item is created for each file.

file
Array of strings <binary> [ items <binary > ]

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Check if a file is in docspell (Integration Endpoint).

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.

Authorizations:
authTokenHeader
path Parameters
id
required
string

An identifier

checksum
required
string

A SHA-256 checksum

Responses

Response samples

Content type
application/json
{
  • "exists": true,
  • "items": [
    ]
}

Full-Text Index

Re-creates the full-text index.

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.

Authorizations:
adminHeader

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Re-creates the full-text index for the current collective

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.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Admin

Re-creates the full-text index.

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.

Authorizations:
adminHeader

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Reset a user password.

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.

Authorizations:
adminHeader
Request Body schema: application/json
account
required
string <accountid>

Responses

Request samples

Content type
application/json
{
  • "account": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "newPassword": "pa$$word",
  • "message": "string"
}

Disables OTP two factor auth for the given user.

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.

Authorizations:
adminHeader
Request Body schema: application/json
account
required
string <accountid>

Responses

Request samples

Content type
application/json
{
  • "account": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

(Re)generate all preview images

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.

Authorizations:
adminHeader

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Convert all PDF files not yet converted

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.

Authorizations:
adminHeader

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Copy all files into a new repository

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.

Authorizations:
adminHeader
Request Body schema: application/json
targetRepositories
required
Array of strings <ident> [ items <ident > ]

Responses

Request samples

Content type
application/json
{
  • "targetRepositories": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Verifies the stored checksum

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

Authorizations:
adminHeader
Request Body schema: application/json
collective
string <ident>

Responses

Request samples

Content type
application/json
{
  • "collective": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Download

Return information about a potential zip download

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.

Authorizations:
authTokenHeader
Request Body schema: application/json
query
required
string <itemquery>
fileType
required
string <downloadalltype>
Enum: "converted" "original"

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "fileType": "converted"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "fileCount": 0,
  • "uncompressedSize": 0,
  • "state": "forbidden"
}

Submits a job to create a zip containing all files in the 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.

Authorizations:
authTokenHeader
Request Body schema: application/json
query
required
string <itemquery>
fileType
required
string <downloadalltype>
Enum: "converted" "original"

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "fileType": "converted"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "fileCount": 0,
  • "uncompressedSize": 0,
  • "state": "forbidden"
}

Cancels potentially running jobs to create a download archive

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.

Authorizations:
authTokenHeader
path Parameters
id
required
string

An identifier

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Download the zip file given the id

Download the zip file to the given id.

Authorizations:
authTokenHeader
path Parameters
id
required
string

An identifier

Responses

Deletets the zip file given the id

Deletes the zip file to the given id.

Authorizations:
authTokenHeader
path Parameters
id
required
string

An identifier

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Return information about a potential zip download

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.

Authorizations:
shareTokenHeader
Request Body schema: application/json
query
required
string <itemquery>
fileType
required
string <downloadalltype>
Enum: "converted" "original"

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "fileType": "converted"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "fileCount": 0,
  • "uncompressedSize": 0,
  • "state": "forbidden"
}

Submits a job to create a zip containing all files in the 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.

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

Authorizations:
shareTokenHeader
Request Body schema: application/json
query
required
string <itemquery>
fileType
required
string <downloadalltype>
Enum: "converted" "original"

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "fileType": "converted"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "fileCount": 0,
  • "uncompressedSize": 0,
  • "state": "forbidden"
}

Download the zip file given the id

Download the zip file to the given id.

Authorizations:
shareTokenHeader
path Parameters
id
required
string

An identifier

Responses

Integration Endpoint

Check if integration endpoint is available.

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).

path Parameters
id
required
string

An identifier

Responses

Response samples

Content type
application/json
{ }

Upload files to docspell (Integration Endpoint).

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.

path Parameters
id
required
string

An identifier

Request Body schema: multipart/form-data
object (ItemUploadMeta)

Meta information for an item upload. The user can specify some structured information with a binary file.

Additional metadata is not required. However, if there is some specified, you have to specifiy whether the corresponding files should become one single item or if an item is created for each file.

file
Array of strings <binary> [ items <binary > ]

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Check if a file is in docspell (Integration Endpoint).

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.

Authorizations:
authTokenHeader
path Parameters
id
required
string

An identifier

checksum
required
string

A SHA-256 checksum

Responses

Response samples

Content type
application/json
{
  • "exists": true,
  • "items": [
    ]
}

Registration

Register a new account.

Create a new account by creating a collective and user.

Request Body schema: application/json
collectiveName
required
string <ident>
login
required
string <ident>
password
required
string <password>
invite
string <ident>

Responses

Request samples

Content type
application/json
{
  • "collectiveName": "string",
  • "login": "string",
  • "password": "pa$$word",
  • "invite": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Generate a new invite.

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.

Request Body schema: application/json
password
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "key": "string"
}

Share

Verify a secret for a share

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.

Request Body schema: application/json
shareId
required
string <ident>
password
string <password>

Responses

Request samples

Content type
application/json
{
  • "shareId": "string",
  • "password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "token": "string",
  • "passwordRequired": true,
  • "message": "string",
  • "name": "string"
}

Performs a search in a share.

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.

Authorizations:
shareTokenHeader
Request Body schema: application/json
offset
integer <int32>
limit
integer <int32>

The maximum number of results to return. Note that this limit is a soft limit, there is some hard limit on the server, too.

withDetails
boolean
Default: false
searchMode
string <searchmode>
Default: "normal"
Enum: "normal" "trashed" "all"

Specify whether the search query should apply to soft-deleted items or not.

query
required
string

A query searching the contents of documents.

Responses

Request samples

Content type
application/json
{
  • "offset": 0,
  • "limit": 0,
  • "withDetails": false,
  • "searchMode": "normal",
  • "query": "string"
}

Response samples

Content type
application/json
{
  • "groups": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "limitCapped": true
}

Get basic statistics about search results.

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

Authorizations:
shareTokenHeader
Request Body schema: application/json
offset
integer <int32>
limit
integer <int32>

The maximum number of results to return. Note that this limit is a soft limit, there is some hard limit on the server, too.

withDetails
boolean
Default: false
searchMode
string <searchmode>
Default: "normal"
Enum: "normal" "trashed" "all"

Specify whether the search query should apply to soft-deleted items or not.

query
required
string

A query searching the contents of documents.

Responses

Request samples

Content type
application/json
{
  • "offset": 0,
  • "limit": 0,
  • "withDetails": false,
  • "searchMode": "normal",
  • "query": "string"
}

Response samples

Content type
application/json
{
  • "count": 0,
  • "tagCloud": {
    },
  • "tagCategoryCloud": {
    },
  • "fieldStats": [
    ],
  • "folderStats": [
    ],
  • "corrOrgStats": [
    ],
  • "corrPersStats": [
    ],
  • "concPersStats": [
    ],
  • "concEquipStats": [
    ]
}

Get details about an item.

Get detailed information about an item.

Authorizations:
shareTokenHeader
path Parameters
id
required
string

An identifier

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "direction": "incoming",
  • "name": "string",
  • "source": "string",
  • "state": "string",
  • "created": 0,
  • "updated": 0,
  • "itemDate": 0,
  • "corrOrg": {
    },
  • "corrPerson": {
    },
  • "concPerson": {
    },
  • "concEquipment": {
    },
  • "folder": {
    },
  • "dueDate": 0,
  • "notes": "string",
  • "attachments": [
    ],
  • "sources": [
    ],
  • "archives": [
    ],
  • "tags": [
    ],
  • "customfields": [
    ],
  • "relatedItems": [
    ]
}

Get headers to an attachment file.

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

Authorizations:
shareTokenHeader
path Parameters
id
required
string

An identifier

Responses

Get an attachment file.

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.

Authorizations:
shareTokenHeader
path Parameters
id
required
string

An identifier

Responses

A javascript rendered view of the pdf attachment

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.

Authorizations:
shareTokenHeader
path Parameters
id
required
string

An identifier

Responses

Get the headers to a preview image of an attachment file.

Checks if an image file showing a preview of the attachment is available. If not available, a 404 is returned.

Authorizations:
shareTokenHeader
path Parameters
id
required
string

An identifier

Responses

Get a preview image of an attachment file.

Gets a image file showing a preview of the attachment. Usually it is a small image of the first page of the document.If not available, a 404 is returned. However, if the query parameter withFallback is true, a fallback preview image is returned. You can also use the HEAD method to check for existence.

The attachment must be in the search results of the current share.

Authorizations:
shareTokenHeader
path Parameters
id
required
string

An identifier

query Parameters
withFallback
boolean

Whether to provide a fallback or not.

Responses

Return the client settings of current user

Returns the settings for the share. This is the settings of the collective that belongs to the share.

The clientId is an identifier to a client application. It returns a JSON structure. The server doesn't care about the actual data, since it is meant to be interpreted by clients.

Authorizations:
shareTokenHeader
path Parameters
clientId
required
string

some identifier for a client application

Responses

Response samples

Content type
application/json
null

Return information about a potential zip download

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.

Authorizations:
shareTokenHeader
Request Body schema: application/json
query
required
string <itemquery>
fileType
required
string <downloadalltype>
Enum: "converted" "original"

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "fileType": "converted"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "fileCount": 0,
  • "uncompressedSize": 0,
  • "state": "forbidden"
}

Submits a job to create a zip containing all files in the 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.

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

Authorizations:
shareTokenHeader
Request Body schema: application/json
query
required
string <itemquery>
fileType
required
string <downloadalltype>
Enum: "converted" "original"

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "fileType": "converted"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "fileCount": 0,
  • "uncompressedSize": 0,
  • "state": "forbidden"
}

Download the zip file given the id

Download the zip file to the given id.

Authorizations:
shareTokenHeader
path Parameters
id
required
string

An identifier

Responses

Get a list of shares

Return a list of all shares for this collective.

Authorizations:
authTokenHeader
query Parameters
q
string

A query string.

owning
boolean

Return my own shares only

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a new share.

Create a new share.

Authorizations:
authTokenHeader
Request Body schema: application/json
name
string
query
required
string <itemquery>
enabled
required
boolean
password
string <password>
publishUntil
required
integer <date-time>
removePassword
boolean

For an update request, this can control whether to delete the password. Otherwise if the password is not set, it will not be changed. When adding a new share, this has no effect.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "query": "string",
  • "enabled": true,
  • "password": "pa$$word",
  • "publishUntil": 0,
  • "removePassword": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "id": "string"
}

Send an email.

Sends an email as specified in the body of the request.

An existing shareId must be given with the request, no matter the content of the mail.

Authorizations:
authTokenHeader
path Parameters
name
required
string

An e-mail connection name

Request Body schema: application/json
shareId
required
string <ident>
recipients
required
Array of strings
cc
required
Array of strings
bcc
required
Array of strings
subject
required
string
body
required
string

Responses

Request samples

Content type
application/json
{
  • "shareId": "string",
  • "recipients": [
    ],
  • "cc": [
    ],
  • "bcc": [
    ],
  • "subject": "string",
  • "body": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Get details to a single share.

Given the id of a share, returns some details about it.

Authorizations:
authTokenHeader
path Parameters
shareId
required
string

An identifier for a share

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "query": "string",
  • "owner": {
    },
  • "name": "string",
  • "enabled": true,
  • "publishAt": 0,
  • "publishUntil": 0,
  • "expired": true,
  • "password": true,
  • "views": 0,
  • "lastAccess": 0
}

Update an existing share.

Updates an existing share.

Authorizations:
authTokenHeader
path Parameters
shareId
required
string

An identifier for a share

Request Body schema: application/json
name
string
query
required
string <itemquery>
enabled
required
boolean
password
string <password>
publishUntil
required
integer <date-time>
removePassword
boolean

For an update request, this can control whether to delete the password. Otherwise if the password is not set, it will not be changed. When adding a new share, this has no effect.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "query": "string",
  • "enabled": true,
  • "password": "pa$$word",
  • "publishUntil": 0,
  • "removePassword": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Delete a share.

Deletes a share

Authorizations:
authTokenHeader
path Parameters
shareId
required
string

An identifier for a share

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Tags

Get a list of tags

Return a list of all configured tags. The sort query parameter is optional and can specify how the list is sorted. Possible values are: name, -name, category, -category.

Authorizations:
authTokenHeader
query Parameters
q
string

A query string.

sort
string

How to sort the returned list

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "items": [
    ]
}

Create a new tag.

Create a new tag. If a tag with this name already exists, an error is returned. The id in the input structure is ignored.

Authorizations:
authTokenHeader
Request Body schema: application/json
id
required
string <ident>
name
required
string
category
string
created
required
integer <date-time>

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "category": "string",
  • "created": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Change an existing tag.

Changes an existing tag. The tag is looked up by its id and all properties are changed as given.

Authorizations:
authTokenHeader
Request Body schema: application/json
id
required
string <ident>
name
required
string
category
string
created
required
integer <date-time>

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "category": "string",
  • "created": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Delete a tag.

Deletes a tag. This also removes this tags from all items.

Authorizations:
authTokenHeader
path Parameters
id
required
string

An identifier

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Organization

Get a list of organizations.

Return a list of all organizations. Only name and id are returned. If full is specified, the list contains all organization data. The sort parameter can be either name or -name to specify the order.

Authorizations:
authTokenHeader
query Parameters
full
boolean

Whether to list full data or just name and id.

q
string

A query string.

sort
string

How to sort the returned list

Responses

Response samples

Content type
application/json
Example
{
  • "items": [
    ]
}

Create a new organization.

Create a new organizaion. If an organization with this name already exists, an error is returned. The id attribute of the request structure is ignored.

Authorizations:
authTokenHeader
Request Body schema: application/json
id
required
string <ident>
name
required
string
required
object (Address)

Postal address information.

required
Array of objects (Contact)
notes
string
created
required
integer <date-time>

DateTime

shortName
string
use
required
string <orguse>
Enum: "correspondent" "disabled"

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "address": {
    },
  • "contacts": [
    ],
  • "notes": "string",
  • "created": 0,
  • "shortName": "string",
  • "use": "correspondent"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Change an existing organization.

Changes an existing organization. The organization is looked up by its id and all properties are changed as given.

Authorizations:
authTokenHeader
Request Body schema: application/json
id
required
string <ident>
name
required
string
required
object (Address)

Postal address information.

required
Array of objects (Contact)
notes
string
created
required
integer <date-time>

DateTime

shortName
string
use
required
string <orguse>
Enum: "correspondent" "disabled"

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "address": {
    },
  • "contacts": [
    ],
  • "notes": "string",
  • "created": 0,
  • "shortName": "string",
  • "use": "correspondent"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Get a list of organizations.

Return details about an organization.

Authorizations:
authTokenHeader
path Parameters
id
required
string

An identifier

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "address": {
    },
  • "contacts": [
    ],
  • "notes": "string",
  • "created": 0,
  • "shortName": "string",
  • "use": "correspondent"
}

Delete a organization by its id.

Deletes an organization.

Authorizations:
authTokenHeader
path Parameters
id
required
string

An identifier

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Person

Get a list of persons.

Return a list of all persons. Only name and id are returned unless the full parameter is specified. The sort parameter can be used to control the order of the result. Use one of: name, -name, org, -org. Note that order by org only works when retrieving the full list.

Authorizations:
authTokenHeader
query Parameters
full
boolean

Whether to list full data or just name and id.

q
string

A query string.

sort
string

How to sort the returned list

Responses

Response samples

Content type
application/json
Example
{
  • "items": [
    ]
}

Create a new person.

Create a new organizaion. If an person with this name already exists, an error is returned. The id attribute of the request structure is ignored.

Authorizations:
authTokenHeader
Request Body schema: application/json
id
required
string <ident>
name
required
string
object (IdName)

The identifier and a human readable name of some entity.

required
object (Address)

Postal address information.

required
Array of objects (Contact)
notes
string
use
required
string <personuse>
Enum: "concerning" "correspondent" "both" "disabled"

Whether this person should be used to create suggestions for the "concerning person", "correspondent" or both.

created
required
integer <date-time>

DateTime

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "organization": {
    },
  • "address": {
    },
  • "contacts": [
    ],
  • "notes": "string",
  • "use": "concerning",
  • "created": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Change an existing person.

Changes an existing person. The person is looked up by its id and all properties are changed as given.

Authorizations:
authTokenHeader
Request Body schema: application/json
id
required
string <ident>
name
required
string
object (IdName)

The identifier and a human readable name of some entity.

required
object (Address)

Postal address information.

required
Array of objects (Contact)
notes
string
use
required
string <personuse>
Enum: "concerning" "correspondent" "both" "disabled"

Whether this person should be used to create suggestions for the "concerning person", "correspondent" or both.

created
required
integer <date-time>

DateTime

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "organization": {
    },
  • "address": {
    },
  • "contacts": [
    ],
  • "notes": "string",
  • "use": "concerning",
  • "created": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Get person details.

Return details about an person.

Authorizations:
authTokenHeader
path Parameters
id
required
string

An identifier

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "organization": {
    },
  • "address": {
    },
  • "contacts": [
    ],
  • "notes": "string",
  • "use": "concerning",
  • "created": 0
}

Delete a person by its id.

Deletes an person.

Authorizations:
authTokenHeader
path Parameters
id
required
string

An identifier

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Equipment

Get a list of equipments

Return a list of all configured equipments. The sort query parameter is optional and can be one of name or -name to sort the list of equipments.

Authorizations:
authTokenHeader
query Parameters
q
string

A query string.

sort
string

How to sort the returned list

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a new equipment.

Create a new equipment. If a equipment with this name already exists, an error is returned.

Authorizations:
authTokenHeader
Request Body schema: application/json
id
required
string <ident>
name
required
string
created
required
integer <date-time>

DateTime

notes
string
use
required
string <equipmentuse>
Enum: "concerning" "disabled"

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "created": 0,
  • "notes": "string",
  • "use": "concerning"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Change an existing equipment.

Changes an existing equipment. The equipment is looked up by its id and all properties are changed as given.

Authorizations:
authTokenHeader
Request Body schema: application/json
id
required
string <ident>
name
required
string
created
required
integer <date-time>

DateTime

notes
string
use
required
string <equipmentuse>
Enum: "concerning" "disabled"

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "created": 0,
  • "notes": "string",
  • "use": "concerning"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Get details about a single equipment.

Loads one equipment by its id.

Authorizations:
authTokenHeader
path Parameters
id
required
string

An identifier

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "created": 0,
  • "notes": "string",
  • "use": "concerning"
}

Delete a equipment.

Deletes a equipment. This also removes this equipments from all items.

Authorizations:
authTokenHeader
path Parameters
id
required
string

An identifier

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Folder

Get a list of folders.

Return a list of folders for the current collective.

All folders are returned, including those not owned by the current user.

It is possible to restrict the results by a substring match of the name.

Authorizations:
authTokenHeader
query Parameters
q
string

A query string.

full
boolean

Whether to get owning folders

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a new folder

Create a new folder owned by the current user. If a folder with the same name already exists, an error is thrown.

Authorizations:
authTokenHeader
Request Body schema: application/json
name
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "id": "string"
}

Get folder details.

Return details about a folder.

Authorizations:
authTokenHeader
path Parameters
id
required
string

An identifier

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "owner": {
    },
  • "created": 0,
  • "isMember": true,
  • "memberCount": 0,
  • "members": [
    ]
}

Change the name of a folder

Changes the name of a folder. The new name must not exists.

Authorizations:
authTokenHeader
path Parameters
id
required
string

An identifier

Request Body schema: application/json
name
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Delete a folder by its id.

Deletes a folder.

Authorizations:
authTokenHeader
path Parameters
id
required
string

An identifier

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Add a member to this folder

Adds a member to this folder (identified by id).

Authorizations:
authTokenHeader
path Parameters
id
required
string

An identifier

userId
required
string

An identifier

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Removes a member from this folder.

Removes a member from this folder.

Authorizations:
authTokenHeader
path Parameters
id
required
string

An identifier

userId
required
string

An identifier

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Collective

Get information about your collective

Return some information about the current collective.

Authorizations:
authTokenHeader

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "state": "string",
  • "created": 0
}

Get collective settings

Return the settings of a collective.

Authorizations:
authTokenHeader

Responses

Response samples

Content type
application/json
{
  • "language": "string",
  • "integrationEnabled": true,
  • "classifier": {
    },
  • "emptyTrash": {
    },
  • "passwords": [
    ]
}

Update settings for a collective

Updates settings for a collective.

Authorizations:
authTokenHeader
Request Body schema: application/json
language
required
string <language>
integrationEnabled
required
boolean

Whether the collective has the integration endpoint enabled.

required
object (ClassifierSetting)

Settings for learning a document classifier.

required
object (EmptyTrashSetting)

Settings for clearing the trash of items.

passwords
required
Array of strings <password> [ items <password > ]

Responses

Request samples

Content type
application/json
{
  • "language": "string",
  • "integrationEnabled": true,
  • "classifier": {
    },
  • "emptyTrash": {
    },
  • "passwords": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "state": "string",
  • "created": 0
}

Get some insights regarding your items.

Returns some information about how many items there are, how much folder they occupy etc.

Authorizations:
authTokenHeader

Responses

Response samples

Content type
application/json
{
  • "incomingCount": 0,
  • "outgoingCount": 0,
  • "deletedCount": 0,
  • "itemSize": 0,
  • "tagCloud": {
    }
}

Summary of used tags.

Returns all tags and how often each has been applied.

Authorizations:
authTokenHeader

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Return a list of contacts.

Return a list of all contacts available from the collectives address book.

Authorizations:
authTokenHeader
query Parameters
q
string

A query string.

kind
string

One of the available contact kinds.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Starts the learn-classifier task

If the collective has classification enabled, this will submit the task for learning a classifier from existing data. This task is usally run periodically as determined by the collective settings.

The request is empty, settings are used from the collective.

Authorizations:
authTokenHeader

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Starts the empty trash task

Submits a task to remove all items from the database that have been "soft-deleted". This task is also run periodically and can be triggered here to be immediatly submitted.

The request is empty, settings are used from the collective.

Authorizations:
authTokenHeader
Request Body schema: application/json
schedule
required
string <calevent>
minAge
required
integer <duration>

Responses

Request samples

Content type
application/json
{
  • "schedule": "string",
  • "minAge": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Get a list of collective users.

Return a list of all users of the collective.

Authorizations:
authTokenHeader

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a new collective user.

Create a new collective user. If a user with this name already exists, an error is returned.

Authorizations:
authTokenHeader
Request Body schema: application/json
id
required
string <ident>
login
required
string <ident>
state
required
string <userstate>
Enum: "active" "disabled"
source
required
string <accountsource>
Enum: "local" "openid"
password
string <password>
email
string
lastLogin
integer <date-time>

DateTime

loginCount
required
integer <int32>
created
required
integer <date-time>

DateTime

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "login": "string",
  • "state": "active",
  • "source": "local",
  • "password": "pa$$word",
  • "email": "string",
  • "lastLogin": 0,
  • "loginCount": 0,
  • "created": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Change an existing user.

Changes an existing user. The user is looked up by its id and all properties are changed as given.

Authorizations:
authTokenHeader
Request Body schema: application/json
id
required
string <ident>
login
required
string <ident>
state
required
string <userstate>
Enum: "active" "disabled"
source
required
string <accountsource>
Enum: "local" "openid"
password
string <password>
email
string
lastLogin
integer <date-time>

DateTime

loginCount
required
integer <int32>
created
required
integer <date-time>

DateTime

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "login": "string",
  • "state": "active",
  • "source": "local",
  • "password": "pa$$word",
  • "email": "string",
  • "lastLogin": 0,
  • "loginCount": 0,
  • "created": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Delete a user by its id or login name.

Deletes a user.

Authorizations:
authTokenHeader
path Parameters
username
required
string

The username of a user of this collective

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Shows some data that would be deleted if the user is deleted

Gets some data that would be deleted, when the user with the given username is deleted. The username must be part of this collective.

Authorizations:
authTokenHeader
path Parameters
username
required
string

The username of a user of this collective

Responses

Response samples

Content type
application/json
{
  • "folders": [
    ],
  • "sentMails": 0,
  • "shares": 0
}

Change the password.

Allows users to change their password.

Authorizations:
authTokenHeader
Request Body schema: application/json
currentPassword
required
string <password>
newPassword
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "currentPassword": "pa$$word",
  • "newPassword": "pa$$word"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Gets the otp state for the current user.

Returns whether the current account as OTP enabled or not.

Authorizations:
authTokenHeader

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "created": 0
}

Initialize two factor auth via OTP

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.

Authorizations:
authTokenHeader

Responses

Response samples

Content type
application/json
{
  • "authenticatorUrl": "http://example.com",
  • "secret": "string",
  • "authType": "totp",
  • "issuer": "string"
}

Confirms two factor authentication

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.

Request Body schema: application/json
otp
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "otp": "pa$$word"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Disables two factor authentication.

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.

Request Body schema: application/json
otp
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "otp": "pa$$word"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Reset a user password.

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.

Authorizations:
adminHeader
Request Body schema: application/json
account
required
string <accountid>

Responses

Request samples

Content type
application/json
{
  • "account": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "newPassword": "pa$$word",
  • "message": "string"
}

Disables OTP two factor auth for the given user.

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.

Authorizations:
adminHeader
Request Body schema: application/json
account
required
string <accountid>

Responses

Request samples

Content type
application/json
{
  • "account": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Notification

Return notification channels of the current user

Returns a list of notification channels for the current user.

Authorizations:
authTokenHeader

Responses

Response samples

Content type
application/json
Example
{
  • "id": "string",
  • "name": "string",
  • "channelType": "string",
  • "connection": "string",
  • "recipients": [
    ]
}

Create a new notification channel

Creates a new channel that can be used for notification.

Authorizations:
authTokenHeader
Request Body schema: application/json
One of
id
required
string <ident>
name
string
channelType
required
string <channeltype>
connection
required
string <ident>
recipients
required
Array of strings

Responses

Request samples

Content type
application/json
Example
{
  • "id": "string",
  • "name": "string",
  • "channelType": "string",
  • "connection": "string",
  • "recipients": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Change a notification channel

Change details about a notification channel.

Authorizations:
authTokenHeader
Request Body schema: application/json
One of
id
required
string <ident>
name
string
channelType
required
string <channeltype>
connection
required
string <ident>
recipients
required
Array of strings

Responses

Request samples

Content type
application/json
Example
{
  • "id": "string",
  • "name": "string",
  • "channelType": "string",
  • "connection": "string",
  • "recipients": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Delete a channel

Deletes the channel with the given id. This causes all hooks of this channel to be deleted as well.

Authorizations:
authTokenHeader
path Parameters
id
required
string

An identifier

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Return list of all hooks

Returns a list of all defined hooks for the current user.

Authorizations:
authTokenHeader

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates a new notification hook

Creates a new notification hook, that issues a request via the given channel description.

Authorizations:
authTokenHeader
Request Body schema: application/json
id
required
string <ident>
enabled
required
boolean
Array of objects (NotificationChannelRef)
allEvents
required
boolean
eventFilter
string <jsonminiq>

A filter expression that is applied to the event to be able to ignore a subset of them. See its documentation.

events
required
Array of strings <eventtype> [ items <eventtype > ]
Items Enum: "tagsAdded" "tagsSet"

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "enabled": true,
  • "channels": [
    ],
  • "allEvents": true,
  • "eventFilter": "string",
  • "events": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Updates a notification hook

Updates the hook details.

Authorizations:
authTokenHeader
Request Body schema: application/json
id
required
string <ident>
enabled
required
boolean
Array of objects (NotificationChannelRef)
allEvents
required
boolean
eventFilter
string <jsonminiq>

A filter expression that is applied to the event to be able to ignore a subset of them. See its documentation.

events
required
Array of strings <eventtype> [ items <eventtype > ]
Items Enum: "tagsAdded" "tagsSet"

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "enabled": true,
  • "channels": [
    ],
  • "allEvents": true,
  • "eventFilter": "string",
  • "events": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Delete a hook

Deletes the hook with the given id.

Authorizations:
authTokenHeader
path Parameters
id
required
string

An identifier

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Test a webhook

Tests the webhook specified in the body by applying it to a sample event.

Authorizations:
authTokenHeader
Request Body schema: application/json
id
required
string <ident>
enabled
required
boolean
Array of objects (NotificationChannelRef)
allEvents
required
boolean
eventFilter
string <jsonminiq>

A filter expression that is applied to the event to be able to ignore a subset of them. See its documentation.

events
required
Array of strings <eventtype> [ items <eventtype > ]
Items Enum: "tagsAdded" "tagsSet"

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "enabled": true,
  • "channels": [
    ],
  • "allEvents": true,
  • "eventFilter": "string",
  • "events": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "messages": [
    ]
}

Verify a json filter expression

Parses the given value into a JSON mini query.

Authorizations:
authTokenHeader
Request Body schema: application/json
value
required
string

Responses

Request samples

Content type
application/json
{
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Provide sample event data

Given an event type, generate some random sample of what would be send on such an event.

Authorizations:
authTokenHeader
Request Body schema: application/json
eventType
required
string <eventtype>

Responses

Request samples

Content type
application/json
{
  • "eventType": "string"
}

Response samples

Content type
application/json
null

Query Bookmarks

Return all query bookmarks

Returns all query bookmarks of the current user.

Bookmarks can be "global", where they belong to the whole collective or personal, so they are only for the user. This returns both.

Authorizations:
authTokenHeader

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new query bookmark

Creates a new query bookmark.

A bookmark must have a unique name (within both collective and personal scope). If a name already exists, a failure is returned - use PUT instead for changing existing bookmarks.

Authorizations:
authTokenHeader
Request Body schema: application/json
id
required
string <ident>
name
required
string
label
string
query
required
string <itemquery>
personal
required
boolean
created
required
integer <date-time>

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "label": "string",
  • "query": "string",
  • "personal": true,
  • "created": 0
}

Response samples

Content type
application/json