docspell/website/site/content/docs/api/intro.md

+++
title = "Api Introduction"
description = "Api Basics"
weight = 10
insert_anchor_links = "right"
[extra]
mktoc = true
+++

Docspell is designed as a REST server that uses JSON to exchange
data. The REST api can be used to integrate docspell into your
workflow.

[Docspell REST Api Doc](/openapi/docspell-openapi.html)

The "raw" `openapi.yml` specification file can be found
[here](/openapi/docspell-openapi.yml).

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 `/share/*`, while admin routes
are at `/admin/*`. Open routes don't require authenticated access and
can be used by any user. The protected routes require either an
authenticated user (for `/sec/*`) or a valid share id and possibly the
password (for `/share/*`). 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.

## Authentication

The unprotected route `/open/auth/login` can be used to login with
account name and password. The response contains a token that can be
used for accessing protected routes. The token is only valid for a
restricted time which can be configured (default is 5 minutes).

New tokens can be generated using an existing valid token and the
protected route `/sec/auth/session`. This will return the same
response as above, giving a new token.

This token can be added to requests in two ways: as a cookie header or
a "normal" http header. If a cookie header is used, the cookie name
must be `docspell_auth` and a custom header must be named
`X-Docspell-Auth`.

The admin route (see below) `/admin/user/resetPassword` can be used to
reset a password of a user.

To authenticate for a share, the `/open/share/verify` endpoint must be
used. It expects the share id and possibly a password. If the share
requires a password, but it was not specified in the request, the
response indicates this. The request must then be replayed with the
correct password to retrieve a token. This token can then be used to
all `/share/*` endpoints to identify the share - analog to the
protected `/sec/*` routes. It can be either specfied as a cookie or
via the header `Docspell-Share-Auth`.


### OpenID Connect

Docspell can be configured to be a relying party for OpenID Connect.
Please see [the config
section](@/docs/configure/_index.md#openid-connect-oauth2) for
details.


## Admin

There are some endpoints available for adminstration tasks, for
example re-creating the complete fulltext index or resetting a
password. These endpoints are not available to normal users, but to
admins only. Docspell has no special admin users, it simply uses a
secret defined in the configuration file. The person who installs
docspell is the admin and knows this secret (and may share it) and
requests must provide it as a http header `Docspell-Admin-Secret`.

Example: re-create the fulltext index (over all collectives):

``` bash
$ curl -XPOST -H "Docspell-Admin-Secret: test123" http://localhost:7880/api/v1/admin/fts/reIndexAll
```

To enable these endpoints, you must provide a secret in the
[configuration](@/docs/configure/_index.md#admin-endpoint).

## Live Api

Besides the statically generated documentation at this site, the rest
server provides a swagger generated api documenation, that allows
playing around with the api. It requires a running docspell rest
server. If it is deployed at `http://localhost:7880`, then check this
url:

```
http://localhost:7880/api/doc
```

## Examples

These examples use the great command line tool
[curl](https://curl.haxx.se/).

### Login

``` bash
$ curl -X POST -d '{"account": "smith", "password": "test"}' http://localhost:7880/api/v1/open/auth/login
{"collective":"smith"
,"user":"smith"
,"success":true
,"message":"Login successful"
,"token":"1568142350115-ZWlrZS9laWtl-$2a$10$rGZUFDAVNIKh4Tj6u6tlI.-O2euwCvmBT0TlyDmIHR1ZsLQPAI="
,"validMs":300000
}
```

### Get new token

``` bash
$ curl -XPOST -H 'X-Docspell-Auth: 1568142350115-ZWlrZS9laWtl-$2a$10$rGZUFDAVNIKh4Tj6u6tlI.-O2euwCvmBT0TlyDmIHR1ZsLQPAI=' http://localhost:7880/api/v1/sec/auth/session
{"collective":"smith"
,"user":"smith"
,"success":true
,"message":"Login successful"
,"token":"1568142446077-ZWlrZS9laWtl-$2a$10$3B0teJ9rMpsBJPzHfZZPoO-WeA1bkfEONBN8fyzWE8DeaAHtUc="
,"validMs":300000
}
```

### Get some insights

``` bash
$ curl -H 'X-Docspell-Auth: 1568142446077-ZWlrZS9laWtl-$2a$10$3B0teJ9rMpsBJPzHfZZPoO-WeA1bkfEONBN8fyzWE8DeaAHtUc=' http://localhost:7880/api/v1/sec/collective/insights
{"incomingCount":3
,"outgoingCount":1
,"itemSize":207310
,"tagCloud":{"items":[]}
}
```

### Search for items

``` bash
$ curl -i -H 'X-Docspell-Auth: 1615240493…kYtFynj4' \
  'http://localhost:7880/api/v1/sec/item/search?q=tag=todo,invoice%20year:2021'
{
  "groups": [
    {
      "name": "2021-02",
      "items": [
        {
          "id": "41J962DjS7T-sjP9idxJ6o9-hJrmBk34YJN-mQqysHwcFD6",
          "name": "something.txt",
          "state": "confirmed",
          "date": 1613598750202,
          "dueDate": 1617883200000,
          "source": "webapp",
          "direction": "outgoing",
          "corrOrg": {
            "id": "J58tYifCh4X-cze5R8eSJcc-YAFr6qt1VKL-1ZmhRwiTXoH",
            "name": "EasyCare AG"
          },
          "corrPerson": null,
          "concPerson": null,
          "concEquipment": null,
          "folder": {
            "id": "GKwSvYVdvfb-QeAwzzT7pBM-Gbji2hQc2bL-uCyrMCAg3wo",
            "name": "test"
          },
          "attachments": [],
          "tags": [],
          "customfields": [],
          "notes": null,
          "highlighting": []
        }
      ]
    },
    {
      "name": "2021-01",
      "items": [
        {
          "id": "ANqtuDynXWU-PrhzUxzQVmH-PDuJfeJ6dYB-Ut3g1jrcFhw",
          "name": "letter-de.pdf",
          "state": "confirmed",
          "date": 1611144000000,
          "dueDate": null,
          "source": "webapp",
          "direction": "incoming",
          "corrOrg": {
            "id": "J58tYifCh4X-cze5R8eSJcc-YAFr6qt1VKL-1ZmhRwiTXoH",
            "name": "EasyCare AG"
          },
          "corrPerson": null,
          "concPerson": {
            "id": "AA5sV1nH9ve-mDCn4DxDRvu-tWkUquiW4fZ-fVJimW4Vq79",
            "name": "Max Mustermann"
          },
          "concEquipment": null,
          "folder": null,
          "attachments": [],
          "tags": [],
          "customfields": [],
          "notes": null,
          "highlighting": []
        }
      ]
    }
  ]
}
```