openapi: 3.0.0

info:
  title: Docspell
  version: 0.7.0
  description: |
    This is the remote API to Docspell, a personal document organizer.

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

paths:
  /api/info/version:
    get:
      tags: [ Information ]
      summary: Get version information.
      description: |
        Returns information about this software.
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VersionInfo"
  /open/auth/login:
    post:
      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.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserPass"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthResult"
  /open/checkfile/{id}/{checksum}:
    get:
      tags: [ Upload ]
      summary: Check if a file is in docspell.
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CheckFileResult"
  /open/upload/item/{id}:
    post:
      tags: [ Upload ]
      summary: Upload files to docspell.
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /open/upload/item/{itemId}/{id}:
    post:
      tags: [ Upload ]
      summary: Upload files to docspell.
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/checkfile/{checksum}:
    get:
      tags: [ Upload ]
      summary: Check if a file is in docspell.
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CheckFileResult"
  /sec/upload:
    post:
      tags: [ Upload ]
      summary: Upload files to docspell.
      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 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.
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/upload/{itemId}:
    post:
      tags: [ Upload ]
      summary: Upload files to docspell.
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /open/integration/item/{id}:
    get:
      tags: [ Upload Integration ]
      summary: Upload files to docspell.
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                type: object
        404:
          description: Not Found
        403:
          description: Forbidden
        401:
          description: Unauthorized
    post:
      tags: [ Upload Integration ]
      summary: Upload files to docspell.
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /open/signup/register:
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /open/signup/newinvite:
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InviteResult"
  /sec/auth/session:
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthResult"
  /sec/auth/logout:
    post:
      tags: [ Authentication ]
      summary: Logout.
      description: |
        This route informs the server about a logout. This is not
        strictly necessary.
      security:
        - authTokenHeader: []
      responses:
        200:
          description: Ok
  /sec/tag:
    get:
      tags: [ Tags ]
      summary: Get a list of tags
      description: |
        Return a list of all configured tags.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/q"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagList"
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    put:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/tag/{id}:
    delete:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/organization:
    get:
      tags: [ Organization ]
      summary: Get a list of organizations.
      description: |
        Return a list of all organizations. Only name and id are returned.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/full"
        - $ref: "#/components/parameters/q"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ReferenceList"
                  - $ref: "#/components/schemas/OrganizationList"
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    put:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/organization/{id}:
    get:
      tags: [ Organization ]
      summary: Get a list of organizations.
      description: |
        Return details about an organization.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
    delete:
      tags: [ Organization ]
      summary: Delete a organization by its id.
      description: |
        Deletes an organization.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/person:
    get:
      tags: [ Person ]
      summary: Get a list of persons.
      description: |
        Return a list of all persons. Only name and id are returned.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/full"
        - $ref: "#/components/parameters/q"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ReferenceList"
                  - $ref: "#/components/schemas/PersonList"
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    put:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/person/{id}:
    get:
      tags: [ Person ]
      summary: Get person details.
      description: |
        Return details about an person.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Person"
    delete:
      tags: [ Person ]
      summary: Delete a person by its id.
      description: |
        Deletes an person.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/equipment:
    get:
      tags: [ Equipment ]
      summary: Get a list of equipments
      description: |
        Return a list of all configured equipments.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/q"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EquipmentList"
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    put:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/equipment/{id}:
    delete:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/collective:
    get:
      tags: [ Collective ]
      summary: Get information about your collective
      description: |
        Return some information about the current collective.
      security:
        - authTokenHeader: []
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Collective"
  /sec/collective/settings:
    get:
      tags: [ Collective ]
      summary: Get collective settings
      description: |
        Return the settings of a collective.
      security:
        - authTokenHeader: []
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectiveSettings"
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Collective"
  /sec/collective/insights:
    get:
      tags: [ Collective ]
      summary: Get some insights regarding your items.
      description: |
        Returns some information about how many items there are, how
        much space they occupy etc.
      security:
        - authTokenHeader: []
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ItemInsights"
  /sec/collective/contacts:
    get:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactList"
  /sec/user:
    get:
      tags: [ Collective ]
      summary: Get a list of collective users.
      description: |
        Return a list of all users of the collective.
      security:
        - authTokenHeader: []
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserList"
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    put:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/user/{id}:
    delete:
      tags: [ Collective ]
      summary: Delete a user.
      description: |
        Deletes a user.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/user/changePassword:
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/source:
    get:
      tags: [ Source ]
      summary: Get a list of sources
      description: |
        Return a list of all configured sources.
      security:
        - authTokenHeader: []
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourceList"
    post:
      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/Source"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    put:
      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/Source"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/source/{id}:
    delete:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/item/search:
    post:
      tags: [ Item ]
      summary: Search for items.
      description: |
        Search for items given a search form. The results are grouped
        by month by default. Tags are *not* resolved! The results will
        always contain an empty list for item tags. Use
        `/searchWithTags` to also retrieve all tags of an item.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemSearch"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ItemLightList"
  /sec/item/searchWithTags:
    post:
      tags: [ Item ]
      summary: Search for items.
      description: |
        Search for items given a search form. The results are grouped
        by month by default. For each item, its tags are also
        returned. This uses more queries and is therefore slower.
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemSearch"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ItemLightList"
  /sec/item/{id}:
    get:
      tags: [ Item ]
      summary: Get details about an item.
      description: |
        Get detailed information about an item.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ItemDetail"
    delete:
      tags: [ Item ]
      summary: Delete an item.
      description: |
        Delete an item and all its data permanently.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/tags:
    put:
      tags: [ Item ]
      summary: Set new set of tags.
      description: |
        Update the tags associated to an item.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReferenceList"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/direction:
    put:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/corrOrg:
    put:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/corrPerson:
    put:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/concPerson:
    put:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/concEquipment:
    put:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/notes:
    put:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/name:
    put:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/confirm:
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/unconfirm:
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/date:
    put:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/duedate:
    put:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/item/{id}/proposals:
    get:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ItemProposals"
  /sec/item/{itemId}/attachment/movebefore:
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/attachment/{id}:
    delete:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    head:
      tags: [ Attachment ]
      summary: Get 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:
        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:
      tags: [ Attachment ]
      summary: Get an attachment file.
      description: |
        Get the binary file belonging to the attachment with the given
        id.
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        200:
          description: Ok
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /sec/attachment/{id}/original:
    head:
      tags: [ Attachment ]
      summary: Get an attachment file.
      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:
        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:
      tags: [ Attachment ]
      summary: Get an attachment file.
      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:
        200:
          description: Ok
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /sec/attachment/{id}/archive:
    head:
      tags: [ Attachment ]
      summary: Get an attachment archive file.
      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:
        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:
      tags: [ Attachment ]
      summary: Get an attachment archive file.
      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:
        200:
          description: Ok
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
  /sec/attachment/{id}/meta:
    get:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttachmentMeta"
  /sec/attachment/{id}/view:
    get:
      tags: [ Attachment ]
      summary: A preview of the attachment
      description: |
        This provides a preview of the attachment. 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
        200:
          description: Ok
  /sec/attachment/{id}/name:
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/queue/state:
    get:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobQueueState"
  /sec/queue/{id}/cancel:
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/email/settings/smtp:
    get:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailSettingsList"
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/email/settings/smtp/{name}:
    parameters:
      - $ref: "#/components/parameters/name"
    get:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailSettings"
    put:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    delete:
      tags: [ E-Mail ]
      summary: Delete e-mail settings.
      description: |
        Deletes the e-mail settings with the specified `name`.
      security:
        - authTokenHeader: []
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/email/settings/imap:
    get:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImapSettingsList"
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/email/settings/imap/{name}:
    parameters:
      - $ref: "#/components/parameters/name"
    get:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImapSettings"
    put:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    delete:
      tags: [ E-Mail ]
      summary: Delete e-mail settings.
      description: |
        Deletes the e-mail settings with the specified `name`.
      security:
        - authTokenHeader: []
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/email/send/{name}/{id}:
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/email/sent/item/{id}:
    get:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SentMails"
  /sec/email/sent/mail/{mailId}:
    parameters:
      - $ref: "#/components/parameters/mailId"
    get:
      tags: [ E-Mail ]
      summary: Get sent single mail related to an item
      description: |
        Return one mail with the given id.
      security:
        - authTokenHeader: []
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SentMail"
    delete:
      tags: [ E-Mail ]
      summary: Delete a sent mail.
      description: |
        Delete a sent mail.
      security:
        - authTokenHeader: []
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/calevent/check:
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CalEventCheckResult"
  /sec/usertask/notifydueitems:
    get:
      tags: [ User Tasks ]
      summary: Get settings for "Notify Due Items" task
      description: |
        Return the 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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationSettingsList"
    post:
      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/NotificationSettings"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    put:
      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/NotificationSettings"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/usertask/notifydueitems/{id}:
    parameters:
      - $ref: "#/components/parameters/id"
    get:
      tags: [ User Tasks ]
      description: |
        Return the current settings for a single notify-due-items task
        of the authenticated user.
      security:
        - authTokenHeader: []
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationSettings"
    delete:
      tags: [ User Tasks ]
      description: |
        Delete the settings to a notify-due-items task of the
        authenticated user.
      security:
        - authTokenHeader: []
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/usertask/notifydueitems/startonce:
    post:
      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/NotificationSettings"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/usertask/scanmailbox:
    get:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScanMailboxSettingsList"
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    put:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/usertask/scanmailbox/{id}:
    parameters:
      - $ref: "#/components/parameters/id"
    get:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScanMailboxSettings"
    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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/usertask/scanmailbox/startonce:
    post:
      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:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

components:
  schemas:
    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
        - imapConnection
        - schedule
        - folders
        - deleteMail
      properties:
        id:
          type: string
          format: ident
        enabled:
          type: boolean
        imapConnection:
          type: string
          format: ident
        folders:
          type: array
          items:
            type: string
        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.
    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
      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
    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
    NotificationSettingsList:
      description: |
        A list of notification settings.
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/NotificationSettings"
    NotificationSettings:
      description: |
        Settings for notifying about due items.
      required:
        - id
        - enabled
        - smtpConnection
        - recipients
        - schedule
        - remindDays
        - capOverdue
        - tagsInclude
        - tagsExclude
      properties:
        id:
          type: string
          format: ident
        enabled:
          type: boolean
        smtpConnection:
          type: string
          format: ident
        recipients:
          type: array
          items:
            type: string
            format: ident
        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"
    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
        - subject
        - body
        - addAllAttachments
        - attachmentIds
      properties:
        recipients:
          type: array
          items:
            type: string
        subject:
          type: string
        body:
          type: string
        addAllAttachments:
          type: boolean
        attachmentIds:
          type: array
          items:
            type: string
            format: ident
    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
    ItemInsights:
      description: |
        Information about the items in docspell.
      required:
        - incomingCount
        - outgoingCount
        - itemSize
        - tagCloud
      properties:
        incomingCount:
          type: integer
          format: int32
        outgoingCount:
          type: integer
          format: int32
        itemSize:
          type: integer
          format: int64
        tagCloud:
          $ref: "#/components/schemas/TagCloud"
    TagCloud:
      description: |
        A tag "cloud"
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/NameCount"
    NameCount:
      description: |
        Generic structure for counting something.
      required:
        - name
        - count
      properties:
        name:
          type: string
        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
      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"
        inReplyTo:
          $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"
    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
        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:
        - login
        - state
        - loginCount
        - created
      properties:
        login:
          type: string
          format: ident
        state:
          type: string
          format: userstate
          enum:
            - active
            - disabled
        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, 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
        direction:
          type: string
          format: direction
    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
      properties:
        language:
          type: string
          format: language
        integrationEnabled:
          type: boolean
          description: |
            Whether the collective has the integration endpoint
            enabled.
    SourceList:
      description: |
        A list of sources.
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Source"
    Source:
      description: |
        Data about a Source. A source defines the endpoint where
        docspell receives files.
      required:
        - id
        - abbrev
        - counter
        - enabled
        - priority
        - created
      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
        created:
          description: DateTime
          type: integer
          format: date-time
    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
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        created:
          description: DateTime
          type: integer
          format: date-time
    ReferenceList:
      description:
        Listing of items.
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/IdName"
    Person:
      description: |
        Basic information about a person.
      required:
        - id
        - name
        - address
        - contacts
        - created
        - concerning
      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
        concerning:
          type: boolean
          description: |
            Whether this person should be used to create suggestions
            for the "concerning person" association.
        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
      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
    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
      properties:
        groups:
          type: array
          items:
            $ref: "#/components/schemas/ItemLightGroup"
    ItemLightGroup:
      description: |
        A group of items.
      required:
        - name
        - items
      properties:
        name:
          type: string
        items:
          type: array
          items:
            $ref: "#/components/schemas/ItemLight"
    ItemSearch:
      description: |
        A structure for a search form.
      required:
        - tagsInclude
        - tagsExclude
        - inbox
        - offset
        - limit
      properties:
        tagsInclude:
          type: array
          items:
            type: string
            format: ident
        tagsExclude:
          type: array
          items:
            type: string
            format: ident
        inbox:
          type: boolean
        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.
        direction:
          type: string
          format: direction
          enum:
            - incoming
            - outgoing
        name:
          type: string
          description: |
            Search in item names.
        allNames:
          type: string
          description: |
            Search in item names, correspondents, concerned entities
            and notes.
        corrOrg:
          type: string
          format: ident
        corrPerson:
          type: string
          format: ident
        concPerson:
          type: string
          format: ident
        concEquip:
          type: string
          format: ident
        dateFrom:
          type: integer
          format: date-time
        dateUntil:
          type: integer
          format: date-time
        dueDateFrom:
          type: integer
          format: date-time
        dueDateUntil:
          type: integer
          format: date-time
    ItemLight:
      description: |
        An item with only a few important properties.
      required:
        - id
        - name
        - state
        - date
        - source
        - fileCount
        - tags
      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"
        concEquip:
          $ref: "#/components/schemas/IdName"
        fileCount:
          type: integer
          format: int32
        tags:
          type: array
          items:
            $ref: "#/components/schemas/Tag"
    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
    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
    AuthResult:
      description: |
        The response to a authentication request.
      required:
        - collective
        - user
        - 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
    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
  parameters:
    id:
      name: id
      in: path
      description: An identifier
      required: true
      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
    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
    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