docspell-openapi.yml

openapi: 3.0.0

info:
  title: Docspell
  version: 0.44.0-SNAPSHOT
  description: |
    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.
  license:
    name: AGPLv3
    url: https://spdx.org/licenses/AGPL-3.0-or-later.html

externalDocs:
  description: Docspell Homepage
  url: https://docspell.org

servers:
  - url: /api/v1
    description: Current host

security: []

paths:
  /api/info/version:
    get:
      operationId: "api-info-version"
      tags: [ Information ]
      summary: Get version information.
      description: |
        Returns information about this software.
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VersionInfo"

  /open/auth/login:
    post:
      operationId: "open-auth-login"
      tags: [ Authentication ]
      summary: Authenticate with account name and password.
      description: |
        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.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserPass"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthResult"
  /open/auth/two-factor:
    post:
      operationId: "open-auth-two-factor"
      tags: [ Authentication ]
      summary: Provide the second factor to finalize authentication
      description: |
        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.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SecondFactor"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthResult"
  /open/auth/openid/{providerId}:
    get:
      operationId: "open-auth-openid"
      tags: [ Authentication ]
      summary: Authenticates via OIDC at the external provider given by its id
      description: |
        Initiates the ["Authorization Code
        Flow"](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth)
        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.
      parameters:
        - $ref: "#/components/parameters/providerId"
      responses:
        422:
          description: BadRequest
        302:
          description: Found. Redirect to external authentication provider
        200:
          description: Not used, is only here because openid requires it
  /open/auth/openid/{providerId}/resume:
    get:
      operationId: "open-auth-openid-resume"
      tags: [ Authentication ]
      summary: The callback URL for the authentication provider
      description: |
        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.
      parameters:
        - $ref: "#/components/parameters/providerId"
      responses:
        422:
          description: BadRequest
        303:
          description: See Other. Redirect to the webapp
        200:
          description: Not used, is only here because openid requires it

  /open/checkfile/{id}/{checksum}:
    get:
      operationId: "open-checkfile-checksum-by-id"
      tags: [ Upload ]
      summary: Check if a file is in docspell (via source).
      description: |
        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.
      parameters:
        - $ref: "#/components/parameters/id"
        - $ref: "#/components/parameters/checksum"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CheckFileResult"
  /open/upload/item/{id}:
    post:
      operationId: "open-upload-new-item-by-source"
      tags: [ Upload ]
      summary: Upload files to docspell (via source).
      description: |
        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.
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                meta:
                  $ref: "#/components/schemas/ItemUploadMeta"
                file:
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /open/upload/item/{itemId}/{id}:
    post:
      operationId: "open-upload-to-item-by-source"
      tags: [ Upload ]
      summary: Upload files to an existing item (via source).
      description: |
        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.
      parameters:
        - $ref: "#/components/parameters/id"
        - $ref: "#/components/parameters/itemId"
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                meta:
                  $ref: "#/components/schemas/ItemUploadMeta"
                file:
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /admin/fts/reIndexAll:
    post:
      operationId: "admin-fts-reindex-all"
      tags: [Full-Text Index, Admin]
      summary: Re-creates the full-text index.
      description: |
        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`.
      security:
        - adminHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/fts/reIndex:
    post:
      operationId: "sec-fts-reindex"
      tags: [Full-Text Index]
      summary: Re-creates the full-text index for the current collective
      description: |
        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:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/checkfile/{checksum}:
    get:
      operationId: "sec-checkfile-by-checksum"
      tags: [ Upload ]
      summary: Check if a file is in docspell (authenticated).
      description: |
        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.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/checksum"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CheckFileResult"

  /sec/upload/item:
    post:
      operationId: "sec-upload-new-item"
      tags: [ Upload ]
      summary: Upload files to docspell (authenticated).
      description: |
        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.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                meta:
                  $ref: "#/components/schemas/ItemUploadMeta"
                file:
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/upload/{itemId}:
    post:
      operationId: "sec-upload-to-item"
      tags: [ Upload ]
      summary: Upload files to an existing item (authenticated).
      description: |
        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.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/itemId"
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                meta:
                  $ref: "#/components/schemas/ItemUploadMeta"
                file:
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/downloadAll/prefetch:
    post:
      operationId: "sec-downloadall-prefetch"
      tags: [Download]
      summary: Return information about a potential zip download
      description: |
        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.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DownloadAllRequest"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DownloadAllSummary"
  /sec/downloadAll/submit:
    post:
      operationId: "sec-downloadall-submit"
      tags: [Download]
      summary: Submits a job to create a zip containing all files in the query
      description: |
        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.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DownloadAllRequest"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DownloadAllSummary"

  /sec/downloadAll/cancel/{id}:
    put:
      operationId: "sec-downloadall-cancel"
      tags: [Download]
      summary: Cancels potentially running jobs to create a download archive
      description: |
        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.
      parameters:
        - $ref: "#/components/parameters/id"
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"      

  /sec/downloadAll/file/{id}:
    get:
      operationId: "sec-downloadall-get-file"
      tags: [Download]
      summary: Download the zip file given the id
      description: |
        Download the zip file to the given id.
      parameters:
        - $ref: "#/components/parameters/id"
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        404:
          description: NotFound
        200:
          description: Ok
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
    delete:
      operationId: "sec-downloadall-delete-file"
      tags: [Download]
      summary: Deletets the zip file given the id
      description: |
        Deletes the zip file to the given id.
      parameters:
        - $ref: "#/components/parameters/id"
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"      

  /open/integration/item/{id}:
    get:
      operationId: "open-integration-item-check-collective"
      tags: [ Integration Endpoint ]
      summary: Check if integration endpoint is available.
      description: |
        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).
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                type: object
        404:
          description: Not Found
        403:
          description: Forbidden
        401:
          description: Unauthorized
    post:
      operationId: "open-integration-item-upload"
      tags: [ Integration Endpoint, Upload ]
      summary: Upload files to docspell (Integration Endpoint).
      description: |
        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.
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                meta:
                  $ref: "#/components/schemas/ItemUploadMeta"
                file:
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /open/integration/checkfile/{id}/{checksum}:
    get:
      operationId: "open-integration-checkfile-by-checksum"
      tags: [ Integration Endpoint, Upload ]
      summary: Check if a file is in docspell (Integration Endpoint).
      description: |
        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.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
        - $ref: "#/components/parameters/checksum"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CheckFileResult"

  /open/signup/register:
    post:
      operationId: "open-signup-register"
      tags: [ Registration ]
      summary: Register a new account.
      description: |
        Create a new account by creating a collective and user.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Registration"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /open/signup/newinvite:
    post:
      operationId: "open-signup-newinvite"
      tags: [ Registration ]
      summary: Generate a new invite.
      description: |
        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.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GenInvite"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InviteResult"

  /open/share/verify:
    post:
      operationId: "open-share-verify"
      tags: [ Share ]
      summary: Verify a secret for a share
      description: |
        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.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ShareSecret"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ShareVerifyResult"

  /sec/auth/session:
    post:
      operationId: "sec-auth-session"
      tags: [ Authentication ]
      summary: Authentication with a token
      description: |
        Authenticate with a token. This can be used to get a new
        authentication token based on another valid one.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthResult"
  /sec/auth/logout:
    post:
      operationId: "sec-auth-logout"
      tags: [ Authentication ]
      summary: Logout.
      description: |
        This route informs the server about a logout. This is not
        strictly necessary.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok

  /sec/tag:
    get:
      operationId: "sec-tag-get-all"
      tags: [ Tags ]
      summary: Get a list of tags
      description: |
        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`.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/q"
        - $ref: "#/components/parameters/sort"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagList"
    post:
      operationId: "sec-tag-new"
      tags: [ Tags ]
      summary: Create a new tag.
      description: |
        Create a new tag. If a tag with this name already exists, an
        error is returned. The id in the input structure is ignored.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Tag"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    put:
      operationId: "sec-tag-edit"
      tags: [ Tags ]
      summary: Change an existing tag.
      description: |
        Changes an existing tag. The tag is looked up by its id and
        all properties are changed as given.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Tag"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/tag/{id}:
    delete:
      operationId: "sec-tag-delete-by-id"
      tags: [ Tags ]
      summary: Delete a tag.
      description: |
        Deletes a tag. This also removes this tags from all items.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/organization:
    get:
      operationId: "sec-org-get-all"
      tags: [ Organization ]
      summary: Get a list of organizations.
      description: |
        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.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/full"
        - $ref: "#/components/parameters/q"
        - $ref: "#/components/parameters/sort"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ReferenceList"
                  - $ref: "#/components/schemas/OrganizationList"
    post:
      operationId: "sec-org-new"
      tags: [ Organization ]
      summary: Create a new organization.
      description: |
        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.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Organization"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    put:
      operationId: "sec-org-edit"
      tags: [ Organization ]
      summary: Change an existing organization.
      description: |
        Changes an existing organization. The organization is looked up by its id and
        all properties are changed as given.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Organization"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/organization/{id}:
    get:
      operationId: "sec-org-details"
      tags: [ Organization ]
      summary: Get a list of organizations.
      description: |
        Return details about an organization.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
    delete:
      operationId: "sec-org-delete-by-id"
      tags: [ Organization ]
      summary: Delete a organization by its id.
      description: |
        Deletes an organization.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/person:
    get:
      operationId: "sec-persion-get-all"
      tags: [ Person ]
      summary: Get a list of persons.
      description: |
        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.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/full"
        - $ref: "#/components/parameters/q"
        - $ref: "#/components/parameters/sort"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ReferenceList"
                  - $ref: "#/components/schemas/PersonList"
    post:
      operationId: "sec-person-new"
      tags: [ Person ]
      summary: Create a new person.
      description: |
        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.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Person"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    put:
      operationId: "sec-person-edit"
      tags: [ Person ]
      summary: Change an existing person.
      description: |
        Changes an existing person. The person is looked up by its id and
        all properties are changed as given.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Person"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/person/{id}:
    get:
      operationId: "sec-person-details"
      tags: [ Person ]
      summary: Get person details.
      description: |
        Return details about an person.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Person"
    delete:
      operationId: "sec-person-delete-by-id"
      tags: [ Person ]
      summary: Delete a person by its id.
      description: |
        Deletes an person.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/equipment:
    get:
      operationId: "sec-equip-get-all"
      tags: [ Equipment ]
      summary: Get a list of equipments
      description: |
        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.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/q"
        - $ref: "#/components/parameters/sort"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EquipmentList"
    post:
      operationId: "sec-equip-new"
      tags: [ Equipment ]
      summary: Create a new equipment.
      description: |
        Create a new equipment. If a equipment with this name already
        exists, an error is returned.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Equipment"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    put:
      operationId: "sec-equip-edit"
      tags: [ Equipment ]
      summary: Change an existing equipment.
      description: |
        Changes an existing equipment. The equipment is looked up by
        its id and all properties are changed as given.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Equipment"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/equipment/{id}:
    get:
      operationId: "sec-equip-details"
      tags: [ Equipment ]
      summary: Get details about a single equipment.
      description: |
        Loads one equipment by its id.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Equipment"

    delete:
      operationId: "sec-equip-delete-by-id"
      tags: [ Equipment ]
      summary: Delete a equipment.
      description: |
        Deletes a equipment. This also removes this equipments from
        all items.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/folder:
    get:
      operationId: "sec-folder-get-all"
      tags: [ Folder ]
      summary: Get a list of folders.
      description: |
        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.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/q"
        - $ref: "#/components/parameters/owning"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FolderList"
    post:
      operationId: "sec-folder-new"
      tags: [ Folder ]
      summary: Create a new folder
      description: |
        Create a new folder owned by the current user. If a folder with
        the same name already exists, an error is thrown.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewFolder"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdResult"
  /sec/folder/{id}:
    get:
      operationId: "sec-folder-details"
      tags: [ Folder ]
      summary: Get folder details.
      description: |
        Return details about a folder.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FolderDetail"
    put:
      operationId: "sec-folder-edit-name"
      tags: [ Folder ]
      summary: Change the name of a folder
      description: |
        Changes the name of a folder. The new name must not exists.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewFolder"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    delete:
      operationId: "sec-folder-delete-by-id"
      tags: [ Folder ]
      summary: Delete a folder by its id.
      description: |
        Deletes a folder.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/folder/{id}/member/{userId}:
    put:
      operationId: "sec-folder-add-member"
      tags: [ Folder ]
      summary: Add a member to this folder
      description: |
        Adds a member to this folder (identified by `id`).
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
        - $ref: "#/components/parameters/userId"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    delete:
      operationId: "sec-folder-delete-member"
      tags: [ Folder ]
      summary: Removes a member from this folder.
      description: |
        Removes a member from this folder.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
        - $ref: "#/components/parameters/userId"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/collective:
    get:
      operationId: "sec-collective-get-all"
      tags: [ Collective ]
      summary: Get information about your collective
      description: |
        Return some information about the current collective.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Collective"
  /sec/collective/settings:
    get:
      operationId: "sec-collective-get-settings"
      tags: [ Collective ]
      summary: Get collective settings
      description: |
        Return the settings of a collective.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectiveSettings"
    post:
      operationId: "sec-collective-update-settings"
      tags: [ Collective ]
      summary: Update settings for a collective
      description: |
        Updates settings for a collective.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CollectiveSettings"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Collective"
  /sec/collective/insights:
    get:
      operationId: "sec-collective-get-insights"
      tags: [ Collective ]
      summary: Get some insights regarding your items.
      description: |
        Returns some information about how many items there are, how
        much folder they occupy etc.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ItemInsights"
  /sec/collective/tagcloud:
    get:
      operationId: "sec-collective-tag-cloud"
      tags: [ Collective ]
      summary: Summary of used tags.
      description: |
        Returns all tags and how often each has been applied.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagCloud"

  /sec/collective/contacts:
    get:
      operationId: "sec-collective-contacts-get-all"
      tags: [ Collective ]
      summary: Return a list of contacts.
      description: |
        Return a list of all contacts available from the collectives
        address book.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/q"
        - $ref: "#/components/parameters/contactKind"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactList"

  /sec/collective/classifier/startonce:
    post:
      operationId: "sec-collective-classifier-start-now"
      tags: [ Collective ]
      summary: Starts the learn-classifier task
      description: |
        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.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/collective/emptytrash/startonce:
    post:
      operationId: "sec-collective-emptytrash-start-now"
      tags: [ Collective ]
      summary: Starts the empty trash task
      description: |
        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.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EmptyTrashSetting"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/user:
    get:
      operationId: "sec-user-get-all"
      tags: [ Collective ]
      summary: Get a list of collective users.
      description: |
        Return a list of all users of the collective.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserList"
    post:
      operationId: "sec-user-new"
      tags: [ Collective ]
      summary: Create a new collective user.
      description: |
        Create a new collective user. If a user with this name already
        exists, an error is returned.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/User"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    put:
      operationId: "sec-user-edit"
      tags: [ Collective ]
      summary: Change an existing user.
      description: |
        Changes an existing user. The user is looked up by
        its id and all properties are changed as given.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/User"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/user/{username}:
    delete:
      operationId: "sec-user-delete-by-userid-or-login"
      tags: [ Collective ]
      summary: Delete a user by its id or login name.
      description: |
        Deletes a user.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/username"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/user/{username}/deleteData:
    get:
      operationId: "sec-user-delete-data"
      tags: [ Collective ]
      summary: Shows some data that would be deleted if the user is deleted
      description: |
        Gets some data that would be deleted, when the user with the
        given username is deleted. The `username` must be part of this
        collective.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/username"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteUserData"

  /sec/user/changePassword:
    post:
      operationId: "sec-user-change-password"
      tags: [ Collective ]
      summary: Change the password.
      description: |
        Allows users to change their password.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PasswordChange"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/user/otp/state:
    get:
      operationId: "sec-user-otp-state"
      tags: [ Collective ]
      summary: Gets the otp state for the current user.
      description: |
        Returns whether the current account as OTP enabled or not.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OtpState"
                  
  /sec/user/otp/init:
    post:
      operationId: "sec-user-otp-init"
      tags: [ Collective, Authentication ]
      summary: Initialize two factor auth via OTP
      description: |
        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.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OtpResult"
                
  /sec/user/otp/confirm:
    post:
      operationId: "sec-user-otp-confirm"
      tags: [ Collective, Authentication ]
      summary: Confirms two factor authentication
      description: |
        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.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OtpConfirm"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/user/otp/disable:
    post:
      operationId: "sec-user-otp-disable"
      tags: [ Collective, Authentication ]
      summary: Disables two factor authentication.
      description: |
        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.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OtpConfirm"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/notification/channel:
    get:
      operationId: "sec-notification-channel-get"
      tags: [ Notification ]
      summary: Return notification channels of the current user
      description: |
        Returns a list of notification channels for the current user.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/NotificationMail"
                  - $ref: "#/components/schemas/NotificationGotify"
                  - $ref: "#/components/schemas/NotificationMatrix"
                  - $ref: "#/components/schemas/NotificationHttp"                    
    post:
      operationId: "sec-notification-channel-post"
      tags: [ Notification ]
      summary: Create a new notification channel
      description: |
        Creates a new channel that can be used for notification.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/NotificationMail"
                  - $ref: "#/components/schemas/NotificationGotify"
                  - $ref: "#/components/schemas/NotificationMatrix"
                  - $ref: "#/components/schemas/NotificationHttp"                    
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    put:
      operationId: "sec-notification-channel-put"
      tags: [ Notification ]
      summary: Change a notification channel
      description: |
        Change details about a notification channel.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/NotificationMail"
                  - $ref: "#/components/schemas/NotificationGotify"
                  - $ref: "#/components/schemas/NotificationMatrix"
                  - $ref: "#/components/schemas/NotificationHttp"                    
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/notification/channel/{id}:
    delete:
      operationId: "sec-notification-channel-delete"
      tags: [ Notification ]
      summary: Delete a channel
      description: |
        Deletes the channel with the given id. This causes all hooks
        of this channel to be deleted as well.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/notification/hook:
    get:
      operationId: "sec-notification-hook-get"
      tags: [ Notification ]
      summary: Return list of all hooks
      description: |
        Returns a list of all defined hooks for the current user.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/NotificationHook"
    post:
      operationId: "sec-notification-hook-post"
      tags: [ Notification ]
      summary: Creates a new notification hook
      description: |
        Creates a new notification hook, that issues a request via the
        given channel description.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NotificationHook"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    put:
      operationId: "sec-notification-hook-put"
      tags: [ Notification ]
      summary: Updates a notification hook
      description: |
        Updates the hook details.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NotificationHook"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/notification/hook/{id}:
    delete:
      operationId: "sec-notification-hook-delete"
      tags: [ Notification ]
      summary: Delete a hook
      description: |
        Deletes the hook with the given id.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/notification/hook/sendTestEvent:
    post:
      operationId: "sec-notification-hook-sendtestevent-post"
      tags: [ Notification ]
      summary: Test a webhook
      description: |
        Tests the webhook specified in the body by applying it to a
        sample event.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NotificationHook"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationChannelTestResult"
  /sec/notification/hook/verifyJsonFilter:
    post:
      operationId: "sec-notification-hook-verifyjsonfilter-post"
      tags: [ Notification ]
      summary: Verify a json filter expression
      description: |
        Parses the given value into a JSON mini query. 
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StringValue"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"


  /sec/notification/event/sample:
    post:
      operationId: "sec-notification-sample-event-post"
      tags: [ Notification ]
      summary: Provide sample event data
      description: |
        Given an event type, generate some random sample of what would
        be send on such an event.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NotificationSampleEventReq"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema: {}

  /sec/querybookmark:
    get:
      operationId: "sec-querybookmark-get-all"
      tags: [Query Bookmarks]
      summary: Return all query bookmarks
      description: |
        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.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/BookmarkedQuery"
    post:
      operationId: "sec-querybookmark-post"
      tags: [Query Bookmarks]
      summary: Create a new query bookmark
      description: |
        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.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BookmarkedQuery"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    put:
      operationId: "sec-querybookmark-put"
      tags: [Query Bookmarks]
      summary: Change a query bookmark
      description: |
        Changes an existing  query bookmark.

        A bookmark must have a unique name within the collective
        (considering collective and personal scope). The bookmark is
        identified by its id, which must exist.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BookmarkedQuery"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/querybookmark/{bookmarkId}:
    parameters:
      - $ref: "#/components/parameters/bookmarkId"
    delete:
      operationId: "sec-querybookmark-delete"
      tags: [Query Bookmarks]
      summary: Delete a bookmark.
      description: |
        Deletes a bookmarks by its id.
      responses:
        422:
          description: BadRequest            
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/clientSettings/{clientId}:
    parameters:
      - $ref: "#/components/parameters/clientId"
    get:
      operationId: "sec-clientsettings-get"
      tags: [ Client Settings ]
      summary: Return the client settings of current user
      description: |
        Returns the settings for the current user by merging the
        client settings for the collective and the user's own client
        settings into one json structure.

        Null, Array, Boolean, String and Number are treated as values,
        and values from the users settings completely replace values
        from the collective's settings.
        
        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.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema: {}

  /sec/clientSettings/user/{clientId}:
    parameters:
      - $ref: "#/components/parameters/clientId"
    get:
      operationId: "sec-clientsettings-user-get"
      tags: [ Client Settings ]
      summary: Return the user's own client settings 
      description: |
        Returns the settings for the current user. 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.

        If there is nothing stored for the given `clientId` an empty
        JSON object (`{}`) is returned!
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema: {}
    put:
      operationId: "sec-clientsettings-user-update"
      tags: [ Client Settings ]
      summary: Update client settings of current user
      description: |
        Updates (replaces or creates) the current user's settings with
        the given data. The `clientId` is an identifier to a client
        application. The request body is expected to be JSON, the
        structure is not important to the server.

        The data is stored for the current user and given `clientId`.

        The data is only saved without being checked in any way
        (besides being valid JSON). It is returned "as is" to the
        client in the corresponding GET endpoint.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema: {}
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    delete:
      operationId: "sec-clientsettings-user-delete"
      tags: [ Client Settings ]
      summary: Clears client settings of current user
      description: |
        Removes all stored user settings for the client identified by
        `clientId`.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/clientSettings/collective/{clientId}:
    parameters:
      - $ref: "#/components/parameters/clientId"
    get:
      operationId: "sec-clientsettings-collective-get"
      tags: [ Client Settings ]
      summary: Return collective client settings
      description: |
        Returns the settings for the current collective. 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.

        If there is nothing stored for the given `clientId` an empty
        JSON object (`{}`) is returned!
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema: {}
    put:
      operationId: "sec-clientsettings-collective-update"
      tags: [ Client Settings ]
      summary: Update collective client settings
      description: |
        Updates (replaces or creates) the current collective's
        settings with the given data. The `clientId` is an identifier
        to a client application. The request body is expected to be
        JSON, the structure is not important to the server.

        The data is stored for the current user and given `clientId`.

        The data is only saved without being checked in any way
        (besides being valid JSON). It is returned "as is" to the
        client in the corresponding GET endpoint.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema: {}
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    delete:
      operationId: "sec-clientsettings-collective-delete"
      tags: [ Client Settings ]
      summary: Clears collective's client settings
      description: |
        Removes all stored client settings of id `clientId` for
        collective.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /share/search/query:
    post:
      operationId: "share-search-query"
      tags: [Share]
      summary: Performs a search in a share.
      description: |
        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.
      security:
        - shareTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemQuery"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ItemLightList"
  /share/search/stats:
    post:
      operationId: "share-search-stats"
      tags: [ Share ]
      summary: Get basic statistics about search results.
      description: |
        Instead of returning the results of a query, uses it to return
        a summary, constraint to the share.
      security:
        - shareTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemQuery"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchStats"
  /share/item/{id}:
    get:
      operationId: "share-item-get"
      tags: [ Share ]
      summary: Get details about an item.
      description: |
        Get detailed information about an item.
      security:
        - shareTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ItemDetail"      
  /share/attachment/{id}:
    head:
      operationId: "share-attach-head"
      tags: [ Share ]
      summary: Get headers to an attachment file.
      description: |
        Get information about the binary file belonging to the
        attachment with the given id.
      security:
        - shareTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          headers:
            Content-Type:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
                format: int64
            ETag:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
    get:
      operationId: "share-attach-get"
      tags: [ Share ]
      summary: Get an attachment file.
      description: |
        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.
      security:
        - shareTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /share/attachment/{id}/view:
    get:
      operationId: "share-attach-show-viewerjs"
      tags: [ Share ]
      summary: A javascript rendered view of the pdf attachment
      description: |
        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.
      security:
        - shareTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        303:
          description: See Other
        422:
          description: BadRequest
        200:
          description: Ok      
  /share/attachment/{id}/preview:
    head:
      operationId: "share-attach-check-preview"
      tags: [ Share ]
      summary: Get the headers to a preview image of an attachment file.
      description: |
        Checks if an image file showing a preview of the attachment is
        available. If not available, a 404 is returned.
      security:
        - shareTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        200:
          description: Ok
        404:
          description: NotFound
    get:
      operationId: "share-attach-get-preview"
      tags: [ Share ]
      summary: Get a preview image of an attachment file.
      description: |
        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.
      security:
        - shareTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
        - $ref: "#/components/parameters/withFallback"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /share/clientSettings/{clientId}:
    parameters:
      - $ref: "#/components/parameters/clientId"
    get:
      operationId: "share-clientsettings-get"
      tags: [ Share ]
      summary: Return the client settings of current user
      description: |
        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.
      security:
        - shareTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema: {}

  /share/downloadAll/prefetch:
    post:
      operationId: "share-downloadall-prefetch"
      tags: [Download, Share]
      summary: Return information about a potential zip download
      description: |
        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`.
      security:
        - shareTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DownloadAllRequest"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DownloadAllSummary"
  /share/downloadAll/submit:
    post:
      operationId: "share-downloadall-submit"
      tags: [Download, Share]
      summary: Submits a job to create a zip containing all files in the query
      description: |
        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`.        
      security:
        - shareTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DownloadAllRequest"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DownloadAllSummary"
  /share/downloadAll/file/{id}:
    get:
      operationId: "share-downloadall-get-file"
      tags: [Download, Share]
      summary: Download the zip file given the id
      description: |
        Download the zip file to the given id.
      parameters:
        - $ref: "#/components/parameters/id"
      security:
        - shareTokenHeader: []
      responses:
        422:
          description: BadRequest
        404:
          description: NotFound
        200:
          description: Ok
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary

  /admin/user/resetPassword:
    post:
      operationId: "admin-user-reset-password"
      tags: [ Collective, Admin ]
      summary: Reset a user password.
      description: |
        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`.
      security:
        - adminHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResetPassword"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResetPasswordResult"
  /admin/user/otp/resetOTP:
    post:
      operationId: "admin-user-reset-otp"
      tags: [ Collective, Admin ]
      summary: Disables OTP two factor auth for the given user.
      description: |
        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.
      security:
        - adminHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResetPassword"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /admin/attachments/generatePreviews:
    post:
      operationId: "admin-attachments-generate-previews"
      tags: [Attachment, Admin]
      summary: (Re)generate all preview images
      description: |
        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`.
      security:
        - adminHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /admin/attachments/convertallpdfs:
    post:
      operationId: "admin-attachments-convertallpdf"
      tags: [Attachment, Admin]
      summary: Convert all PDF files not yet converted
      description: |
        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.
      security:
        - adminHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /admin/files/cloneFileRepository:
    post:
      operationId: "admin-files-cloneFileRepository"
      tags: [Admin]
      summary: Copy all files into a new repository
      description: |
        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.
      security:
        - adminHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FileRepositoryCloneRequest"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /admin/files/integrityCheck:
    post:
      operationId: "admin-files-integrityCheck"
      tags: [ Admin ]
      summary: Verifies the stored checksum
      description: |
        Submits a task that goes through the files and compares the
        stored checksum (at the time of inserting) against a newly
        calculated one.
      security:
        - adminHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FileIntegrityCheckRequest"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/source:
    get:
      operationId: "sec-source-get-all"
      tags: [ Source ]
      summary: Get a list of sources
      description: |
        Return a list of all configured sources.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourceList"
    post:
      operationId: "sec-source-new"
      tags: [ Source ]
      summary: Create a new source.
      description: |
        Create a new source. If a source with this name already
        exists, an error is returned.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SourceTagIn"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    put:
      operationId: "sec-source-edit"
      tags: [ Source ]
      summary: Change an existing source.
      description: |
        Changes an existing source. The source is looked up by
        its id and all properties are changed as given.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SourceTagIn"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/source/{id}:
    delete:
      operationId: "sec-source-delete-by-id"
      tags: [ Source ]
      summary: Delete a source.
      description: |
        Deletes a source. This also removes this sources from
        all items.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/share:
    get:
      operationId: "sec-share-get-all"
      tags: [ Share ]
      summary: Get a list of shares
      description: |
        Return a list of all shares for this collective.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/q"
        - $ref: "#/components/parameters/owningShare"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ShareList"
    post:
      operationId: "sec-share-new"
      tags: [ Share ]
      summary: Create a new share.
      description: |
        Create a new share.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ShareData"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdResult"
  /sec/share/email/send/{name}:
    post:
      operationId: "sec-share-email-send"
      tags: [ Share, E-Mail ]
      summary: Send an email.
      description: |
        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.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/name"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SimpleShareMail"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/share/{shareId}:
    parameters:
      - $ref: "#/components/parameters/shareId"
    get:
      operationId: "sec-share-get"
      tags: [Share]
      summary: Get details to a single share.
      description: |
        Given the id of a share, returns some details about it.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ShareDetail"
    put:
      operationId: "sec-share-update"
      tags: [ Share ]
      summary: Update an existing share.
      description: |
        Updates an existing share.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ShareData"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    delete:
      operationId: "sec-share-delete-by-id"
      tags: [ Share ]
      summary: Delete a share.
      description: |
        Deletes a share
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/item/search:
    get:
      operationId: "sec-item-search-by-get"
      tags: [ Item Search ]
      summary: Search for items.
      description: |
        Search for items given a search query. The results are grouped
        by month and are sorted by item date (newest first). Tags and
        attachments are *not* resolved. The results will always
        contain an empty list for item tags and attachments. Set
        `withDetails` to `true` for retrieving all tags and a list of
        attachments of an item.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/q"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/withDetails"
        - $ref: "#/components/parameters/searchMode"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ItemLightList"
    post:
      operationId: "sec-item-search-by-post"
      tags: [ Item Search ]
      summary: Search for items.
      description: |
        Search for items given a search query. The results are grouped
        by month and are sorted by item date (newest first). Tags and
        attachments are *not* resolved. The results will always
        contain an empty list for item tags and attachments. Use
        `withDetails` to also retrieve all tags and a list of
        attachments of an item.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemQuery"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ItemLightList"

  /sec/item/searchStats:
    post:
      operationId: "sec-item-search-stats-get"
      tags: [ Item Search ]
      summary: Get basic statistics about search results.
      description: |
        Instead of returning the results of a query, uses it to return
        a summary.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemQuery"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchStats"
    get:
      operationId: "sec-item-search-stats-post"
      tags: [ Item Search ]
      summary: Get basic statistics about search results.
      description: |
        Instead of returning the results of a query, uses it to return
        a summary.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/q"
        - $ref: "#/components/parameters/searchMode"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchStats"

  /sec/item/{id}:
    get:
      operationId: "sec-item-details"
      tags: [ Item ]
      summary: Get details about an item.
      description: |
        Get detailed information about an item.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ItemDetail"
    delete:
      operationId: "sec-item-delete-by-id"
      tags: [ Item ]
      summary: Delete an item.
      description: |
        Delete an item and all its data. This is a "soft delete", the
        item is still in the database and can be undeleted. A periodic
        job will eventually remove this item from the database.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/restore:
    post:
      operationId: "sec-item-restore-by-id"
      tags: [ Item ]
      summary: Restore a deleted item.
      description: |
        A deleted item can be restored as long it is still in the
        database. This action sets the item state to `created`.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/item/{id}/tags:
    put:
      operationId: "sec-item-get-tags"
      tags: [ Item ]
      summary: Set new set of tags.
      description: |
        Update the tags associated to an item. This will remove all
        existing ones and sets the given tags, such that after this
        returns, the item has exactly the tags as given.

        Tags may be specified as names or ids.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StringList"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    post:
      operationId: "sec-item-create-and-add-tag"
      tags: [ Item ]
      summary: Add a new tag to an item.
      description: |
        Creates a new tag and associates it to the given item.

        The tag's `id` and `created` are generated and not used from
        the given data, so it can be left empty. Only `name` and
        `category` are used, where `category` is optional.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Tag"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/item/{id}/taglink:
    put:
      operationId: "sec-item-link-tags"
      tags: [Item]
      summary: Link existing tags to an item.
      description: |
        Sets all given tags to the item. The tags must exist,
        otherwise they are ignored. The tags may be specified as names
        or ids.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StringList"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/item/{id}/tagtoggle:
    post:
      operationId: "sec-item-toggle-tags"
      tags: [Item]
      summary: Toggles existing tags to an item.
      description: |
        Toggles all given tags of the item. The tags must exist,
        otherwise they are ignored. The tags may be specified as names
        or ids. Tags are either removed or linked from/to the item,
        depending on whether the item currently is tagged with the
        corresponding tag.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StringList"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/item/{id}/tagsremove:
    post:
      operationId: "sec-item-remove-tags"
      tags: [ Item ]
      summary: Remove tags from an item
      description: |
        Remove the given tags from the item. The tags can be specified
        via ids or names.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StringList"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/item/{id}/direction:
    put:
      operationId: "sec-item-set-direction"
      tags: [ Item ]
      summary: Set the direction of an item.
      description: |
        Update the direction of an item.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DirectionValue"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/folder:
    put:
      operationId: "sec-item-set-folder"
      tags: [ Item ]
      summary: Set a folder for this item.
      description: |
        Updates the folder property for this item to "place" the item
        into a folder. If the request contains an empty object or an
        `id` property of `null`, the item is moved into the "public"
        or "root" folder.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OptionalId"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/corrOrg:
    put:
      operationId: "sec-item-set-org"
      tags: [ Item ]
      summary: Set the correspondent organization of an item.
      description: |
        Update the correspondent organization of an item.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OptionalId"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    post:
      operationId: "sec-item-create-and-set-org"
      tags: [ Item ]
      summary: Set a new correspondent organization of an item.
      description: |
        Create a new organization and update the correspondent
        organization of an item.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Organization"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/corrPerson:
    put:
      operationId: "sec-item-set-corr-person"
      tags: [ Item ]
      summary: Set the correspondent person of an item.
      description: |
        Update the correspondent person of an item.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OptionalId"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    post:
      operationId: "sec-item-create-and-set-corr-person"
      tags: [ Item ]
      summary: Create and set the correspondent person of an item.
      description: |
        Creates a new person and updates the correspondent person of
        an item.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Person"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/concPerson:
    put:
      operationId: "sec-item-set-conc-person"
      tags: [ Item ]
      summary: Set the concerning person of an item.
      description: |
        Update the concerning person of an item.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OptionalId"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    post:
      operationId: "sec-item-create-and-set-conc-person"
      tags: [ Item ]
      summary: Create and set the concerning person of an item.
      description: |
        Creates a new person and updates the concerning person of an
        item.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Person"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/concEquipment:
    put:
      operationId: "sec-item-set-equip"
      tags: [ Item ]
      summary: Set the concering equipment of an item.
      description: |
        Update the concering equipment of an item.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OptionalId"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    post:
      operationId: "sec-item-create-and-set-equip"
      tags: [ Item ]
      summary: Create and set a new the concering equipment of an item.
      description: |
        Creates a new equipment and sets it as the concering equipment
        of an item.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Equipment"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/notes:
    put:
      operationId: "sec-item-set-notes"
      tags: [ Item ]
      summary: Set notes of an item.
      description: |
        Update the notes of an item.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OptionalText"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/name:
    put:
      operationId: "sec-item-set-name"
      tags: [ Item ]
      summary: Set the name of an item.
      description: |
        Update the name of an item.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OptionalText"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/confirm:
    post:
      operationId: "sec-item-confirm"
      tags: [ Item ]
      summary: Confirms the current meta data of an item.
      description: |
        An item is initially in state "created". The user can confirm
        the associated data to put it in state "confirmed".
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/unconfirm:
    post:
      operationId: "sec-item-unconfirm"
      tags: [ Item ]
      summary: Puts an item back to created state.
      description: |
        If an item is confirmed it can be set back to created to
        appear as new.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/date:
    put:
      operationId: "sec-item-set-date"
      tags: [ Item ]
      summary: Sets the item date.
      description: |
        Sets the date of an item.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OptionalDate"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/duedate:
    put:
      operationId: "sec-item-set-duedate"
      tags: [ Item ]
      summary: Sets the items due date.
      description: |
        Sets the due date of an item.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OptionalDate"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/proposals:
    get:
      operationId: "sec-item-get-proposals"
      tags: [ Item ]
      summary: Get a list of proposals for this item.
      description: |
        During text processing, a list of possible meta data has been
        extracted from each attachment that may be a match to this
        item. This is returned here, without duplicates.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ItemProposals"
  /sec/item/{id}/preview:
    head:
      operationId: "sec-item-check-preview"
      tags: [ Attachment ]
      summary: Get a preview image of an attachment file.
      description: |
        Checks if an image file showing a preview of the item is
        available. If not available, a 404 is returned. The preview is
        an image of the first page of the first attachment.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
        404:
          description: NotFound
    get:
      operationId: "sec-item-get-preview"
      tags: [ Attachment ]
      summary: Get a preview image of an attachment file.
      description: |
        Gets a image file showing a preview of the item. Usually it is
        a small image of the first page of the first attachment. 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.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
        - $ref: "#/components/parameters/withFallback"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary

  /sec/item/{id}/customfield:
    put:
      operationId: "sec-item-set-customfield-value"
      tags: [ Item ]
      summary: Set the value of a custom field.
      description: |
        Sets the value for a custom field to this item. If a value
        already exists, it is overwritten. A value must comply to the
        type of the associated field. It must not be the empty string.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomFieldValue"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{itemId}/customfield/{id}:
    delete:
      operationId: "sec-item-delete-customfield-value"
      tags: [ Item ]
      summary: Removes the value for a custom field
      description: |
        Removes the value for the given custom field. The `id` may be
        the id of a custom field or its name.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
        - $ref: "#/components/parameters/itemId"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"


  /sec/item/{itemId}/reprocess:
    post:
      operationId: "sec-item-start-reprocess"
      tags: [ Item ]
      summary: Start reprocessing the files of the item.
      description: |
        This submits a job that will re-process the files (either all
        or the ones specified) of the item and replace their metadata.

        If the item is not in "confirmed" state, its associated metada
        is also updated. Otherwise only the file metadata is updated
        (text analysis).
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/itemId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IdList"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"


  /sec/item/{itemId}/attachment/movebefore:
    post:
      operationId: "sec-item-attach-move-before"
      tags: [ Item ]
      summary: Reorder attachments within an item
      description: |
        Moves the `source` attachment before the `target` attachment,
        such that `source` becomes the immediate neighbor of `target`
        with a lower position.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/itemId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MoveAttachment"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/itemlink/{itemId}:
    get:
      operationId: "sec-itemlink-get"
      tags: [ Item ]
      summary: Get related items
      description: |
        Returns a list of related items for the given one.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/itemId"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ItemLightGroup"

  /sec/itemlink/{itemId}/{id}:
    delete:
      operationId: "sec-itemlink-delete"
      tags: [Item]
      summary: Delete an item from the list of related items
      description: |
        Deletes the item `id` from the list of related items on
        `itemId`.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/itemId"
        - $ref: "#/components/parameters/id"          
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/itemlink/addAll:
    post:
      operationId: "sec-itemlink-appendall-post"
      tags: [ Item ]
      summary: Add more items as related
      description: |
        Add one or more items to anothers list of related items.
        Duplicates are ignored.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemLinkData"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/itemlink/removeAll:
    post:
      operationId: "sec-itemlink-removeall-post"
      tags: [ Item ]
      summary: Remove items from the list of related items
      description: |
        Remove all given items from the list of related items
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemLinkData"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"


  /sec/items/merge:
    post:
      operationId: "sec-items-merge"
      tags:
        - Item (Multi Edit)
      summary: Merge multiple items into one.
      description: |
        A list of items is merged into one item by copying all
        metadata into the first item in the list.

        Metadata is copied into the target item, if there is no value
        present. So the order of items in the list matters - the first
        item with a correspondent or folder will win.

        For metadata that allow multiple values, like tags or custom
        fields the values are combined. Notes are concatenated from
        all items and custom fields with the same name are added
        together for money/numeric fields, concatenated for text
        fields or the first value is used for other field types.

        After a successful merge, the remaining items are deleted from
        the database (they cannot be restored).
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IdList"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/items/deleteAll:
    post:
      operationId: "sec-items-delete-all"
      tags:
        - Item (Multi Edit)
      summary: Delete multiple items.
      description: |
        Given a list of item ids, deletes all of them.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IdList"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/items/restoreAll:
    post:
      operationId: "sec-items-restore-all"
      tags:
        - Item (Multi Edit)
      summary: Restore multiple items.
      description: |
        Given a list of item ids, restores all of them.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IdList"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/items/tags:
    post:
      operationId: "sec-items-add-all-tags"
      tags:
        - Item (Multi Edit)
      summary: Add tags to multiple items
      description: |
        Add the given tags to all given items. The tags that are
        currently attached to the items are not changed. If there are
        new tags in the given list, then they are added. Otherwise,
        the item is left unchanged.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemsAndRefs"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    put:
      operationId: "sec-items-replace-all-tags"
      tags:
        - Item (Multi Edit)
      summary: Sets tags to multiple items
      description: |
        Sets the given tags to all given items. If the tag list is
        empty, then all tags are removed from the items.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemsAndRefs"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/items/tagsremove:
    post:
      operationId: "sec-items-remove-all-tags"
      tags:
        - Item (Multi Edit)
      summary: Remove tags from multiple items
      description: |
        Remove the given tags from all given items.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemsAndRefs"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"


  /sec/items/name:
    put:
      operationId: "sec-items-set-name-all"
      tags:
        - Item (Multi Edit)
      summary: Change the name of multiple items
      description: |
        Sets the name of multiple items at once. The name must not be
        empty.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemsAndName"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/items/folder:
    put:
      operationId: "sec-items-set-folder-all"
      tags:
        - Item (Multi Edit)
      summary: Sets a folder to multiple items.
      description: |
        Given a folder id, sets it on all given items. If the folder
        reference is not present, the folder is removed from all
        items.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemsAndRef"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/items/direction:
    put:
      operationId: "sec-items-set-direction-all"
      tags:
        - Item (Multi Edit)
      summary: Set the direction of multiple items
      description: |
        Given multiple item ids and a direction value, sets it to all
        items.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemsAndDirection"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/items/date:
    put:
      operationId: "sec-items-set-date-all"
      tags:
        - Item (Multi Edit)
      summary: Set the date of multiple items
      description: |
        Given multiple item ids and a date, sets it to all items as
        the item date. If no date is present, remove the date from the
        items.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemsAndDate"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/items/duedate:
    put:
      operationId: "sec-items-set-duedate-all"
      tags:
        - Item (Multi Edit)
      summary: Set the direction of multiple items
      description: |
        Given multiple item ids and a date value, sets it to all items
        as the due date. If the date is missing, remove the due-date
        from the items.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemsAndDate"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/items/corrOrg:
    put:
      operationId: "sec-items-set-corr-org-all"
      tags:
        - Item (Multi Edit)
      summary: Sets an organization to multiple items.
      description: |
        Given an organization id, sets it on all given items. If the
        organization is missing, the reference is removed from all
        items.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemsAndRef"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/items/corrPerson:
    put:
      operationId: "sec-items-set-corr-person-all"
      tags:
        - Item (Multi Edit)
      summary: Sets an correspondent person to multiple items.
      description: |
        Given an person id, sets it on all given items as
        correspondent person. If the person is missing, the reference
        is removed from all items.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemsAndRef"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/items/concPerson:
    put:
      operationId: "sec-items-set-conc-person-all"
      tags:
        - Item (Multi Edit)
      summary: Sets an concerning person to multiple items.
      description: |
        Given an person id, sets it on all given items as concerning
        person. If the person is missing, it is removed from all
        items.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemsAndRef"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/items/concEquipment:
    put:
      operationId: "sec-items-set-equip-all"
      tags:
        - Item (Multi Edit)
      summary: Sets an equipment to multiple items.
      description: |
        Given an equipment id, sets it on all given items. If no
        equipment is given, the reference is removed from all given
        items.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemsAndRef"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/items/confirm:
    put:
      operationId: "sec-items-confirm-all"
      tags:
        - Item (Multi Edit)
      summary: Confirm multiple items.
      description: |
        Given a list of item ids, confirm all of them.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IdList"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/items/unconfirm:
    put:
      operationId: "sec-items-unconfirm-all"
      tags:
        - Item (Multi Edit)
      summary: Un-confirm multiple items.
      description: |
        Given a list of item ids, un-confirm all of them.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IdList"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/items/reprocess:
    post:
      operationId: "sec-items-reprocess-all"
      tags:
        - Item (Multi Edit)
      summary: Submit multiple items to re-processing
      description: |
        Given a list of item-ids, submits all these items for
        reprocessing. All attachments of these items will be
        reprocessed. Item metadata may be changed if an item is not
        confirmed. Confirmed items are not changed.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IdList"

      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/items/customfield:
    put:
      operationId: "sec-items-set-customfield-all"
      tags: [ Item (Multi Edit) ]
      summary: Set the value of a custom field for multiple items
      description: |
        Sets the value for a custom field to multiple given items. If
        a value already exists, it is overwritten. The value must
        comply to the associated field type. It must not be the empty
        string.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemsAndFieldValue"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/items/customfieldremove:
    post:
      operationId: "sec-items-remove-customfield-all"
      tags: [ Item (Multi Edit) ]
      summary: Removes the value for a custom field on multiple items
      description: |
        Removes the value for the given custom field from multiple
        items. The field may be specified by its id or name.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemsAndName"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"


  /sec/attachment/{id}:
    delete:
      operationId: "sec-attach-delete-by-id"
      tags: [ Attachment ]
      summary: Delete an attachment.
      description: |
        Deletes a single attachment with all its related data like
        file, the original file, extracted text, results from analysis
        etc.

        If the attachment is part of an archive, the archive is only
        deleted, if it is the last entry left. Archives are otherwise
        not deleted, if there are remaining attachments available.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    head:
      operationId: "sec-attach-check"
      tags: [ Attachment ]
      summary: Get headers to an attachment file.
      description: |
        Get information about the binary file belonging to the
        attachment with the given id.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          headers:
            Content-Type:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
                format: int64
            ETag:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
    get:
      operationId: "sec-attach-get"
      tags: [ Attachment ]
      summary: Get an attachment file.
      description: |
        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.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /sec/attachment/{id}/original:
    head:
      operationId: "sec-attach-check-original"
      tags: [ Attachment ]
      summary: Get headers of the original file of an attachment.
      description: |
        Get information about the original binary file of the
        attachment with the given id.

        If the attachment is a converted PDF file, this route gets the
        original file as it was uploaded.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          headers:
            Content-Type:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
                format: int64
            ETag:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
    get:
      operationId: "sec-attach-get-original"
      tags: [ Attachment ]
      summary: Get the original file of an attachment.
      description: |
        Get the original binary file of the attachment with the given
        id.

        If the attachment is a converted PDF file, this route gets the
        original file as it was uploaded.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /sec/attachment/{id}/archive:
    head:
      operationId: "sec-attach-check-archive"
      tags: [ Attachment ]
      summary: Get headers of the archive file to an attachment.
      description: |
        Get information about the archive that contains the attachment
        with the given id.

        If the attachment was not uploaded as part of an archive, 404
        is returned.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          headers:
            Content-Type:
              schema:
                type: string
            Content-Length:
              schema:
                type: integer
                format: int64
            ETag:
              schema:
                type: string
            Content-Disposition:
              schema:
                type: string
    get:
      operationId: "sec-attach-get-archive"
      tags: [ Attachment ]
      summary: Get the archive file of an attachment.
      description: |
        Get the archive file that was originally uploaded that
        contains the attachment with the given id.

        If the attachment was not uploaded as part of an archive, a
        404 is returned.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /sec/attachment/{id}/preview:
    head:
      operationId: "sec-attach-check-preview"
      tags: [ Attachment ]
      summary: Get the headers to a preview image of an attachment file.
      description: |
        Checks if an image file showing a preview of the attachment is
        available. If not available, a 404 is returned.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
        404:
          description: NotFound
    get:
      operationId: "sec-attach-get-preview"
      tags: [ Attachment ]
      summary: Get a preview image of an attachment file.
      description: |
        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.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
        - $ref: "#/components/parameters/withFallback"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
    post:
      operationId: "sec-attach-regenerate-preview"
      tags: [ Attachment ]
      summary: (Re)generate a preview image.
      description: |
        Submits a task that generates a preview image for this
        attachment. The existing preview will be replaced.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/attachment/{id}/meta:
    get:
      operationId: "sec-attach-get-meta"
      tags: [ Attachment ]
      summary: Get the attachment's meta data.
      description: |
        Get meta data for this attachment. The meta data has been
        extracted from the contents.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttachmentMeta"
  /sec/attachment/{id}/view:
    get:
      operationId: "sec-attach-show-viewerjs"
      tags: [ Attachment ]
      summary: A javascript rendered view of the pdf attachment
      description: |
        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.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        303:
          description: See Other
        422:
          description: BadRequest
        200:
          description: Ok
  /sec/attachment/{id}/name:
    post:
      operationId: "sec-attach-set-name"
      tags: [ Attachment ]
      summary: Changes the name of an attachment
      description: |
        Change the name of the attachment with the given id. The
        attachment must be part of an item that belongs to the
        collective of the current user.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OptionalText"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/attachment/{id}/extracted-text:
    get:
      operationId: "sec-attachment-get-extracted-text"
      tags: [ Attachment ]
      summary: Get the extracted text of the given attachment.
      description: |
        Returns the extracted text of the attachment with the given
        id.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OptionalText"
    delete:
      operationId: "sec-attachment-delete-extracted-text"
      summary: Removes extracted text for the given attachment.
      description: |
        Removes any extracted text for the given attachment.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"    
    post:
      operationId: "sec-attachment-post-extracted-text"
      tags: [ Attachment ]
      summary: Changes the extracted text for an attachment
      description: |
        Changes the extracted text of the attachment with the given
        id. The attachment must be part of an item that belongs to the
        collective of the current user. This can be used to correct
        poor ocr-ed files.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OptionalText"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/attachments/delete:
    post:
      operationId: "sec-attachs-delete-all"
      tags:
        - Attachment (Multi Edit)
      summary: Delete multiple attachments.
      description: |
        Given a list of attachment ids, deletes all of them.
      security:
        - authTokenHeader: [ ]
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IdList"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/queue/state:
    get:
      operationId: "sec-jobs-get-state"
      tags: [ Job Queue ]
      summary: Get complete state of job queue.
      description: |
        Get the current state of the job qeue. The job qeue contains
        all processing tasks and other long-running operations. All
        users/collectives share processing resources.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobQueueState"
  /sec/queue/{id}/cancel:
    post:
      operationId: "sec-jobs-cancel-job"
      tags: [ Job Queue ]
      summary: Cancel a job.
      description: |
        Tries to cancel a job and remove it from the queue. If the job
        is running, a cancel request is send to the corresponding joex
        instance. Otherwise the job is removed from the queue.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/queue/{id}/priority:
    post:
      operationId: "sec-jobs-set-prio"
      tags: [ Job Queue ]
      summary: Change the priority of a waiting job.
      description: |
        A waiting job can change its priority. If the job is not in
        state waiting, this operation fails.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JobPriority"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/email/settings/smtp:
    get:
      operationId: "sec-email-settings-smtp-all"
      tags: [ E-Mail ]
      summary: List email settings for current user.
      description: |
        List all available e-mail settings for the current user.
        E-Mail settings specify smtp connections that can be used to
        sent e-mails.

        Multiple e-mail settings can be specified, they are
        distinguished by their `name`. The query `q` parameter does a
        simple substring search in the connection name.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/q"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailSettingsList"
    post:
      operationId: "sec-email-new-smtp-settings"
      tags: [ E-Mail ]
      summary: Create new email settings
      description: |
        Create new e-mail settings.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EmailSettings"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/email/settings/smtp/{name}:
    parameters:
      - $ref: "#/components/parameters/name"
    get:
      operationId: "sec-email-get-smtp-details"
      tags: [ E-Mail ]
      summary: Return specific email settings by name.
      description: |
        Return the stored e-mail settings for the given connection
        name.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailSettings"
    put:
      operationId: "sec-email-set-smtp-settings"
      tags: [ E-Mail ]
      summary: Change specific email settings.
      description: |
        Changes all settings for the connection with the given `name`.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EmailSettings"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    delete:
      operationId: "sec-email-delete-smtp-settings"
      tags: [ E-Mail ]
      summary: Delete e-mail settings.
      description: |
        Deletes the e-mail settings with the specified `name`.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/email/settings/imap:
    get:
      operationId: "sec-email-imap-settings-all"
      tags: [ E-Mail ]
      summary: List email settings for current user.
      description: |
        List all available e-mail settings for the current user.
        E-Mail settings specify imap connections that can be used to
        retrieve e-mails.

        Multiple e-mail settings can be specified, they are
        distinguished by their `name`. The query `q` parameter does a
        simple substring search in the connection name.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/q"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImapSettingsList"
    post:
      operationId: "sec-email-new-imap-settings"
      tags: [ E-Mail ]
      summary: Create new email settings
      description: |
        Create new e-mail settings.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ImapSettings"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/email/settings/imap/{name}:
    parameters:
      - $ref: "#/components/parameters/name"
    get:
      operationId: "sec-email-get-imap-details"
      tags: [ E-Mail ]
      summary: Return specific email settings by name.
      description: |
        Return the stored e-mail settings for the given connection
        name.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImapSettings"
    put:
      operationId: "sec-email-set-imap-settings"
      tags: [ E-Mail ]
      summary: Change specific email settings.
      description: |
        Changes all settings for the connection with the given `name`.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ImapSettings"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    delete:
      operationId: "sec-email-delete-imap-settings"
      tags: [ E-Mail ]
      summary: Delete e-mail settings.
      description: |
        Deletes the e-mail settings with the specified `name`.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/email/send/{name}/{id}:
    post:
      operationId: "sec-email-send-with-item"
      tags: [ E-Mail ]
      summary: Send an email.
      description: |
        Sends an email as specified in the body of the request.

        The item's attachment are added to the mail if requested.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/name"
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SimpleMail"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/email/sent/item/{id}:
    get:
      operationId: "sec-email-get-sent-mails-to-item"
      tags: [ E-Mail ]
      summary: Get sent mail related to an item
      description: |
        Return all mails that have been sent related to the item with
        id `id`.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SentMails"
  /sec/email/sent/mail/{mailId}:
    parameters:
      - $ref: "#/components/parameters/mailId"
    get:
      operationId: "sec-email-get-sent-mail"
      tags: [ E-Mail ]
      summary: Get sent single mail related to an item
      description: |
        Return one mail with the given id.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SentMail"
    delete:
      operationId: "sec-email-delete-sent-mail"
      tags: [ E-Mail ]
      summary: Delete a sent mail.
      description: |
        Delete a sent mail.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/calevent/check:
    post:
      operationId: "sec-calevent-check"
      tags: [ Utility ]
      summary: Check a calendar event string
      description: |
        For ui purposes, this route checks a calendar event string and
        either returns the normal form or an error message.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CalEventCheck"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CalEventCheckResult"

  /sec/usertask/notifydueitems:
    get:
      operationId: "sec-usertask-notify-all"
      tags: [ User Tasks ]
      summary: Get settings for "Notify Due Items" task
      description: |
        Return all current notification settings of the authenticated
        user. Users can be notified on due items via e-mail. This is
        done by periodically querying items. It is possible to have
        multiple tasks.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/PeriodicDueItemsSettings"
    post:
      operationId: "sec-usertask-notify-new"
      tags: [ User Tasks ]
      summary: Create settings for "Notify Due Items" task
      description: |
        Create a new notification settings task of the authenticated
        user. The id field in the input is ignored.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PeriodicDueItemsSettings"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    put:
      operationId: "sec-usertask-notify-edit"
      tags: [ User Tasks ]
      summary: Change settings for "Notify Due Items" task
      description: |
        Change the settings for a notify-due-items task. The task is
        looked up by its id.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PeriodicDueItemsSettings"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/usertask/notifydueitems/{id}:
    parameters:
      - $ref: "#/components/parameters/id"
    get:
      operationId: "sec-usertask-notify-get-details"
      tags: [ User Tasks ]
      summary: Get notify items settings for a specific task
      description: |
        Return the current settings for a single notify-due-items task
        of the authenticated user.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PeriodicDueItemsSettings"
    delete:
      operationId: "sec-usertask-notify-delete"
      tags: [ User Tasks ]
      summary: Delete a specific notify due items task
      description: |
        Delete the settings to a notify-due-items task of the
        authenticated user.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/usertask/notifydueitems/startonce:
    post:
      operationId: "sec-usertask-notify-start-now"
      tags: [ User Tasks ]
      summary: Start the "Notify Due Items" task once
      description: |
        Starts the notify-due-items task just once, discarding the
        schedule and not updating the periodic task.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PeriodicDueItemsSettings"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/usertask/periodicquery:
    get:
      operationId: "sec-usertask-periodic-query-all"
      tags: [ User Tasks ]
      summary: Get settings for PeriodicQuery task
      description: |
        Return all current settings of the authenticated user. 
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/PeriodicQuerySettings"
    post:
      operationId: "sec-usertask-periodic-query-new"
      tags: [ User Tasks ]
      summary: Create settings for PeriodicQuery task
      description: |
        Create a new periodic-query task of the authenticated user.
        The id field in the input is ignored.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PeriodicQuerySettings"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    put:
      operationId: "sec-usertask-periodic-query-edit"
      tags: [ User Tasks ]
      summary: Change settings for PeriodicQuery task
      description: |
        Change the settings for a periodic-query task. The task is
        looked up by its id.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PeriodicQuerySettings"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/usertask/periodicquery/{id}:
    parameters:
      - $ref: "#/components/parameters/id"
    get:
      operationId: "sec-usertask-periodic-query-get-details"
      tags: [ User Tasks ]
      summary: Get periodic query for a specific task
      description: |
        Return the current settings for a single periodic-query task
        of the authenticated user.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PeriodicQuerySettings"
    delete:
      operationId: "sec-usertask-periodic-query-delete"
      tags: [ User Tasks ]
      summary: Delete a specific periodic-query task
      description: |
        Delete the settings to a periodic-query task of the
        authenticated user.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/usertask/periodicquery/startonce:
    post:
      operationId: "sec-usertask-periodic-query-start-now"
      tags: [ User Tasks ]
      summary: Start the PeriodicQuery task once
      description: |
        Starts the periodic-query task just once, discarding the
        schedule and not updating the periodic task.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PeriodicQuerySettings"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/usertask/scanmailbox:
    get:
      operationId: "sec-usertask-scanmailbox-get-all"
      tags: [ User Tasks ]
      summary: Get settings for "Scan Mailbox" task
      description: |
        Return the current settings for the scan-mailbox tasks of the
        authenticated user. Users can periodically fetch mails to be
        imported into docspell. It is possible to have multiple of
        these tasks.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScanMailboxSettingsList"
    post:
      operationId: "sec-usertask-scanmailbox-new"
      tags: [ User Tasks ]
      summary: Create settings for "Scan Mailbox" task
      description: |
        Create new settings for a scan-mailbox task. The id field in
        the input data is ignored.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ScanMailboxSettings"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    put:
      operationId: "sec-usertask-scanmailbox-edit"
      tags: [ User Tasks ]
      summary: Change settings for a "Scan Mailbox" task
      description: |
        Change the settings for a scan-mailbox task. The task is
        looked up by its id.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ScanMailboxSettings"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/usertask/scanmailbox/{id}:
    parameters:
      - $ref: "#/components/parameters/id"
    get:
      operationId: "sec-usertask-scanmailbox-get-details"
      tags: [ User Tasks ]
      summary: Get settings for "Scan Mailbox" task
      description: |
        Return the current settings for a single scan-mailbox task of
        the authenticated user. Users can periodically fetch mails to
        be imported into docspell.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScanMailboxSettings"
    delete:
      operationId: "sec-usertask-scanmailbox-delete"
      tags: [ User Tasks ]
      summary: Delete a scan-mailbox task.
      description: |
        Deletes the settings to a scan-mailbox task of the
        authenticated user.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/usertask/scanmailbox/startonce:
    post:
      operationId: "sec-usertask-scanmailbox-start-now"
      tags: [ User Tasks ]
      summary: Start the "Scan Mailbox" task once
      description: |
        Starts the scan-mailbox task just once, discarding the
        schedule and not updating the periodic task.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ScanMailboxSettings"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/customfield:
    get:
      operationId: "sec-customfield-get-all"
      tags: [ Custom Fields ]
      summary: Get all defined custom fields.
      description: |
        Get all custom fields defined for the current collective. The
        `sort` parameter can be used to control the order of the
        returned list. It can take a value from: `name`, `-name`,
        `label`, `-label`, `type`, `-type`.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/q"
        - $ref: "#/components/parameters/sort"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomFieldList"
    post:
      operationId: "sec-customfield-new"
      tags: [ Custom Fields ]
      summary: Create a new custom field
      description: |
        Creates a new custom field.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewCustomField"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/customfield/{id}:
    parameters:
      - $ref: "#/components/parameters/id"
    get:
      operationId: "sec-customfield-get-details"
      tags: [ Custom Fields ]
      summary: Get details about a custom field.
      description: |
        Returns the details about a custom field.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomField"
    put:
      operationId: "sec-customfield-edit"
      tags: [ Custom Fields ]
      summary: Change a custom field
      description: |
        Change properties of a custom field.

        Changing the label has no further impliciations, since it is
        only used for displaying. The name and type on the other hand
        have consequences: name must be unique and the type determines
        how the value is stored internally.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewCustomField"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    delete:
      operationId: "sec-customfield-delete"
      tags: [ Custom Fields ]
      summary: Deletes a custom field.
      description: |
        Deletes the custom field and all its relations.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/addon/archive:
    get:
      operationId: "sec-addon-archive-get"
      tags: [Addons]
      summary: Get all registered addons
      description: |
        Returns a list of all registered addons.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddonList"
    post:
      operationId: "sec-addon-post"
      tags: [ Addons ]
      summary: Install a new addon
      description: |
        Given an URL to an addon (which is a zip file containing a
        `docspell-meta.yaml` or json descriptor), the addon is
        downloaded and installed in docspell.

        By default this happens asynchronously and the response only
        indicates that installing has been submitted. The result will
        be transfered over the websocket channel. With query parameter
        `sync` installing happens synchronously and it may take a
        while to complete (if successful, the addon id is returned).
      security:
        - authTokenHeader: []
      parameters:
        - in: query
          name: sync
          required: false
          allowEmptyValue: true
          schema:
            type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddonRegister"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdResult"
  /sec/addon/archive/{id}:
    parameters:
      - $ref: "#/components/parameters/id"
    delete:
      operationId: "sec-addon-archive-delete"
      tags: [Addons]
      summary: Deletes the addon and removes it from all addon run configs
      description: |
        Deletes the addon from the database and also removes it from
        all run configurations where it might be referenced.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    put:
      operationId: "sec-addon-archive-put"
      tags: [ Addons ]
      summary: Update an addon from its url
      description: |
        Addons are urls to zip files. This call reads the url again
        and updates the contents in docspell for this addon.

        By default this happens asynchronously and the response only
        indicates that updating has been submitted. The result will be
        transfered over the websocket channel. With query parameter
        `sync` updating happens synchronously and it may take a while
        to complete.
      security:
        - authTokenHeader: []
      parameters:
        - in: query
          name: sync
          required: false
          allowEmptyValue: true
          schema:
            type: boolean
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/addon/run-config:
    get:
      operationId: "sec-addon-run-config-get"
      tags: [Addons]
      summary: Get all addon run configs
      description: |
        Returns a list of addon run configs.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddonRunConfigList"
    post:
      operationId: "sec-addon-run-config-post"
      tags: [ Addons ]
      summary: Adds a new addon run config
      description: |
        Adds a new set of configured addons, creating a run
        configuration.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddonRunConfig"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdResult"

  /sec/addon/run-config/{id}:
    parameters:
      - $ref: "#/components/parameters/id"
    put:
      operationId: "sec-addon-run-config-id-put"
      tags: [ Addons ]
      summary: Updates an addon run config
      description: |
        Updates an existing addon run configuration. The id is taken
        from the URL and any given id in the request body is ignored.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddonRunConfig"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    delete:
      operationId: "sec-addonrunconfig-delete"
      tags: [Addons]
      summary: Deletes the addon run config given its id
      description: |
        Deletes the addon run configuration.
      security:
        - authTokenHeader: []
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/addon/run/existingitem:
    post:
      operationId: "sec-addon-run-existing-item"
      tags: [Addons]
      summary: Submits a task running addons for an item
      description: |
        Submits a background task that executes the specified (or all)
        addons configured to use for an existing item.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddonRunExistingItem"
      responses:
        422:
          description: BadRequest
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

components:
  schemas:
    AddonRunExistingItem:
      description: |
        Data to run addons for an existing item.
      required:
        - itemId
      properties:
        itemId:
          type: string
          format: ident
        additionalItems:
          type: array
          items:
            type: string
            format: ident
          description: |
            Additional items to run addons on. There will be one job
            submitted per item.
        addonRunConfigIds:
          type: array
          items:
            type: string
            format: ident
          description: |
            If non empty, only select these addon run configs.
            Otherwise all configured to be run for existing items are
            executed.

    AddonRef:
      description: |
        A reference to an addon (archive) with additional name and
        version and its arguments. When used for adding addon run
        configs, name and version are ignored.
      required:
        - addonId
        - name
        - version
        - args
      properties:
        addonId:
          type: string
          format: ident
        name:
          type: string
        version:
          type: string
        description:
          type: string
        args:
          type: string

    AddonRunConfig:
      description: |
        A set of configured addons that are run on certain points
        defined by the `trigger` property.
      required:
        - id
        - name
        - enabled
        - trigger
        - addons
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        enabled:
          type: boolean
        userId:
          type: string
          format: ident
          description: |
            An addon can be run on behalf of a user. If not given, no
            authentication token is generated into the environment of
            the addon. The user can be given as user_id or by its
            login name.
        schedule:
          type: string
          format: calevent
          description: |
            A schedule must be supplied when a trigger type of
            'scheduled' is defined.
        trigger:
          description: |
            Defines when this task is executed. There must be at least
            one element. Possible values:
              
              * process-item: After an item has been processed
              * reprocess-item: After an item has been re-processed
              * scheduled: Executed periodically based on a schedule,
                which must be defined then
          type: array
          items:
            type: string
            format: addon-trigger-type
            enum:
              - process-item
              - reprocess-item
              - scheduled
        addons:
          type: array
          items:
            $ref: "#/components/schemas/AddonRef"

    AddonRunConfigList:
      description: |
        A list of addon run configurations.
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/AddonRunConfig"
          
    AddonRegister:
      description: |
        Data to register addons
      required:
        - url
      properties:
        url:
          type: string
          format: uri

    Addon:
      description: |
        An registered addon.
      required:
        - id
        - name
        - version
        - created
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        version:
          type: string
        description:
          type: string
        url:
          type: string
          format: uri
        created:
          type: integer
          format: date-time

    AddonList:
      description: |
        A list of addons
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Addon"       

    DownloadAllSummary:
      description: |
        Information about a ZIP download.
      required:
        - id
        - fileCount
        - uncompressedSize
        - state
      properties:
        id:
          type: string
          format: ident
          description: Unique identifier for the download request
        fileCount:
          type: integer
          format: int32
          description: How many files are included
        uncompressedSize:
          type: integer
          format: bytesize
          description: The sum of sizes of all included files
        state:
          type: string
          format: downloadstate
          enum:
            - forbidden
            - notpresent
            - preparing
            - present
            - empty
          description: |
            A state for the download, it may not exist yet or be
            forbidden because it exceeds configured thresholds. Then a
            job may be running to create it or the file is present and
            ready to download.

    DownloadAllRequest:
      description: |
        A request to download all files included in a query.
      required:
        - query
        - fileType
      properties:
        query:
          type: string
          format: itemquery
        fileType:
          type: string
          format: downloadalltype
          enum:
            - converted
            - original
      
    ItemLinkData:
      description: |
        Data for changing the list of related items.
      required:
        - item
        - related
      properties:
        item:
          type: string
          format: ident
        related:
          type: array
          items:
            type: string
            format: ident

    FileIntegrityCheckRequest:
      description: |
        Data for running a file integrity check
      properties:
        collective:
          type: string
          format: ident
          
    FileRepositoryCloneRequest:
      description: |
        Clone the file repository to a new location.
      required:
        - targetRepositories
      properties:
        targetRepositories:
          type: array
          items:
            type: string
            format: ident

    BookmarkedQuery:
      description: |
        A query bookmark.
      required:
        - id
        - name
        - query
        - personal
        - created
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        label:
          type: string
        query:
          type: string
          format: itemquery
        personal:
          type: boolean
        created:
          type: integer
          format: date-time

    StringValue:
      description: |
        A generic string value
      required:
        - value
      properties:
        value:
          type: string

    NotificationSampleEventReq:
      description: |
        An event type.
      required:
        - eventType
      properties:
        eventType:
          type: string
          format: eventtype
    NotificationChannelTestResult:
      description: |
        Results from running a sample event.
      required:
        - success
        - messages
      properties:
        success:
          type: boolean
        messages:
          type: array
          items:
            type: string
    NotificationChannelRef:
      description: |
        A reference to a channel. The `id` and `channelType` are
        required to identify a channel. The `name` attribute is as a
        descriptive name and is returned by the server if it is
        specified for the corresponding channel.
      required:
        - id
        - channelType
      properties:
        id:
          type: string
          format: ident
        channelType:
          type: string
          format: channeltype
        name:
          type: string
    NotificationMatrix:
      description: |
        A notification channel for matrix.
      required:
        - id
        - channelType
        - homeServer
        - roomId
        - accessToken
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        channelType:
          type: string
          format: channeltype
        homeServer:
          type: string
          format: uri
        roomId:
          type: string
        accessToken:
          type: string
          format: password
    NotificationGotify:
      description: |
        A notification channel for gotify.
      required:
        - id
        - channelType
        - url
        - appKey
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        channelType:
          type: string
          format: channeltype
        url:
          type: string
          format: uri
        appKey:
          type: string
          format: password
        priority:
          type: integer
          format: int32
          description: |
            A priority number [0-10]
    NotificationHttp:
      description: |
        A notification channel for receiving a generic http request.
      required:
        - id
        - channelType
        - url
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        channelType:
          type: string
          format: channeltype
        url:
          type: string
          format: uri
    NotificationMail:
      description: |
        A notification channel for receiving e-mails.
      required:
        - id
        - channelType
        - connection
        - recipients
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        channelType:
          type: string
          format: channeltype
        connection:
          type: string
          format: ident
        recipients:
          type: array
          items:
            type: string

    NotificationHook:
      description: |
        Describes a notifcation hook. There must be at least one
        channel specified. When creating hooks, the channels must
        provide the `ìd` and the `channelType` while their `name`
        attribute is optional.
      required:
        - id
        - enabled
        - channel
        - events
        - allEvents
      properties:
        id:
          type: string
          format: ident
        enabled:
          type: boolean
        channels:
          type: array
          items:
            $ref: "#/components/schemas/NotificationChannelRef"
        allEvents:
          type: boolean
        eventFilter:
          type: string
          format: jsonminiq
          description: |
            A filter expression that is applied to the event to be able
            to ignore a subset of them. See its
            [documentation](https://docspell.org/docs/jsonminiquery/).
        events:
          type: array
          items:
            type: string
            format: eventtype
            enum:
              - tagsAdded
              - tagsSet
  
    PeriodicQuerySettings:
      description: |
        Settings for the periodc-query task. At least one of `query`
        and `bookmark` is required! There must be at least one channel
        specified when creating settings. A channel must provide its
        `id` and `channelType`, while its `name` is optional.
      required:
        - id
        - enabled
        - channel
        - schedule
      properties:
        id:
          type: string
          format: ident
        enabled:
          type: boolean
        summary:
          type: string
        channels:
          type: array
          items:
            $ref: "#/components/schemas/NotificationChannelRef"
        schedule:
          type: string
          format: calevent
        query:
          type: string
          format: itemquery
        bookmark:
          type: string
          description: |
            Name or ID of bookmark to use.
        contentStart:
          type: string
  
    PeriodicDueItemsSettings:
      description: |
        Settings for notifying about due items. At least one of
        `query` and `bookmark` is required! There must be at least one
        channel specified when creating settings. A channel must
        provide its `id` and `channelType`, while its `name` is
        optional.
      required:
        - id
        - enabled
        - channel
        - schedule
        - remindDays
        - capOverdue
        - tagsInclude
        - tagsExclude
      properties:
        id:
          type: string
          format: ident
        enabled:
          type: boolean
        summary:
          type: string
        channels:
          type: array
          items:
            $ref: "#/components/schemas/NotificationChannelRef"
        schedule:
          type: string
          format: calevent
        remindDays:
          type: integer
          format: int32
          description: |
            Used to restrict items by their due dates. All items with
            a due date lower than (now + remindDays) are searched.
        capOverdue:
          type: boolean
          description: |
            If this is true, the search is also restricted to due
            dates greater than `now - remindDays'. Otherwise, due date
            are not restricted in that direction (only lower than `now
            + remindDays' applies) and it is expected to restrict it
            more using custom tags.
        tagsInclude:
          type: array
          items:
            $ref: "#/components/schemas/Tag"
        tagsExclude:
          type: array
          items:
            $ref: "#/components/schemas/Tag"
  
    ShareSecret:
      description: |
        The secret (the share id + optional password) to access a
        share.
      required:
        - shareId
      properties:
        shareId:
          type: string
          format: ident
        password:
          type: string
          format: password

    ShareVerifyResult:
      description: |
        The data returned when verifying a `ShareSecret`.
      required:
        - success
        - token
        - passwordRequired
        - message
      properties:
        success:
          type: boolean
        token:
          type: string
        passwordRequired:
          type: boolean
        message:
          type: string
        name:
          type: string
          description: |
            The name of the share if it exists. Only valid to use when
            `success` is `true`.

    ShareData:
      description: |
        Editable data for a share.
      required:
        - query
        - enabled
        - publishUntil
      properties:
        name:
          type: string
        query:
          type: string
          format: itemquery
        enabled:
          type: boolean
        password:
          type: string
          format: password
        publishUntil:
          type: integer
          format: date-time
        removePassword:
          type: boolean
          description: |
            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.

    ShareDetail:
      description: |
        Details for an existing share.
      required:
        - id
        - query
        - owner
        - enabled
        - publishAt
        - publishUntil
        - password
        - views
        - expired
      properties:
        id:
          type: string
          format: ident
        query:
          type: string
          format: itemquery
        owner:
          $ref: "#/components/schemas/IdName"          
        name:
          type: string
        enabled:
          type: boolean
        publishAt:
          type: integer
          format: date-time
        publishUntil:
          type: integer
          format: date-time
        expired:
          type: boolean
        password:
          type: boolean
        views:
          type: integer
          format: int32
        lastAccess:
          type: integer
          format: date-time

    ShareList:
      description: |
        A list of shares.
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/ShareDetail"
        
    DeleteUserData:
      description: |
        An excerpt of data that would be deleted when deleting the
        associated user.
      required:
        - folders
        - sentMails
        - shares
      properties:
        folders:
          type: array
          items:
            type: string
            format: ident
        sentMails:
          type: integer
          format: int32
        shares:
          type: integer
          format: int32

    SecondFactor:
      description: |
        Provide a second factor for login.
      required:
        - token
        - otp
        - rememberMe
      properties:
        token:
          type: string
        otp:
          type: string
          format: password
        rememberMe:
          type: boolean          
    OtpState:
      description: |
        The state for OTP for an account
      required:
        - enabled
      properties:
        enabled:
          type: boolean
        created:
          type: integer
          format: date-time        
    OtpResult:
      description: |
        The result from initializing OTP. It contains the shared
        secret.
      required:
        - authenticatorUrl
        - secret
        - authType
        - issuer
      properties:
        authenticatorUrl:
          type: string
          format: uri
        secret:
          type: string
        authType:
          type: string
          enum:
            - totp
        issuer:
          type: string

    OtpConfirm:
      description: |
        Transports a one time password.
      required:
        - otp
      properties:
        otp:
          type: string
          format: password          

    ResetPassword:
      description: |
        The account to reset the password.
      required:
        - account
      properties:
        account:
          type: string
          format: accountid

    ResetPasswordResult:
      description: |
        Contains the newly generated password or an error.
      required:
        - success
        - newPassword
        - message
      properties:
        success:
          type: boolean
        newPassword:
          type: string
          format: password
        message:
          type: string

    ItemsAndFieldValue:
      description: |
        Holds a list of item ids and a custom field value.
      required:
        - items
        - field
      properties:
        items:
          type: array
          items:
            type: string
            format: ident
        field:
          $ref: "#/components/schemas/CustomFieldValue"

    ItemsAndRefs:
      description: |
        Holds a list of item ids and a list of names or ids of some
        other related entity (e.g. tags).
      required:
        - items
        - refs
      properties:
        items:
          type: array
          items:
            type: string
            format: ident
        refs:
          type: array
          items:
            type: string
    ItemsAndRef:
      description: |
        Holds a list of item ids and a single optional id of some
        other related entity (e.g. person, org).
      required:
        - items
      properties:
        items:
          type: array
          items:
            type: string
            format: ident
        ref:
          type: string
          format: ident
    ItemsAndName:
      description: |
        Holds a list of item ids and an item name.
      required:
        - items
        - name
      properties:
        items:
          type: array
          items:
            type: string
            format: ident
        name:
          type: string
    ItemsAndDirection:
      description: |
        Holds a list of item ids and a direction value.
      required:
        - items
        - direction
      properties:
        items:
          type: array
          items:
            type: string
            format: ident
        direction:
          type: string
          format: direction
    ItemsAndDate:
      description: |
        Holds a list of item ids and a date value.
      required:
        - items
      properties:
        items:
          type: array
          items:
            type: string
            format: ident
        date:
          type: integer
          format: date-time


    CustomFieldList:
      description: |
        A list of known custom fields.
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/CustomField"

    ItemFieldValue:
      description: |
        Information about a custom field on an item.
      required:
        - id
        - name
        - ftype
        - value
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
          format: ident
        label:
          type: string
        ftype:
          type: string
          format: customfieldtype
          enum:
            - text
            - numeric
            - date
            - bool
            - money
        value:
          type: string

    CustomFieldValue:
      description: |
        Data structure to update the value of a custom field.
      required:
        - field
        - value
      properties:
        field:
          type: string
          format: ident
        value:
          type: string

    NewCustomField:
      description: |
        Data for creating a custom field.
      required:
        - name
        - ftype
      properties:
        name:
          type: string
          format: ident
        label:
          type: string
        ftype:
          type: string
          format: customfieldtype
          enum:
            - text
            - numeric
            - date
            - bool
            - money

    CustomField:
      description: |
        A custom field definition.
      required:
        - id
        - name
        - ftype
        - usages
        - created
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
          format: ident
        label:
          type: string
        ftype:
          type: string
          format: customfieldtype
          enum:
            - text
            - numeric
            - date
            - bool
            - money
        usages:
          type: integer
          format: int32
        created:
          type: integer
          format: date-time

    JobPriority:
      description: |
        Transfer the priority of a job.
      required:
        - priority
      properties:
        priority:
          type: string
          format: priority
          enum:
            - high
            - low
    IdList:
      description:
        A list of identifiers.
      required:
        - ids
      properties:
        ids:
          type: array
          items:
            type: string
            format: ident
    StringList:
      description: |
        A simple list of strings.
      required:
        - items
      properties:
        items:
          type: array
          items:
            type: string
    FolderList:
      description: |
        A list of folders with their member counts.
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/FolderItem"
    FolderItem:
      description: |
        An item in a folder list.
      required:
        - id
        - name
        - owner
        - created
        - isMember
        - memberCount
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        owner:
          $ref: "#/components/schemas/IdName"
        created:
          type: integer
          format: date-time
        isMember:
          type: boolean
        memberCount:
          type: integer
          format: int32
    NewFolder:
      description: |
        Data required to create a new folder.
      required:
        - name
      properties:
        name:
          type: string
    FolderDetail:
      description: |
        Details about a folder.
      required:
        - id
        - name
        - owner
        - created
        - isMember
        - memberCount
        - members
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        owner:
          $ref: "#/components/schemas/IdName"
        created:
          type: integer
          format: date-time
        isMember:
          type: boolean
        memberCount:
          type: integer
          format: int32
        members:
          type: array
          items:
            $ref: "#/components/schemas/IdName"
    ItemQuery:
      description: |
        Query description for a search. Is used for fulltext-only
        searches and combined searches.
      required:
        - query
      properties:
        offset:
          type: integer
          format: int32
        limit:
          type: integer
          format: int32
          description: |
            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:
          type: boolean
          default: false
        searchMode:
          type: string
          format: searchmode
          enum:
            - normal
            - trashed
            - all
          default: normal
          description: |
            Specify whether the search query should apply to
            soft-deleted items or not.
        query:
          type: string
          description: |
            A query searching the contents of documents.
    MoveAttachment:
      description: |
        Data to move an attachment to another position.
      required:
        - source
        - target
      properties:
        source:
          type: string
          format: ident
        target:
          type: string
          format: ident
    ScanMailboxSettingsList:
      description: |
        A list of scan-mailbox tasks.
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/ScanMailboxSettings"
    ScanMailboxSettings:
      description: |
        Settings for the scan mailbox task.
      required:
        - id
        - enabled
        - scanRecursively
        - imapConnection
        - schedule
        - folders
        - deleteMail
      properties:
        id:
          type: string
          format: ident
        enabled:
          type: boolean
        summary:
          type: string
        imapConnection:
          type: string
          format: ident
        folders:
          type: array
          items:
            type: string
        scanRecursively:
          type: boolean
          description: |
            Scan folders recursively for new mails.
        schedule:
          type: string
          format: calevent
        receivedSinceHours:
          type: integer
          format: int32
          description: |
            Look only for mails newer than `receivedSinceHours' hours.
        targetFolder:
          type: string
          description: |
            The folder to move all mails into that have been
            successfully submitted to docspell.
        deleteMail:
          type: boolean
          description: |
            Whether to delete all successfully imported mails. This
            only applies, if `targetFolder' is not set.
        direction:
          type: string
          format: direction
          description: |
            The direction to apply to items resulting from importing
            mails. If not set, the value is guessed based on the from
            and to mail headers and your address book.
        itemFolder:
          type: string
          format: ident
          description: |
            The folder id that is applied to items resulting from
            importing mails. If the folder id is not valid when the
            task executes, items have no folder set.
        tags:
          $ref: "#/components/schemas/StringList"
        fileFilter:
          description: |
            A glob to filter attachments to import by file name.
          type: string
          format: glob
        subjectFilter:
          description: |
            A glob to filter attachments to import by subject.
          type: string
          format: glob
        language:
          description: |
            The language for text extraction and analysis when
            processing mails. Use **ISO 639-3** (3-letter codes) such
            as `eng`, `deu`, `fra`; ISO 639-1 (2-letter) like `en`,
            `de` and language names like `english` are also accepted.
          type: string
          format: language
        postHandleAll:
          type: boolean
        attachmentsOnly:
          type: boolean
          description: |
            Import only the attachments e-mails and discard the body

    ImapSettingsList:
      description: |
        A list of user email settings.
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/ImapSettings"
    ImapSettings:
      description: |
        IMAP settings for sending mail.
      required:
        - name
        - imapHost
        - from
        - sslType
        - ignoreCertificates
        - useOAuth
      properties:
        name:
          type: string
          format: ident
        imapHost:
          type: string
        imapPort:
          type: integer
          format: int32
        imapUser:
          type: string
        imapPassword:
          type: string
          format: password
        sslType:
          type: string
        ignoreCertificates:
          type: boolean
        useOAuth:
          type: boolean
          description: |
            Use the password as an OAuth2 access token with the
            authentication scheme XOAUTH2.
    CalEventCheckResult:
      description: |
        The result of checking a calendar event string.
      required:
        - success
        - message
      properties:
        success:
          type: boolean
        message:
          type: string
        event:
          type: string
          format: calevent
        next:
          type: array
          items:
            type: integer
            format: date-time
    CalEventCheck:
      description: |
        A calendar event.
      required:
        - event
      properties:
        event:
          type: string
    SentMails:
      description: |
        A list of sent mails.
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/SentMail"
    SentMail:
      description: |
        A mail that has been sent previously related to an item.
      required:
        - id
        - sender
        - connection
        - recipients
        - subject
        - body
        - created
      properties:
        id:
          type: string
          format: ident
        sender:
          type: string
          format: ident
        connection:
          type: string
          format: ident
        recipients:
          type: array
          items:
            type: string
        subject:
          type: string
        body:
          type: string
        created:
          type: integer
          format: date-time
    SimpleMail:
      description: |
        A simple e-mail related to an item.

        The mail may contain the item attachments as mail attachments.
        If all item attachments should be send, set
        `addAllAttachments` to `true`. Otherwise set it to `false` and
        specify a list of file-ids that you want to include. This list
        is ignored, if `addAllAttachments` is set to `true`.
      required:
        - recipients
        - cc
        - bcc
        - subject
        - body
        - addAllAttachments
        - attachmentIds
      properties:
        recipients:
          type: array
          items:
            type: string
        cc:
          type: array
          items:
            type: string
        bcc:
          type: array
          items:
            type: string
        subject:
          type: string
        body:
          type: string
        addAllAttachments:
          type: boolean
        attachmentIds:
          type: array
          items:
            type: string
            format: ident
    SimpleShareMail:
      description: |
        A simple e-mail related to a share.
      required:
        - shareId
        - recipients
        - cc
        - bcc
        - subject
        - body
      properties:
        shareId:
          type: string
          format: ident
        recipients:
          type: array
          items:
            type: string
        cc:
          type: array
          items:
            type: string
        bcc:
          type: array
          items:
            type: string
        subject:
          type: string
        body:
          type: string
    EmailSettingsList:
      description: |
        A list of user email settings.
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/EmailSettings"
    EmailSettings:
      description: |
        SMTP settings for sending mail.
      required:
        - name
        - smtpHost
        - from
        - sslType
        - ignoreCertificates
      properties:
        name:
          type: string
          format: ident
        smtpHost:
          type: string
        smtpPort:
          type: integer
          format: int32
        smtpUser:
          type: string
        smtpPassword:
          type: string
          format: password
        from:
          type: string
        replyTo:
          type: string
        sslType:
          type: string
        ignoreCertificates:
          type: boolean
    CheckFileResult:
      description: |
        Results when searching for file checksums.
      required:
        - exists
        - items
      properties:
        exists:
          type: boolean
        items:
          type: array
          items:
            $ref: "#/components/schemas/BasicItem"
    BasicItem:
      description: |
        Basic properties about an item.
      required:
        - id
        - name
        - direction
        - state
        - created
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        direction:
          type: string
          format: direction
        state:
          type: string
          format: itemstate
        created:
          type: integer
          format: date-time
        itemDate:
          type: integer
          format: date-time
    GenInvite:
      description: |
        A request to generate a new invitation key.
      required:
        - password
      properties:
        password:
          type: string
          format: password
    InviteResult:
      description: |
        The result when requesting new invitation keys.
      required:
        - success
        - message
      properties:
        success:
          type: boolean
        message:
          type: string
        key:
          type: string
          format: ident
    SearchStats:
      description: |
        A summary of search results.
      required:
        - count
        - tagCloud
        - tagCategoryCloud
        - fieldStats
        - folderStats
        - corrOrgStats
        - corrPersStats
        - concPersStats
        - concEquipStats
      properties:
        count:
          type: integer
          format: int32
        tagCloud:
          $ref: "#/components/schemas/TagCloud"
        tagCategoryCloud:
          $ref: "#/components/schemas/NameCloud"
        fieldStats:
          type: array
          items:
            $ref: "#/components/schemas/FieldStats"
        folderStats:
          type: array
          items:
            $ref: "#/components/schemas/FolderStats"
        corrOrgStats:
          type: array
          items:
            $ref: "#/components/schemas/IdRefStats"
        corrPersStats:
          type: array
          items:
            $ref: "#/components/schemas/IdRefStats"
        concPersStats:
          type: array
          items:
            $ref: "#/components/schemas/IdRefStats"
        concEquipStats:
          type: array
          items:
            $ref: "#/components/schemas/IdRefStats"

    ItemInsights:
      description: |
        Information about the items in docspell.
      required:
        - incomingCount
        - outgoingCount
        - deletedCount
        - itemSize
        - tagCloud
      properties:
        incomingCount:
          type: integer
          format: int32
        outgoingCount:
          type: integer
          format: int32
        deletedCount:
          type: integer
          format: int32
        itemSize:
          type: integer
          format: int64
        tagCloud:
          $ref: "#/components/schemas/TagCloud"
    FolderStats:
      description: |
        Count of folder usage.
      required:
        - id
        - name
        - owner
        - count
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        owner:
          $ref: "#/components/schemas/IdName"
        count:
          type: integer
          format: int32
    FieldStats:
      description: |
        Basic statistics about a custom field.
      required:
        - id
        - name
        - ftype
        - count
        - avg
        - sum
        - max
        - min
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
          format: ident
        label:
          type: string
        ftype:
          type: string
          format: customfieldtype
          enum:
            - text
            - numeric
            - date
            - bool
            - money
        count:
          type: integer
          format: int32
        sum:
          type: number
          format: double
        avg:
          type: number
          format: double
        max:
          type: number
          format: double
        min:
          type: number
          format: double
    TagCloud:
      description: |
        A tag "cloud"
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/TagCount"
    TagCount:
      description: |
        Structure for counting tags.
      required:
        - tag
        - count
      properties:
        tag:
          $ref: "#/components/schemas/Tag"
        count:
          type: integer
          format: int32

    NameCloud:
      description: |
        A set of counters.
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/NameCount"
    NameCount:
      description: |
        Generic structure for counting something.
      required:
        - count
      properties:
        name:
          type: string
        count:
          type: integer
          format: int32

    IdRefStats:
      description: |
        Counting some objects that have an id and a name.
      required:
        - ref
        - count
      properties:
        ref:
          $ref: "#/components/schemas/IdName"
        count:
          type: integer
          format: int32

    AttachmentMeta:
      description: |
        Extracted meta data of an attachment.
      required:
        - content
        - labels
        - proposals
      properties:
        content:
          type: string
        labels:
          type: array
          items:
            $ref: "#/components/schemas/Label"
        proposals:
          $ref: "#/components/schemas/ItemProposals"
    ItemProposals:
      description: |
        Metadata that has been suggested to an item.
      required:
        - corrOrg
        - corrPerson
        - concPerson
        - concEquipment
        - itemDate
        - dueDate
      properties:
        corrOrg:
          type: array
          items:
            $ref: "#/components/schemas/IdName"
        corrPerson:
          type: array
          items:
            $ref: "#/components/schemas/IdName"
        concPerson:
          type: array
          items:
            $ref: "#/components/schemas/IdName"
        concEquipment:
          type: array
          items:
            $ref: "#/components/schemas/IdName"
        itemDate:
          type: array
          items:
            type: integer
            format: date-time
        dueDate:
          type: array
          items:
            type: integer
            format: date-time
    Label:
      description: |
        Extracted label.
      required:
        - labelType
        - label
        - beginPos
        - endPos
      properties:
        labelType:
          type: string
          format: nertag
        label:
          type: string
        beginPos:
          type: integer
          format: int32
        endPos:
          type: integer
          format: int32
    OptionalDate:
      description: |
        Structure for sending an optional datetime value.
      properties:
        date:
          type: integer
          format: date-time
    OptionalText:
      description: |
        Structure for sending optional text.
      properties:
        text:
          type: string
    OptionalId:
      description: |
        Structure for sending optional ids.
      properties:
        id:
          type: string
          format: ident
    DirectionValue:
      description: |
        A direction.
      required:
        - direction
      properties:
        direction:
          type: string
          format: direction
    ItemDetail:
      description: |
        Detailed information about an item.
      required:
        - id
        - direction
        - name
        - source
        - state
        - created
        - updated
        - attachments
        - sources
        - archives
        - tags
        - customfields
        - relatedItems
      properties:
        id:
          type: string
          format: ident
        direction:
          type: string
          format: direction
          enum:
            - incoming
            - outgoing
        name:
          type: string
        source:
          type: string
        state:
          type: string
          format: itemstate
        created:
          type: integer
          format: date-time
        updated:
          type: integer
          format: date-time
        itemDate:
          type: integer
          format: date-time
        corrOrg:
          $ref: "#/components/schemas/IdName"
        corrPerson:
          $ref: "#/components/schemas/IdName"
        concPerson:
          $ref: "#/components/schemas/IdName"
        concEquipment:
          $ref: "#/components/schemas/IdName"
        folder:
          $ref: "#/components/schemas/IdName"
        dueDate:
          type: integer
          format: date-time
        notes:
          type: string
        attachments:
          type: array
          items:
            $ref: "#/components/schemas/Attachment"
        sources:
          type: array
          items:
            $ref: "#/components/schemas/AttachmentSource"
        archives:
          type: array
          items:
            $ref: "#/components/schemas/AttachmentSource"
        tags:
          type: array
          items:
            $ref: "#/components/schemas/Tag"
        customfields:
          type: array
          items:
            $ref: "#/components/schemas/ItemFieldValue"
        relatedItems:
          description: |
            All related items to this item. The list contains items
            without more details being resolved.
          type: array
          items:
            $ref: "#/components/schemas/ItemLight"
    Attachment:
      description: |
        Information about an attachment to an item.
      required:
        - id
        - size
        - contentType
        - converted
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        size:
          type: integer
          format: int64
        contentType:
          type: string
          format: mimetype
        converted:
          type: boolean
    AttachmentSource:
      description: |
        The source or original file of an attachment.
      required:
        - id
        - size
        - contentType
      properties:
        id:
          type: string
          format: ident
          description: |
            The id is the attachment id.
        name:
          type: string
        size:
          type: integer
          format: int64
        contentType:
          type: string
          format: mimetype
    Registration:
      description: |
        Data for registering a new account.
      required:
        - collectiveName
        - login
        - password
      properties:
        collectiveName:
          type: string
          format: ident
        login:
          type: string
          format: ident
        password:
          type: string
          format: password
        invite:
          type: string
          format: ident
    JobQueueState:
      description: |
        Contains all information about the job queue.
      required:
        - progress
        - completed
        - queued
      properties:
        progress:
          type: array
          items:
            $ref: "#/components/schemas/JobDetail"
        completed:
          type: array
          items:
            $ref: "#/components/schemas/JobDetail"
        queued:
          type: array
          items:
            $ref: "#/components/schemas/JobDetail"
    JobDetail:
      description: |
        Details about a job.
      required:
        - id
        - name
        - submitted
        - priority
        - state
        - retries
        - logs
        - progress
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        submitted:
          description: DateTime
          type: integer
          format: date-time
        priority:
          type: string
          format: priority
          enum:
            - high
            - low
        state:
          type: string
          format: jobstate
          enum:
            - waiting
            - scheduled
            - running
            - stuck
            - failed
            - canceled
            - success
        retries:
          type: integer
          format: int32
        logs:
          type: array
          items:
            $ref: "#/components/schemas/JobLogEvent"
        progress:
          type: integer
          format: int32
        worker:
          type: string
          format: ident
        started:
          description: DateTime
          type: integer
          format: date-time
        finished:
          type: integer
          format: date-time
    JobLogEvent:
      description: |
        A log output line.
      required:
        - time
        - level
        - message
      properties:
        time:
          description: DateTime
          type: integer
          format: date-time
        level:
          type: string
          format: loglevel
        message:
          type: string
    PasswordChange:
      description: |
        Change the password, by given the old and new one.
      required:
        - currentPassword
        - newPassword
      properties:
        currentPassword:
          type: string
          format: password
        newPassword:
          type: string
          format: password
    UserList:
      description: |
        A list of users.
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/User"
    User:
      description: |
        A user of a collective.
      required:
        - id
        - login
        - state
        - source
        - loginCount
        - created
      properties:
        id:
          type: string
          format: ident
        login:
          type: string
          format: ident
        state:
          type: string
          format: userstate
          enum:
            - active
            - disabled
        source:
          type: string
          format: accountsource
          enum:
            - local
            - openid
        password:
          type: string
          format: password
        email:
          type: string
        lastLogin:
          description: DateTime
          type: integer
          format: date-time
        loginCount:
          type: integer
          format: int32
        created:
          description: DateTime
          type: integer
          format: date-time

    ItemUploadMeta:
      description: |
        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.
      required:
        - multiple
      properties:
        multiple:
          type: boolean
          default: true
          description: |
            If `true` (the default) each file in the upload request
            results in a separate item. If it is set to `false`, then
            all files in the request are put into a single item.
        flattenArchives:
          type: boolean
          default: false
          description: |
            This implies `multiple = true` and will (when `true`)
            treat every ZIP file as a container of independent files
            that will result in separate items. When this is `false`
            then each zip file will result in one item with its
            contents being the attachments.
        direction:
          type: string
          format: direction
          default: "incoming"
          description: |
            The direction of the item, can be `Incoming` or `Outgoing`.
        folder:
          type: string
          format: ident
          description: |
            A folder can be specified that is attached to the new
            item. The folder must exist and can be specified by id or
            name.
        skipDuplicates:
          type: boolean
          default: false
          description: |
            If set to `true` the processing will look for the same
            file in Docspell and will skip processing this one if one
            is found. The check is done via the file's checksum.
        tags:
          $ref: "#/components/schemas/StringList"
          description: |
            The `tags` input allows to provide tags that should be
            applied to the item being created. This only works if the
            tags already exist. It is possible to specify their ids or
            names.
        fileFilter:
          type: string
          format: glob
          description: |
            The `fileFilter` is an optional glob for filtering files
            to import. Only applicable if archive files are uploaded.
            It applies to all of them. For example, to only import pdf
            files when uploading e-mails, use `*.pdf`. If the pattern
            doesn't contain a slash `/`, then it is applied to all
            file names. Otherwise it is applied to the complete path
            in the archive (useful for zip files). Note that the
            archive file itself is always saved completely, too.
        language:
          type: string
          format: language
          description: |
            The language of the document for processing (OCR, text
            extraction, analysis). If not specified, the collective's
            default language is used.

            Use **ISO 639-3** (3-letter codes) such as `eng`, `deu`,
            `fra`, `spa`. ISO 639-1 (2-letter) codes like `en`, `de`
            and language names like `english`, `german` are also
            accepted. Supported languages include German, English,
            French, Italian, Spanish, Portuguese, Czech, Danish,
            Finnish, Norwegian, Swedish, Russian, Romanian, Dutch,
            Latvian, Japanese, Hebrew, Hungarian, Lithuanian, Polish,
            Estonian, Ukrainian, Khmer, Slovak.
        attachmentsOnly:
          type: boolean
          default: false
          description: |
            Only applies to e-mail files. If `true` then only
            attachments of the e-mail are imported and the e-mail body
            is discarded. E-mails that don't have any attachments are
            skipped.
        customData:
          type: object
          format: json
          description: |
            Custom user data that gets threaded through the processing. Docspell
            ignores it completely, but will pass it to the outcome of processing
            to be able to react on it in addons or other ways.

    Collective:
      description: |
        Information about a collective.
      required:
        - id
        - state
        - created
      properties:
        id:
          type: string
          format: ident
        state:
          type: string
          format: collectivestate
        created:
          description: DateTime
          type: integer
          format: date-time

    CollectiveSettings:
      description: |
        Settings for a collective.
      required:
        - language
        - integrationEnabled
        - classifier
        - emptyTrash
        - passwords
      properties:
        language:
          type: string
          format: language
          description: |
            Default document language for the collective. Use **ISO
            639-3** (3-letter codes) like `eng`, `deu`, `fra`; ISO
            639-1 (2-letter) like `en`, `de` and language names are
            also accepted.
        integrationEnabled:
          type: boolean
          description: |
            Whether the collective has the integration endpoint
            enabled.
        classifier:
          $ref: "#/components/schemas/ClassifierSetting"
        emptyTrash:
          $ref: "#/components/schemas/EmptyTrashSetting"
        passwords:
          type: array
          items:
            type: string
            format: password

    EmptyTrashSetting:
      description: |
        Settings for clearing the trash of items.
      required:
        - schedule
        - minAge
      properties:
        schedule:
          type: string
          format: calevent
        minAge:
          type: integer
          format: duration

    ClassifierSetting:
      description: |
        Settings for learning a document classifier.
      required:
        - schedule
        - itemCount
        - categoryList
        - listType
      properties:
        itemCount:
          type: integer
          format: int32
          description: |
            The max. number of items to learn from. The newest items
            are considered.
        schedule:
          type: string
          format: calevent
        categoryList:
          type: array
          items:
            type: string
        listType:
          type: string
          format: listtype
          enum:
            - blacklist
            - whitelist

    SourceList:
      description: |
        A list of sources.
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/SourceAndTags"

    Source:
      description: |
        Data about a Source. A source defines the endpoint where
        docspell receives files.
      required:
        - id
        - abbrev
        - counter
        - enabled
        - priority
        - created
        - attachmentsOnly
      properties:
        id:
          type: string
          format: ident
        abbrev:
          type: string
        description:
          type: string
        counter:
          type: integer
          format: int32
        enabled:
          type: boolean
        priority:
          type: string
          format: priority
          enum:
            - high
            - low
        folder:
          type: string
          format: ident
        fileFilter:
          type: string
          format: glob
        language:
          type: string
          format: language
          description: |
            Document language for uploads via this source. Use **ISO
            639-3** (3-letter codes) like `eng`, `deu`, `fra`; ISO
            639-1 (2-letter) and language names are also accepted.
        created:
          description: DateTime
          type: integer
          format: date-time
        attachmentsOnly:
          type: boolean
    SourceTagIn:
      description: |
        A source and optional tags (ids or names) for updating/adding.
      required:
        - source
        - tags
      properties:
        source:
          $ref: "#/components/schemas/Source"
        tags:
          type: array
          items:
            type: string
    SourceAndTags:
      description: |
        A source and optional tags.
      required:
        - source
        - tags
      properties:
        source:
          $ref: "#/components/schemas/Source"
        tags:
          $ref: "#/components/schemas/TagList"

    EquipmentList:
      description: |
        A list of equipments.
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Equipment"
    Equipment:
      description: |
        Some "thing" that occurs in documents.
      required:
        - id
        - name
        - created
        - use
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        created:
          description: DateTime
          type: integer
          format: date-time
        notes:
          type: string
        use:
          type: string
          format: equipmentuse
          enum:
            - concerning
            - disabled
    ReferenceList:
      description:
        Listing of entities with their id and a name.
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/IdName"
    Person:
      description: |
        Basic information about a person.
      required:
        - id
        - name
        - address
        - contacts
        - created
        - use
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        organization:
          $ref: "#/components/schemas/IdName"
        address:
          $ref: "#/components/schemas/Address"
        contacts:
          type: array
          items:
            $ref: "#/components/schemas/Contact"
        notes:
          type: string
        use:
          type: string
          format: personuse
          enum:
            - concerning
            - correspondent
            - both
            - disabled
          description: |
            Whether this person should be used to create suggestions
            for the "concerning person", "correspondent" or both.
        created:
          description: DateTime
          type: integer
          format: date-time
    PersonList:
      description: |
        A list of persons.
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Person"
    Organization:
      description: |
        An organisation.
      required:
        - id
        - name
        - address
        - contacts
        - created
        - use
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        address:
          $ref: "#/components/schemas/Address"
        contacts:
          type: array
          items:
            $ref: "#/components/schemas/Contact"
        notes:
          type: string
        created:
          description: DateTime
          type: integer
          format: date-time
        shortName:
          type: string
        use:
          type: string
          format: orguse
          enum:
            - correspondent
            - disabled
    OrganizationList:
      description: |
        A list of full organization values.
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Organization"
    Address:
      description: |
        Postal address information.
      required:
        - street
        - zip
        - city
        - country
      properties:
        street:
          type: string
        zip:
          type: string
        city:
          type: string
        country:
          type: string
    ContactList:
      description: |
        A list of contacts.
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Contact"
    Contact:
      description: |
        Contact information.
      required:
        - id
        - value
        - kind
      properties:
        id:
          type: string
          format: ident
        value:
          type: string
        kind:
          type: string
          format: contactkind
          enum:
            - phone
            - mobile
            - website
            - fax
            - docspell
            - email
    ItemLightList:
      description: |
        A list of item details.
      required:
        - groups
        - limit
        - offset
        - limitCapped
      properties:
        groups:
          type: array
          items:
            $ref: "#/components/schemas/ItemLightGroup"
        limit:
          type: integer
          format: int32
          description: |
            Returns the `limit` value as used for this search. This
            can deviate from the requested limit, if it exceeds the
            server defined maximum. See `limitCapped`.
        offset:
          type: integer
          format: int32
          description: |
            The `offset` value used for this search.
        limitCapped:
          type: boolean
          description: |
            The server defines a maximum `limit` value. If the
            requested `limit` exceeds the server defined one, this
            flag is set to true. The limit used for the query is
            returned with this response.
    ItemLightGroup:
      description: |
        A group of items.
      required:
        - name
        - items
      properties:
        name:
          type: string
        items:
          type: array
          items:
            $ref: "#/components/schemas/ItemLight"
    ItemLight:
      description: |
        An item with only a few important properties.
      required:
        - id
        - name
        - state
        - date
        - source
        - tags
        - attachments
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        state:
          type: string
          format: itemstate
        date:
          type: integer
          format: date-time
        dueDate:
          type: integer
          format: date-time
        source:
          type: string
        direction:
          type: string
          enum:
            - incoming
            - outgoing
        corrOrg:
          $ref: "#/components/schemas/IdName"
        corrPerson:
          $ref: "#/components/schemas/IdName"
        concPerson:
          $ref: "#/components/schemas/IdName"
        concEquipment:
          $ref: "#/components/schemas/IdName"
        folder:
          $ref: "#/components/schemas/IdName"
        attachments:
          type: array
          items:
            $ref: "#/components/schemas/AttachmentLight"
        tags:
          type: array
          items:
            $ref: "#/components/schemas/Tag"
        customfields:
          type: array
          items:
            $ref: "#/components/schemas/ItemFieldValue"
        relatedItems:
          type: array
          items:
            type: string
            format: ident
        notes:
          description: |
            Some prefix of the item notes.
          type: string
        highlighting:
          description: |
            Optional contextual information of a search query. Each
            item refers to some field where a search match was found
            (e.g. the name of an attachment or the item notes) and a
            list of lines giving surrounding context of the macth.
          type: array
          items:
            $ref: "#/components/schemas/HighlightEntry"
    AttachmentLight:
      description: |
        Some little details about an attachment.
      required:
        - id
        - position
      properties:
        id:
          type: string
          format: ident
        position:
          type: integer
          format: int32
        name:
          type: string
        pageCount:
          type: integer
          format: int32
    HighlightEntry:
      description: |
        Highlighting information for a single field (maybe attachment
        name or item notes).
      required:
        - name
        - lines
      properties:
        name:
          type: string
        lines:
          type: array
          items:
            type: string
    IdName:
      description: |
        The identifier and a human readable name of some entity.
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
    BasicResult:
      description: |
        Some basic result of an operation.
      required:
        - success
        - message
      properties:
        success:
          type: boolean
        message:
          type: string
    IdResult:
      description: |
        Some basic result of an operation with an ID as payload, if
        success is true. If success is `false` the id is not usable.
      required:
        - success
        - message
        - id
      properties:
        success:
          type: boolean
        message:
          type: string
        id:
          type: string
          format: ident
    Tag:
      description: |
        A tag used to annotate items. A tag may have a category which
        groups tags together.
      required:
        - id
        - name
        - created
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        category:
          type: string
        created:
          type: integer
          format: date-time
    TagList:
      description: |
        A list of tags.
      required:
        - count
        - items
      properties:
        count:
          type: integer
          format: int32
        items:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
    UserPass:
      description: |
        Account name and password.
      required:
        - account
        - password
      properties:
        account:
          type: string
        password:
          type: string
        rememberMe:
          type: boolean
    AuthResult:
      description: |
        The response to a authentication request.
      required:
        - collective
        - user
        - requireSecondFactor
        - success
        - message
        - validMs
      properties:
        collective:
          type: string
        user:
          type: string
        success:
          type: boolean
        message:
          type: string
        token:
          description: |
            The authentication token that should be used for
            subsequent requests to secured endpoints.
          type: string
        validMs:
          description: |
            How long the token is valid in ms.
          type: integer
          format: int64
        requireSecondFactor:
          type: boolean
    VersionInfo:
      description: |
        Information about the software.
      required:
        - version
        - builtAtMillis
        - builtAtString
        - gitCommit
        - gitVersion
      properties:
        version:
          type: string
        builtAtMillis:
          type: integer
          format: int64
        builtAtString:
          type: string
        gitCommit:
          type: string
        gitVersion:
          type: string
  securitySchemes:
    authTokenHeader:
      type: apiKey
      in: header
      name: X-Docspell-Auth
    adminHeader:
      type: apiKey
      in: header
      name: Docspell-Admin-Secret
    shareTokenHeader:
      type: apiKey
      in: header
      name: Docspell-Share-Auth
  parameters:
    id:
      name: id
      in: path
      description: An identifier
      required: true
      schema:
        type: string
    userId:
      name: userId
      in: path
      description: An identifier
      required: true
      schema:
        type: string
    shareId:
      name: shareId
      in: path
      description: An identifier for a share
      required: true
      schema:
        type: string
    username:
      name: username
      in: path
      required: true
      description: The username of a user of this collective
      schema:
        type: string
    itemId:
      name: itemId
      in: path
      description: An identifier for an item
      required: true
      schema:
        type: string
    full:
      name: full
      in: query
      description: Whether to list full data or just name and id.
      required: false
      schema:
        type: boolean
    owning:
      name: full
      in: query
      description: Whether to get owning folders
      required: false
      schema:
        type: boolean
    owningShare:
      name: owning
      in: query
      description: Return my own shares only
      required: false
      schema:
        type: boolean
    checksum:
      name: checksum
      in: path
      description: A SHA-256 checksum
      required: true
      schema:
        type: string
    q:
      name: q
      in: query
      description: A query string.
      required: false
      schema:
        type: string
    limit:
      name: limit
      in: query
      description: A limit for a search query
      schema:
        type: integer
        format: int32
    offset:
      name: offset
      in: query
      description: A offset into the results for a search query
      schema:
        type: integer
        format: int32
    sort:
      name: sort
      in: query
      required: false
      description: |
        How to sort the returned list
      schema:
        type: string
    withDetails:
      name: withDetails
      in: query
      description: Whether to return details to each item.
      schema:
        type: boolean
    searchMode:
      name: searchMode
      in: query
      schema:
        type: string
        format: searchmode
      description: |
        Specify whether the search query should apply to soft-deleted
        items or not.
    name:
      name: name
      in: path
      description: An e-mail connection name
      required: true
      schema:
        type: string
    mailId:
      name: mailId
      in: path
      description: The id of a sent mail.
      required: true
      schema:
        type: string
    contactKind:
      name: kind
      in: query
      required: false
      description: |
        One of the available contact kinds.
      schema:
        type: string
    withFallback:
      name: withFallback
      in: query
      description: Whether to provide a fallback or not.
      required: false
      schema:
        type: boolean
    clientId:
      name: clientId
      in: path
      required: true
      description: |
        some identifier for a client application
      schema:
        type: string
    bookmarkId:
      name: bookmarkId
      in: path
      required: true
      description: |
        An identifier for a bookmark
      schema:
        type: string
    providerId:
      name: providerId
      in: path
      required: true
      schema:
        type: string
        format: ident