Download OpenAPI specification:Download
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.
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.
account required | string |
password required | string |
rememberMe | boolean |
{- "account": "string",
- "password": "string",
- "rememberMe": true
}
{- "collective": "string",
- "user": "string",
- "success": true,
- "message": "string",
- "token": "string",
- "validMs": 0,
- "requireSecondFactor": true
}
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.
token required | string |
otp required | string <password> |
rememberMe required | boolean |
{- "token": "string",
- "otp": "pa$$word",
- "rememberMe": true
}
{- "collective": "string",
- "user": "string",
- "success": true,
- "message": "string",
- "token": "string",
- "validMs": 0,
- "requireSecondFactor": true
}
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.
providerId required | string <ident> |
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.
providerId required | string <ident> |
Authenticate with a token. This can be used to get a new authentication token based on another valid one.
{- "collective": "string",
- "user": "string",
- "success": true,
- "message": "string",
- "token": "string",
- "validMs": 0,
- "requireSecondFactor": true
}
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.
{- "secret": "string",
- "authType": "totp",
- "issuer": "string"
}
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.
otp required | string <password> |
{- "otp": "pa$$word"
}
{- "success": true,
- "message": "string"
}
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.
otp required | string <password> |
{- "otp": "pa$$word"
}
{- "success": true,
- "message": "string"
}
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.
id required | string An identifier |
checksum required | string A SHA-256 checksum |
{- "exists": true,
- "items": [
- {
- "id": "string",
- "name": "string",
- "direction": "string",
- "state": "string",
- "created": 0,
- "itemDate": 0
}
]
}
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.
id required | string An identifier |
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 > ] |
{- "success": true,
- "message": "string"
}
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.
id required | string An identifier |
itemId required | string An identifier for an item |
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 > ] |
{- "success": true,
- "message": "string"
}
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.
checksum required | string A SHA-256 checksum |
{- "exists": true,
- "items": [
- {
- "id": "string",
- "name": "string",
- "direction": "string",
- "state": "string",
- "created": 0,
- "itemDate": 0
}
]
}
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.
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 > ] |
{- "success": true,
- "message": "string"
}
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.
itemId required | string An identifier for an item |
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 > ] |
{- "success": true,
- "message": "string"
}
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:
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.
id required | string An identifier |
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 > ] |
{- "success": true,
- "message": "string"
}
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.
id required | string An identifier |
checksum required | string A SHA-256 checksum |
{- "exists": true,
- "items": [
- {
- "id": "string",
- "name": "string",
- "direction": "string",
- "state": "string",
- "created": 0,
- "itemDate": 0
}
]
}
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
.
{- "success": true,
- "message": "string"
}
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.
{- "success": true,
- "message": "string"
}
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
.
{- "success": true,
- "message": "string"
}
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
.
account required | string <accountid> |
{- "account": "string"
}
{- "success": true,
- "newPassword": "pa$$word",
- "message": "string"
}
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.
account required | string <accountid> |
{- "account": "string"
}
{- "success": true,
- "message": "string"
}
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
.
{- "success": true,
- "message": "string"
}
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.
{- "success": true,
- "message": "string"
}
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.
targetRepositories required | Array of strings <ident> [ items <ident > ] |
{- "targetRepositories": [
- "string"
]
}
{- "success": true,
- "message": "string"
}
Submits a task that goes through the files and compares the stored checksum (at the time of inserting) against a newly calculated one.
collective | string <ident> |
{- "collective": "string"
}
{- "success": true,
- "message": "string"
}
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.
query required | string <itemquery> |
fileType required | string <downloadalltype> Enum: "converted" "original" |
{- "query": "string",
- "fileType": "converted"
}
{- "id": "string",
- "fileCount": 0,
- "uncompressedSize": 0,
- "state": "forbidden"
}
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.
query required | string <itemquery> |
fileType required | string <downloadalltype> Enum: "converted" "original" |
{- "query": "string",
- "fileType": "converted"
}
{- "id": "string",
- "fileCount": 0,
- "uncompressedSize": 0,
- "state": "forbidden"
}
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.
id required | string An identifier |
{- "success": true,
- "message": "string"
}
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).
id required | string An identifier |
{ }
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:
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.
id required | string An identifier |
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 > ] |
{- "success": true,
- "message": "string"
}
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.
id required | string An identifier |
checksum required | string A SHA-256 checksum |
{- "exists": true,
- "items": [
- {
- "id": "string",
- "name": "string",
- "direction": "string",
- "state": "string",
- "created": 0,
- "itemDate": 0
}
]
}
Create a new account by creating a collective and user.
collectiveName required | string <ident> |
login required | string <ident> |
password required | string <password> |
invite | string <ident> |
{- "collectiveName": "string",
- "login": "string",
- "password": "pa$$word",
- "invite": "string"
}
{- "success": true,
- "message": "string"
}
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.
password required | string <password> |
{- "password": "pa$$word"
}
{- "success": true,
- "message": "string",
- "key": "string"
}
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
.
q | string A query string. |
sort | string How to sort the returned list |
{- "count": 0,
- "items": [
- {
- "id": "string",
- "name": "string",
- "category": "string",
- "created": 0
}
]
}
Create a new tag. If a tag with this name already exists, an error is returned. The id in the input structure is ignored.
id required | string <ident> |
name required | string |
category | string |
created required | integer <date-time> |
{- "id": "string",
- "name": "string",
- "category": "string",
- "created": 0
}
{- "success": true,
- "message": "string"
}
Changes an existing tag. The tag is looked up by its id and all properties are changed as given.
id required | string <ident> |
name required | string |
category | string |
created required | integer <date-time> |
{- "id": "string",
- "name": "string",
- "category": "string",
- "created": 0
}
{- "success": true,
- "message": "string"
}
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.
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 |
{- "items": [
- {
- "id": "string",
- "name": "string"
}
]
}
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.
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" |
{- "id": "string",
- "name": "string",
- "address": {
- "street": "string",
- "zip": "string",
- "city": "string",
- "country": "string"
}, - "contacts": [
- {
- "id": "string",
- "value": "string",
- "kind": "phone"
}
], - "notes": "string",
- "created": 0,
- "shortName": "string",
- "use": "correspondent"
}
{- "success": true,
- "message": "string"
}
Changes an existing organization. The organization is looked up by its id and all properties are changed as given.
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" |
{- "id": "string",
- "name": "string",
- "address": {
- "street": "string",
- "zip": "string",
- "city": "string",
- "country": "string"
}, - "contacts": [
- {
- "id": "string",
- "value": "string",
- "kind": "phone"
}
], - "notes": "string",
- "created": 0,
- "shortName": "string",
- "use": "correspondent"
}
{- "success": true,
- "message": "string"
}
Return details about an organization.
id required | string An identifier |
{- "id": "string",
- "name": "string",
- "address": {
- "street": "string",
- "zip": "string",
- "city": "string",
- "country": "string"
}, - "contacts": [
- {
- "id": "string",
- "value": "string",
- "kind": "phone"
}
], - "notes": "string",
- "created": 0,
- "shortName": "string",
- "use": "correspondent"
}
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.
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 |
{- "items": [
- {
- "id": "string",
- "name": "string"
}
]
}
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.
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 |
{- "id": "string",
- "name": "string",
- "organization": {
- "id": "string",
- "name": "string"
}, - "address": {
- "street": "string",
- "zip": "string",
- "city": "string",
- "country": "string"
}, - "contacts": [
- {
- "id": "string",
- "value": "string",
- "kind": "phone"
}
], - "notes": "string",
- "use": "concerning",
- "created": 0
}
{- "success": true,
- "message": "string"
}
Changes an existing person. The person is looked up by its id and all properties are changed as given.
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 |
{- "id": "string",
- "name": "string",
- "organization": {
- "id": "string",
- "name": "string"
}, - "address": {
- "street": "string",
- "zip": "string",
- "city": "string",
- "country": "string"
}, - "contacts": [
- {
- "id": "string",
- "value": "string",
- "kind": "phone"
}
], - "notes": "string",
- "use": "concerning",
- "created": 0
}
{- "success": true,
- "message": "string"
}
Return details about an person.
id required | string An identifier |
{- "id": "string",
- "name": "string",
- "organization": {
- "id": "string",
- "name": "string"
}, - "address": {
- "street": "string",
- "zip": "string",
- "city": "string",
- "country": "string"
}, - "contacts": [
- {
- "id": "string",
- "value": "string",
- "kind": "phone"
}
], - "notes": "string",
- "use": "concerning",
- "created": 0
}
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.
q | string A query string. |
sort | string How to sort the returned list |
{- "items": [
- {
- "id": "string",
- "name": "string",
- "created": 0,
- "notes": "string",
- "use": "concerning"
}
]
}
Create a new equipment. If a equipment with this name already exists, an error is returned.
id required | string <ident> |
name required | string |
created required | integer <date-time> DateTime |
notes | string |
use required | string <equipmentuse> Enum: "concerning" "disabled" |
{- "id": "string",
- "name": "string",
- "created": 0,
- "notes": "string",
- "use": "concerning"
}
{- "success": true,
- "message": "string"
}
Changes an existing equipment. The equipment is looked up by its id and all properties are changed as given.
id required | string <ident> |
name required | string |
created required | integer <date-time> DateTime |
notes | string |
use required | string <equipmentuse> Enum: "concerning" "disabled" |
{- "id": "string",
- "name": "string",
- "created": 0,
- "notes": "string",
- "use": "concerning"
}
{- "success": true,
- "message": "string"
}
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.
q | string A query string. |
full | boolean Whether to get owning folders |
{- "items": [
- {
- "id": "string",
- "name": "string",
- "owner": {
- "id": "string",
- "name": "string"
}, - "created": 0,
- "isMember": true,
- "memberCount": 0
}
]
}
Create a new folder owned by the current user. If a folder with the same name already exists, an error is thrown.
name required | string |
{- "name": "string"
}
{- "success": true,
- "message": "string",
- "id": "string"
}
Return details about a folder.
id required | string An identifier |
{- "id": "string",
- "name": "string",
- "owner": {
- "id": "string",
- "name": "string"
}, - "created": 0,
- "isMember": true,
- "memberCount": 0,
- "members": [
- {
- "id": "string",
- "name": "string"
}
]
}
Changes the name of a folder. The new name must not exists.
id required | string An identifier |
name required | string |
{- "name": "string"
}
{- "success": true,
- "message": "string"
}
Return the settings of a collective.
{- "language": "string",
- "integrationEnabled": true,
- "classifier": {
- "itemCount": 0,
- "schedule": "string",
- "categoryList": [
- "string"
], - "listType": "blacklist"
}, - "emptyTrash": {
- "schedule": "string",
- "minAge": 0
}, - "passwords": [
- "pa$$word"
]
}
Updates settings for a collective.
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 > ] |
{- "language": "string",
- "integrationEnabled": true,
- "classifier": {
- "itemCount": 0,
- "schedule": "string",
- "categoryList": [
- "string"
], - "listType": "blacklist"
}, - "emptyTrash": {
- "schedule": "string",
- "minAge": 0
}, - "passwords": [
- "pa$$word"
]
}
{- "id": "string",
- "state": "string",
- "created": 0
}
Returns some information about how many items there are, how much folder they occupy etc.
{- "incomingCount": 0,
- "outgoingCount": 0,
- "deletedCount": 0,
- "itemSize": 0,
- "tagCloud": {
- "items": [
- {
- "tag": {
- "id": "string",
- "name": "string",
- "category": "string",
- "created": 0
}, - "count": 0
}
]
}
}
Return a list of all contacts available from the collectives address book.
q | string A query string. |
kind | string One of the available contact kinds. |
{- "items": [
- {
- "id": "string",
- "value": "string",
- "kind": "phone"
}
]
}
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.
{- "success": true,
- "message": "string"
}
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.
schedule required | string <calevent> |
minAge required | integer <duration> |
{- "schedule": "string",
- "minAge": 0
}
{- "success": true,
- "message": "string"
}
Return a list of all users of the collective.
{- "items": [
- {
- "id": "string",
- "login": "string",
- "state": "active",
- "source": "local",
- "password": "pa$$word",
- "email": "string",
- "lastLogin": 0,
- "loginCount": 0,
- "created": 0
}
]
}
Create a new collective user. If a user with this name already exists, an error is returned.
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> |
string | |
lastLogin | integer <date-time> DateTime |
loginCount required | integer <int32> |
created required | integer <date-time> DateTime |
{- "id": "string",
- "login": "string",
- "state": "active",
- "source": "local",
- "password": "pa$$word",
- "email": "string",
- "lastLogin": 0,
- "loginCount": 0,
- "created": 0
}
{- "success": true,
- "message": "string"
}
Changes an existing user. The user is looked up by its id and all properties are changed as given.
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> |
string | |
lastLogin | integer <date-time> DateTime |
loginCount required | integer <int32> |
created required | integer <date-time> DateTime |
{- "id": "string",
- "login": "string",
- "state": "active",
- "source": "local",
- "password": "pa$$word",
- "email": "string",
- "lastLogin": 0,
- "loginCount": 0,
- "created": 0
}
{- "success": true,
- "message": "string"
}
Gets some data that would be deleted, when the user with the
given username is deleted. The username
must be part of this
collective.
username required | string The username of a user of this collective |
{- "folders": [
- "string"
], - "sentMails": 0,
- "shares": 0
}
Allows users to change their password.
currentPassword required | string <password> |
newPassword required | string <password> |
{- "currentPassword": "pa$$word",
- "newPassword": "pa$$word"
}
{- "success": true,
- "message": "string"
}
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.
{- "secret": "string",
- "authType": "totp",
- "issuer": "string"
}
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.
otp required | string <password> |
{- "otp": "pa$$word"
}
{- "success": true,
- "message": "string"
}
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.
otp required | string <password> |
{- "otp": "pa$$word"
}
{- "success": true,
- "message": "string"
}
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
.
account required | string <accountid> |
{- "account": "string"
}
{- "success": true,
- "newPassword": "pa$$word",
- "message": "string"
}
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.
account required | string <accountid> |
{- "account": "string"
}
{- "success": true,
- "message": "string"
}
Returns a list of notification channels for the current user.
{- "id": "string",
- "name": "string",
- "channelType": "string",
- "connection": "string",
- "recipients": [
- "string"
]
}
Creates a new channel that can be used for notification.
id required | string <ident> |
name | string |
channelType required | string <channeltype> |
connection required | string <ident> |
recipients required | Array of strings |
{- "id": "string",
- "name": "string",
- "channelType": "string",
- "connection": "string",
- "recipients": [
- "string"
]
}
{- "success": true,
- "message": "string"
}
Change details about a notification channel.
id required | string <ident> |
name | string |
channelType required | string <channeltype> |
connection required | string <ident> |
recipients required | Array of strings |
{- "id": "string",
- "name": "string",
- "channelType": "string",
- "connection": "string",
- "recipients": [
- "string"
]
}
{- "success": true,
- "message": "string"
}
Returns a list of all defined hooks for the current user.
[- {
- "id": "string",
- "enabled": true,
- "channels": [
- {
- "id": "string",
- "channelType": "string",
- "name": "string"
}
], - "allEvents": true,
- "eventFilter": "string",
- "events": [
- "tagsAdded"
]
}
]
Creates a new notification hook, that issues a request via the given channel description.
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" |
{- "id": "string",
- "enabled": true,
- "channels": [
- {
- "id": "string",
- "channelType": "string",
- "name": "string"
}
], - "allEvents": true,
- "eventFilter": "string",
- "events": [
- "tagsAdded"
]
}
{- "success": true,
- "message": "string"
}
Updates the hook details.
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" |
{- "id": "string",
- "enabled": true,
- "channels": [
- {
- "id": "string",
- "channelType": "string",
- "name": "string"
}
], - "allEvents": true,
- "eventFilter": "string",
- "events": [
- "tagsAdded"
]
}
{- "success": true,
- "message": "string"
}
Tests the webhook specified in the body by applying it to a sample event.
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" |
{- "id": "string",
- "enabled": true,
- "channels": [
- {
- "id": "string",
- "channelType": "string",
- "name": "string"
}
], - "allEvents": true,
- "eventFilter": "string",
- "events": [
- "tagsAdded"
]
}
{- "success": true,
- "messages": [
- "string"
]
}
Parses the given value into a JSON mini query.
value required | string |
{- "value": "string"
}
{- "success": true,
- "message": "string"
}
Given an event type, generate some random sample of what would be send on such an event.
eventType required | string <eventtype> |
{- "eventType": "string"
}
null
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.
[- {
- "id": "string",
- "name": "string",
- "label": "string",
- "query": "string",
- "personal": true,
- "created": 0
}
]
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.
id required | string <ident> |
name required | string |
label | string |
query required | string <itemquery> |
personal required | boolean |
created required | integer <date-time> |
{- "id": "string",
- "name": "string",
- "label": "string",
- "query": "string",
- "personal": true,
- "created": 0
}