docspell/modules/restapi/src/main/resources/docspell-openapi.yml

openapi: 3.0.0

info:
  title: Docspell
  version: 0.24.0-SNAPSHOT
  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"
  /admin/fts/reIndexAll:
    post:
      tags: [Full-Text Index, Admin]
      summary: Re-creates the full-text index.
      description: |
        Clears the full-text index and inserts all data from the
        database. This migh take a while to complete. The response
        returns immediately. A task is submitted that will be executed
        by a job executor. Note that this affects all data of all
        collectives.

        This is an admin route, so you need to provide the secret from
        the config file as header `Docspell-Admin-Secret`.        
      security:
        - adminHeader: []
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/fts/reIndex:
    post:
      tags: [Full-Text Index]
      summary: Re-creates the full-text index for the current collective
      description: |
        Clears the full-text index for all data belonging to the
        current collective and inserts the data from the database. The
        response is immediately returned and a task is submitted that
        will be executed by a job executor.        
      responses:
        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/item:
    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 one is required.

        The upload meta data can be used to tell, whether multiple
        files are one item, or if each file should become a single
        item. By default, each file will be a one item.        
      security:
        - authTokenHeader: []
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                meta:
                  $ref: "#/components/schemas/ItemUploadMeta"
                file:
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
        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: [ Integration Endpoint ]
      summary: Check if integration endpoint is available.
      description: |
        Allows to check whether an integration endpoint is enabled for
        a collective. The collective is given by the `id` parameter.
        It returns not found (404) if the endpoint is disabled (either
        globally by an admin or by a specific collective). It returns
        403 (or 401 if http-basic is enabled) if authorization fails.

        The response body is empty (an empty json object).        
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                type: object
        404:
          description: Not Found
        403:
          description: Forbidden
        401:
          description: Unauthorized
    post:
      tags: [ Integration Endpoint ]
      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/integration/checkfile/{id}/{checksum}:
    get:
      tags: [ Integration Endpoint ]
      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 the *collective name*. This route only
        exists, if it is enabled in the configuration file.

        The result shows all items that contains a file with the given
        checksum.        
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
        - $ref: "#/components/parameters/checksum"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CheckFileResult"

  /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}:
    get:
      tags: [ Equipment ]
      summary: Get details about a single equipment.
      description: |
        Loads one equipment by its id.        
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Equipment"

    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/folder:
    get:
      tags: [ Folder ]
      summary: Get a list of folders.
      description: |
        Return a list of folders for the current collective.

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

        It is possible to restrict the results by a substring match of
        the name.        
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/q"
        - $ref: "#/components/parameters/owning"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FolderList"
    post:
      tags: [ Folder ]
      summary: Create a new folder
      description: |
        Create a new folder owned by the current user. If a folder with
        the same name already exists, an error is thrown.        
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewFolder"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdResult"
  /sec/folder/{id}:
    get:
      tags: [ Folder ]
      summary: Get folder details.
      description: |
        Return details about a folder.        
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FolderDetail"
    put:
      tags: [ Folder ]
      summary: Change the name of a folder
      description: |
        Changes the name of a folder. The new name must not exists.        
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewFolder"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    delete:
      tags: [ Folder ]
      summary: Delete a folder by its id.
      description: |
        Deletes a folder.        
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
  /sec/folder/{id}/member/{userId}:
    put:
      tags: [ Folder ]
      summary: Add a member to this folder
      description: |
        Adds a member to this folder (identified by `id`).        
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
        - $ref: "#/components/parameters/userId"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"
    delete:
      tags: [ Folder ]
      summary: Removes a member from this folder.
      description: |
        Removes a member from this folder.        
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
        - $ref: "#/components/parameters/userId"
      responses:
        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 folder they occupy etc.        
      security:
        - authTokenHeader: []
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ItemInsights"
  /sec/collective/tagcloud:
    get:
      tags: [ Collective ]
      summary: Summary of used tags.
      description: |
        Returns all tags and how often each has been applied.        
      security:
        - authTokenHeader: []
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagCloud"

  /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/collective/classifier/startonce:
    post:
      tags: [ Collective ]
      summary: Starts the learn-classifier task
      description: |
        If the collective has classification enabled, this will submit
        the task for learning a classifier from existing data. This
        task is usally run periodically as determined by the
        collective settings.

        The request is empty, settings are used from the collective.        
      security:
        - authTokenHeader: []
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/collective/previews:
    post:
      tags: [ Collective ]
      summary: Starts the generate previews task
      description: |
        Submits a task that re-generates preview images of all
        attachments of the current collective. Each existing preview
        image will be replaced.

        This can be used after changing the `preview` settings.

        If only preview images of selected attachments should be
        regenerated, see the `/sec/attachment/{id}/preview` endpoint.        
      security:
        - authTokenHeader: []
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /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/clientSettings/{clientId}:
    parameters:
      - $ref: "#/components/parameters/clientId"
    get:
      tags: [ Client Settings ]
      summary: Return the current user settings
      description: |
        Returns the settings for the current user. The `clientId` is
        an identifier to a client application. It returns a JSON
        structure. The server doesn't care about the actual data,
        since it is meant to be interpreted by clients.        
      security:
        - authTokenHeader: []
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema: {}
    put:
      tags: [ Client Settings ]
      summary: Update current user settings
      description: |
        Updates (replaces or creates) the current user's settings with
        the given data. The `clientId` is an identifier to a client
        application. The request body is expected to be JSON, the
        structure is not important to the server.

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

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

  /admin/user/resetPassword:
    post:
      tags: [ Collective, Admin ]
      summary: Reset a user password.
      description: |
        Resets a user password to some random string which is returned
        as the result. This is an admin route, so you need to specify
        the secret from the config file via a http header
        `Docspell-Admin-Secret`.        
      security:
        - adminHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResetPassword"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResetPasswordResult"

  /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/SourceTagIn"
      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/SourceTagIn"
      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/convertallpdfs:
    post:
      tags: [ Item ]
      summary: Convert all non-converted pdfs.
      description: |
        Submits a job that will find all pdf files that have not been
        converted and converts them using the ocrmypdf tool (if
        enabled). This tool has been added in version 0.9.0 and so
        older files can be "migrated" this way, or maybe after
        enabling the tool.

        The task finds all files of the current collective and submits
        task for each file to convert. These tasks are submitted with
        a low priority so that normal processing can still proceed.

        The body of the request should be empty.        
      security:
        - authTokenHeader: []
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

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

  /sec/item/searchIndex:
    post:
      tags: [ Item Search ]
      summary: Search for items using full-text search only.
      description: |
        Search for items by only using the full-text search index.

        Unlike the other search routes, this one only asks the
        full-text search index and returns only one group that
        contains the results in the same order as given from the
        index. Most full-text search engines use an ordering that
        reflect the relevance wrt the search term.

        The other search routes always order the results by some
        property (the item date) and thus the relevance ordering is
        destroyed when using the full-text search.        
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemQuery"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ItemLightList"

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

  /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. This will remove all
        existing ones and sets the given tags, such that after this
        returns, the item has exactly the tags as given.        
      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}/taglink:
    post:
      tags: [Item]
      summary: Link existing tags to an item.
      description: |
        Sets all given tags to the item. The tags must exist,
        otherwise they are ignored. The tags may be specified as names
        or ids.        
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StringList"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /sec/item/{id}/tagtoggle:
    post:
      tags: [Item]
      summary: Toggles existing tags to an item.
      description: |
        Toggles all given tags of the item. The tags must exist,
        otherwise they are ignored. The tags may be specified as names
        or ids. Tags are either removed or linked from/to the item,
        depending on whether the item currently is tagged with the
        corresponding tag.        
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StringList"
      responses:
        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}/folder:
    put:
      tags: [ Item ]
      summary: Set a folder for this item.
      description: |
        Updates the folder property for this item to "place" the item
        into a folder. If the request contains an empty object or an
        `id` property of `null`, the item is moved into the "public"
        or "root" folder.        
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OptionalId"
      responses:
        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/{id}/preview:
    head:
      tags: [ Attachment ]
      summary: Get a preview image of an attachment file.
      description: |
        Checks if an image file showing a preview of the item is
        available. If not available, a 404 is returned. The preview is
        currently the an image of the first page of the first
        attachment.        
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        200:
          description: Ok
        404:
          description: NotFound
    get:
      tags: [ Attachment ]
      summary: Get a preview image of an attachment file.
      description: |
        Gets a image file showing a preview of the item. Usually it is
        a small image of the first page of the first attachment. If
        not available, a 404 is returned. However, if the query
        parameter `withFallback` is `true`, a fallback preview image
        is returned. You can also use the `HEAD` method to check for
        existence.        
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
        - $ref: "#/components/parameters/withFallback"
      responses:
        200:
          description: Ok
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary

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


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

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


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

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

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

    put:
      tags:
        - Item (Multi Edit)
      summary: Sets tags to multiple items
      description: |
        Sets the given tags to all given items. If the tag list is
        empty, then all tags are removed from the items.        
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemsAndRefs"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  /sec/items/customfieldremove:
    post:
      tags: [ Item (Multi Edit) ]
      summary: Removes the value for a custom field on multiple items
      description: |
        Removes the value for the given custom field from multiple
        items. The field may be specified by its id or name.        
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/itemId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ItemsAndName"
      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}/preview:
    head:
      tags: [ Attachment ]
      summary: Get a preview image of an attachment file.
      description: |
        Checks if an image file showing a preview of the attachment is
        available. If not available, a 404 is returned.        
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        200:
          description: Ok
        404:
          description: NotFound
    get:
      tags: [ Attachment ]
      summary: Get a preview image of an attachment file.
      description: |
        Gets a image file showing a preview of the attachment. Usually
        it is a small image of the first page of the document.If not
        available, a 404 is returned. However, if the query parameter
        `withFallback` is `true`, a fallback preview image is
        returned. You can also use the `HEAD` method to check for
        existence.        
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
        - $ref: "#/components/parameters/withFallback"
      responses:
        200:
          description: Ok
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
    post:
      tags: [ Attachment ]
      summary: (Re)generate a preview image.
      description: |
        Submits a task that generates a preview image for this
        attachment. The existing preview will be replaced.        
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

  /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/attachments/delete:
    post:
      tags:
        - Attachment (Multi Edit)
      summary: Delete multiple attachments.
      description: |
        Given a list of attachment ids, deletes all of them.        
      security:
        - authTokenHeader: [ ]
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IdList"
      responses:
        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/queue/{id}/priority:
    post:
      tags: [ Job Queue ]
      summary: Change the priority of a waiting job.
      description: |
        A waiting job can change its priority. If the job is not in
        state waiting, this operation fails.        
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/id"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JobPriority"
      responses:
        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"

  /sec/customfield:
    get:
      tags: [ Custom Fields ]
      summary: Get all defined custom fields.
      description: |
        Get all custom fields defined for the current collective.        
      security:
        - authTokenHeader: []
      parameters:
        - $ref: "#/components/parameters/q"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomFieldList"
    post:
      tags: [ Custom Fields ]
      summary: Create a new custom field
      description: |
        Creates a new custom field.        
      security:
        - authTokenHeader: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewCustomField"
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BasicResult"

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

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


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

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

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

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


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

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

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

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

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

    JobPriority:
      description: |
        Transfer the priority of a job.        
      required:
        - priority
      properties:
        priority:
          type: string
          format: priority
          enum:
            - high
            - low
    IdList:
      description:
        A list of identifiers.
      required:
        - ids
      properties:
        ids:
          type: array
          items:
            type: string
            format: ident
    StringList:
      description: |
        A simple list of strings.        
      required:
        - items
      properties:
        items:
          type: array
          items:
            type: string
    FolderList:
      description: |
        A list of folders with their member counts.        
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/FolderItem"
    FolderItem:
      description: |
        An item in a folder list.        
      required:
        - id
        - name
        - owner
        - created
        - isMember
        - memberCount
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        owner:
          $ref: "#/components/schemas/IdName"
        created:
          type: integer
          format: date-time
        isMember:
          type: boolean
        memberCount:
          type: integer
          format: int32
    NewFolder:
      description: |
        Data required to create a new folder.        
      required:
        - name
      properties:
        name:
          type: string
    FolderDetail:
      description: |
        Details about a folder.        
      required:
        - id
        - name
        - owner
        - created
        - isMember
        - memberCount
        - members
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        owner:
          $ref: "#/components/schemas/IdName"
        created:
          type: integer
          format: date-time
        isMember:
          type: boolean
        memberCount:
          type: integer
          format: int32
        members:
          type: array
          items:
            $ref: "#/components/schemas/IdName"
    ItemQuery:
      description: |
        Query description for a search. Is used for fulltext-only
        searches and combined searches.        
      required:
        - query
      properties:
        offset:
          type: integer
          format: int32
        limit:
          type: integer
          format: int32
          description: |
            The maximum number of results to return. Note that this
            limit is a soft limit, there is some hard limit on the
            server, too.            
        withDetails:
          type: boolean
          default: false
        query:
          type: string
          description: |
            A query searching the contents of documents.            
    MoveAttachment:
      description: |
        Data to move an attachment to another position.        
      required:
        - source
        - target
      properties:
        source:
          type: string
          format: ident
        target:
          type: string
          format: ident
    ScanMailboxSettingsList:
      description: |
        A list of scan-mailbox tasks.        
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/ScanMailboxSettings"
    ScanMailboxSettings:
      description: |
        Settings for the scan mailbox task.        
      required:
        - id
        - enabled
        - imapConnection
        - schedule
        - folders
        - deleteMail
      properties:
        id:
          type: string
          format: ident
        enabled:
          type: boolean
        summary:
          type: string
        imapConnection:
          type: string
          format: ident
        folders:
          type: array
          items:
            type: string
        schedule:
          type: string
          format: calevent
        receivedSinceHours:
          type: integer
          format: int32
          description: |
            Look only for mails newer than `receivedSinceHours' hours.            
        targetFolder:
          type: string
          description: |
            The folder to move all mails into that have been
            successfully submitted to docspell.            
        deleteMail:
          type: boolean
          description: |
            Whether to delete all successfully imported mails. This
            only applies, if `targetFolder' is not set.            
        direction:
          type: string
          format: direction
          description: |
            The direction to apply to items resulting from importing
            mails. If not set, the value is guessed based on the from
            and to mail headers and your address book.            
        itemFolder:
          type: string
          format: ident
          description: |
            The folder id that is applied to items resulting from
            importing mails. If the folder id is not valid when the
            task executes, items have no folder set.            
        tags:
          $ref: "#/components/schemas/StringList"
        fileFilter:
          description: |
            A glob to filter attachments to import by file name.            
          type: string
          format: glob
        subjectFilter:
          description: |
            A glob to filter attachments to import by subject.            
          type: string
          format: glob
        language:
          description: |
            The language used for text extraction and analysis when
            processing mails.            
          type: string
          format: language
        postHandleAll:
          type: boolean

    ImapSettingsList:
      description: |
        A list of user email settings.        
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/ImapSettings"
    ImapSettings:
      description: |
        IMAP settings for sending mail.        
      required:
        - name
        - imapHost
        - from
        - sslType
        - ignoreCertificates
        - useOAuth
      properties:
        name:
          type: string
          format: ident
        imapHost:
          type: string
        imapPort:
          type: integer
          format: int32
        imapUser:
          type: string
        imapPassword:
          type: string
          format: password
        sslType:
          type: string
        ignoreCertificates:
          type: boolean
        useOAuth:
          type: boolean
          description: |
            Use the password as an OAuth2 access token with the
            authentication scheme XOAUTH2.            
    CalEventCheckResult:
      description: |
        The result of checking a calendar event string.        
      required:
        - success
        - message
      properties:
        success:
          type: boolean
        message:
          type: string
        event:
          type: string
          format: calevent
        next:
          type: array
          items:
            type: integer
            format: date-time
    CalEventCheck:
      description: |
        A calendar event.        
      required:
        - event
      properties:
        event:
          type: string
    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
        summary:
          type: string
        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
        - cc
        - bcc
        - subject
        - body
        - addAllAttachments
        - attachmentIds
      properties:
        recipients:
          type: array
          items:
            type: string
        cc:
          type: array
          items:
            type: string
        bcc:
          type: array
          items:
            type: string
        subject:
          type: string
        body:
          type: string
        addAllAttachments:
          type: boolean
        attachmentIds:
          type: array
          items:
            type: string
            format: ident
    EmailSettingsList:
      description: |
        A list of user email settings.        
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/EmailSettings"
    EmailSettings:
      description: |
        SMTP settings for sending mail.        
      required:
        - name
        - smtpHost
        - from
        - sslType
        - ignoreCertificates
      properties:
        name:
          type: string
          format: ident
        smtpHost:
          type: string
        smtpPort:
          type: integer
          format: int32
        smtpUser:
          type: string
        smtpPassword:
          type: string
          format: password
        from:
          type: string
        replyTo:
          type: string
        sslType:
          type: string
        ignoreCertificates:
          type: boolean
    CheckFileResult:
      description: |
        Results when searching for file checksums.        
      required:
        - exists
        - items
      properties:
        exists:
          type: boolean
        items:
          type: array
          items:
            $ref: "#/components/schemas/BasicItem"
    BasicItem:
      description: |
        Basic properties about an item.        
      required:
        - id
        - name
        - direction
        - state
        - created
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        direction:
          type: string
          format: direction
        state:
          type: string
          format: itemstate
        created:
          type: integer
          format: date-time
        itemDate:
          type: integer
          format: date-time
    GenInvite:
      description: |
        A request to generate a new invitation key.        
      required:
        - password
      properties:
        password:
          type: string
          format: password
    InviteResult:
      description: |
        The result when requesting new invitation keys.        
      required:
        - success
        - message
      properties:
        success:
          type: boolean
        message:
          type: string
        key:
          type: string
          format: ident
    SearchStats:
      description: |
        A summary of search results.        
      required:
        - count
        - tagCloud
        - tagCategoryCloud
        - fieldStats
        - folderStats
      properties:
        count:
          type: integer
          format: int32
        tagCloud:
          $ref: "#/components/schemas/TagCloud"
        tagCategoryCloud:
          $ref: "#/components/schemas/NameCloud"
        fieldStats:
          type: array
          items:
            $ref: "#/components/schemas/FieldStats"
        folderStats:
          type: array
          items:
            $ref: "#/components/schemas/FolderStats"
    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"
    FolderStats:
      description: |
        Count of folder usage.        
      required:
        - id
        - name
        - owner
        - count
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        owner:
          $ref: "#/components/schemas/IdName"
        count:
          type: integer
          format: int32
    FieldStats:
      description: |
        Basic statistics about a custom field.        
      required:
        - id
        - name
        - ftype
        - count
        - avg
        - sum
        - max
        - min
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
          format: ident
        label:
          type: string
        ftype:
          type: string
          format: customfieldtype
          enum:
            - text
            - numeric
            - date
            - bool
            - money
        count:
          type: integer
          format: int32
        sum:
          type: number
          format: double
        avg:
          type: number
          format: double
        max:
          type: number
          format: double
        min:
          type: number
          format: double
    TagCloud:
      description: |
        A tag "cloud"        
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/TagCount"
    TagCount:
      description: |
        Structure for counting tags.        
      required:
        - tag
        - count
      properties:
        tag:
          $ref: "#/components/schemas/Tag"
        count:
          type: integer
          format: int32

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

    AttachmentMeta:
      description: |
        Extracted meta data of an attachment.        
      required:
        - content
        - labels
        - proposals
      properties:
        content:
          type: string
        labels:
          type: array
          items:
            $ref: "#/components/schemas/Label"
        proposals:
          $ref: "#/components/schemas/ItemProposals"
    ItemProposals:
      description: |
        Metadata that has been suggested to an item.        
      required:
        - corrOrg
        - corrPerson
        - concPerson
        - concEquipment
        - itemDate
        - dueDate
      properties:
        corrOrg:
          type: array
          items:
            $ref: "#/components/schemas/IdName"
        corrPerson:
          type: array
          items:
            $ref: "#/components/schemas/IdName"
        concPerson:
          type: array
          items:
            $ref: "#/components/schemas/IdName"
        concEquipment:
          type: array
          items:
            $ref: "#/components/schemas/IdName"
        itemDate:
          type: array
          items:
            type: integer
            format: date-time
        dueDate:
          type: array
          items:
            type: integer
            format: date-time
    Label:
      description: |
        Extracted label.        
      required:
        - labelType
        - label
        - beginPos
        - endPos
      properties:
        labelType:
          type: string
          format: nertag
        label:
          type: string
        beginPos:
          type: integer
          format: int32
        endPos:
          type: integer
          format: int32
    OptionalDate:
      description: |
        Structure for sending an optional datetime value.        
      properties:
        date:
          type: integer
          format: date-time
    OptionalText:
      description: |
        Structure for sending optional text.        
      properties:
        text:
          type: string
    OptionalId:
      description: |
        Structure for sending optional ids.        
      properties:
        id:
          type: string
          format: ident
    DirectionValue:
      description: |
        A direction.        
      required:
        - direction
      properties:
        direction:
          type: string
          format: direction
    ItemDetail:
      description: |
        Detailed information about an item.        
      required:
        - id
        - direction
        - name
        - source
        - state
        - created
        - updated
        - attachments
        - sources
        - archives
        - tags
        - customfields
      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"
        folder:
          $ref: "#/components/schemas/IdName"
        dueDate:
          type: integer
          format: date-time
        notes:
          type: string
        attachments:
          type: array
          items:
            $ref: "#/components/schemas/Attachment"
        sources:
          type: array
          items:
            $ref: "#/components/schemas/AttachmentSource"
        archives:
          type: array
          items:
            $ref: "#/components/schemas/AttachmentSource"
        tags:
          type: array
          items:
            $ref: "#/components/schemas/Tag"
        customfields:
          type: array
          items:
            $ref: "#/components/schemas/ItemFieldValue"
    Attachment:
      description: |
        Information about an attachment to an item.        
      required:
        - id
        - size
        - contentType
        - converted
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        size:
          type: integer
          format: int64
        contentType:
          type: string
          format: mimetype
        converted:
          type: boolean
    AttachmentSource:
      description: |
        The source or original file of an attachment.        
      required:
        - id
        - size
        - contentType
      properties:
        id:
          type: string
          format: ident
          description: |
            The id is the attachment id.            
        name:
          type: string
        size:
          type: integer
          format: int64
        contentType:
          type: string
          format: mimetype
    Registration:
      description: |
        Data for registering a new account.        
      required:
        - collectiveName
        - login
        - password
      properties:
        collectiveName:
          type: string
          format: ident
        login:
          type: string
          format: ident
        password:
          type: string
          format: password
        invite:
          type: string
          format: ident
    JobQueueState:
      description: |
        Contains all information about the job queue.        
      required:
        - progress
        - completed
        - queued
      properties:
        progress:
          type: array
          items:
            $ref: "#/components/schemas/JobDetail"
        completed:
          type: array
          items:
            $ref: "#/components/schemas/JobDetail"
        queued:
          type: array
          items:
            $ref: "#/components/schemas/JobDetail"
    JobDetail:
      description: |
        Details about a job.        
      required:
        - id
        - name
        - submitted
        - priority
        - state
        - retries
        - logs
        - progress
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        submitted:
          description: DateTime
          type: integer
          format: date-time
        priority:
          type: string
          format: priority
          enum:
            - high
            - low
        state:
          type: string
          format: jobstate
          enum:
            - waiting
            - scheduled
            - running
            - stuck
            - failed
            - canceled
            - success
        retries:
          type: integer
          format: int32
        logs:
          type: array
          items:
            $ref: "#/components/schemas/JobLogEvent"
        progress:
          type: integer
          format: int32
        worker:
          type: string
          format: ident
        started:
          description: DateTime
          type: integer
          format: date-time
        finished:
          type: integer
          format: date-time
    JobLogEvent:
      description: |
        A log output line.        
      required:
        - time
        - level
        - message
      properties:
        time:
          description: DateTime
          type: integer
          format: date-time
        level:
          type: string
          format: loglevel
        message:
          type: string
    PasswordChange:
      description: |
        Change the password, by given the old and new one.        
      required:
        - currentPassword
        - newPassword
      properties:
        currentPassword:
          type: string
          format: password
        newPassword:
          type: string
          format: password
    UserList:
      description: |
        A list of users.        
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/User"
    User:
      description: |
        A user of a collective.        
      required:
        - id
        - login
        - state
        - loginCount
        - created
      properties:
        id:
          type: string
          format: ident
        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, if there is some
        specified, you have to specifiy whether the corresponding
        files should become one single item or if an item is created
        for each file.

        A direction can be given, `Incoming` is used if not specified.

        A folderId can be given, the item is placed into this folder
        after creation.

        The `fileFilter` is an optional glob for filtering files to
        import. Only applicable if archive files are uploaded. It
        applies to all of them. For example, to only import pdf files
        when uploading e-mails, use `*.pdf`. If the pattern doesn't
        contain a slash `/`, then it is applied to all file names.
        Otherwise it is applied to the complete path in the archive
        (useful for zip files). Note that the archive file itself is
        always saved completely, too.

        The `tags` input allows to provide tags that should be applied
        to the item being created. This only works if the tags already
        exist. It is possible to specify their ids or names.

        The `language` of the document may be specified, otherwise the
        one from settings is used.        
      required:
        - multiple
      properties:
        multiple:
          type: boolean
          default: true
        direction:
          type: string
          format: direction
        folder:
          type: string
          format: ident
        skipDuplicates:
          type: boolean
          default: false
        tags:
          $ref: "#/components/schemas/StringList"
        fileFilter:
          type: string
          format: glob
        language:
          type: string
          format: language

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

    CollectiveSettings:
      description: |
        Settings for a collective.        
      required:
        - language
        - integrationEnabled
        - classifier
      properties:
        language:
          type: string
          format: language
        integrationEnabled:
          type: boolean
          description: |
            Whether the collective has the integration endpoint
            enabled.            
        classifier:
          $ref: "#/components/schemas/ClassifierSetting"

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

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

    Source:
      description: |
        Data about a Source. A source defines the endpoint where
        docspell receives files.        
      required:
        - id
        - abbrev
        - counter
        - enabled
        - priority
        - created
      properties:
        id:
          type: string
          format: ident
        abbrev:
          type: string
        description:
          type: string
        counter:
          type: integer
          format: int32
        enabled:
          type: boolean
        priority:
          type: string
          format: priority
          enum:
            - high
            - low
        folder:
          type: string
          format: ident
        fileFilter:
          type: string
          format: glob
        language:
          type: string
          format: language
        created:
          description: DateTime
          type: integer
          format: date-time
    SourceTagIn:
      description: |
        A source and optional tags (ids or names) for updating/adding.        
      required:
        - source
        - tags
      properties:
        source:
          $ref: "#/components/schemas/Source"
        tags:
          type: array
          items:
            type: string
    SourceAndTags:
      description: |
        A source and optional tags.        
      required:
        - source
        - tags
      properties:
        source:
          $ref: "#/components/schemas/Source"
        tags:
          $ref: "#/components/schemas/TagList"

    EquipmentList:
      description: |
        A list of equipments.        
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Equipment"
    Equipment:
      description: |
        Some "thing" that occurs in documents.        
      required:
        - id
        - name
        - created
        - use
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        created:
          description: DateTime
          type: integer
          format: date-time
        notes:
          type: string
        use:
          type: string
          format: equipmentuse
          enum:
            - concerning
            - disabled
    ReferenceList:
      description:
        Listing of entities with their id and a name.
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/IdName"
    Person:
      description: |
        Basic information about a person.        
      required:
        - id
        - name
        - address
        - contacts
        - created
        - use
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        organization:
          $ref: "#/components/schemas/IdName"
        address:
          $ref: "#/components/schemas/Address"
        contacts:
          type: array
          items:
            $ref: "#/components/schemas/Contact"
        notes:
          type: string
        use:
          type: string
          format: personuse
          enum:
            - concerning
            - correspondent
            - both
            - disabled
          description: |
            Whether this person should be used to create suggestions
            for the "concerning person", "correspondent" or both.            
        created:
          description: DateTime
          type: integer
          format: date-time
    PersonList:
      description: |
        A list of persons.        
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Person"
    Organization:
      description: |
        An organisation.        
      required:
        - id
        - name
        - address
        - contacts
        - created
        - use
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        address:
          $ref: "#/components/schemas/Address"
        contacts:
          type: array
          items:
            $ref: "#/components/schemas/Contact"
        notes:
          type: string
        created:
          description: DateTime
          type: integer
          format: date-time
        shortName:
          type: string
        use:
          type: string
          format: orguse
          enum:
            - correspondent
            - disabled
    OrganizationList:
      description: |
        A list of full organization values.        
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Organization"
    Address:
      description: |
        Postal address information.        
      required:
        - street
        - zip
        - city
        - country
      properties:
        street:
          type: string
        zip:
          type: string
        city:
          type: string
        country:
          type: string
    ContactList:
      description: |
        A list of contacts.        
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/Contact"
    Contact:
      description: |
        Contact information.        
      required:
        - id
        - value
        - kind
      properties:
        id:
          type: string
          format: ident
        value:
          type: string
        kind:
          type: string
          format: contactkind
          enum:
            - phone
            - mobile
            - website
            - fax
            - docspell
            - email
    ItemLightList:
      description: |
        A list of item details.        
      required:
        - groups
      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"
    ItemLight:
      description: |
        An item with only a few important properties.        
      required:
        - id
        - name
        - state
        - date
        - source
        - 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"
        concEquipment:
          $ref: "#/components/schemas/IdName"
        folder:
          $ref: "#/components/schemas/IdName"
        attachments:
          type: array
          items:
            $ref: "#/components/schemas/AttachmentLight"
        tags:
          type: array
          items:
            $ref: "#/components/schemas/Tag"
        customfields:
          type: array
          items:
            $ref: "#/components/schemas/ItemFieldValue"
        notes:
          description: |
            Some prefix of the item notes.            
          type: string
        highlighting:
          description: |
            Optional contextual information of a search query. Each
            item refers to some field where a search match was found
            (e.g. the name of an attachment or the item notes) and a
            list of lines giving surrounding context of the macth.            
          type: array
          items:
            $ref: "#/components/schemas/HighlightEntry"
    AttachmentLight:
      description: |
        Some little details about an attachment.        
      required:
        - id
        - position
      properties:
        id:
          type: string
          format: ident
        position:
          type: integer
          format: int32
        name:
          type: string
        pageCount:
          type: integer
          format: int32
    HighlightEntry:
      description: |
        Highlighting information for a single field (maybe attachment
        name or item notes).        
      required:
        - name
        - lines
      properties:
        name:
          type: string
        lines:
          type: array
          items:
            type: string
    IdName:
      description: |
        The identifier and a human readable name of some entity.        
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
    BasicResult:
      description: |
        Some basic result of an operation.        
      required:
        - success
        - message
      properties:
        success:
          type: boolean
        message:
          type: string
    IdResult:
      description: |
        Some basic result of an operation with an ID as payload. If
        success if `false` the id is not usable.        
      required:
        - success
        - message
        - id
      properties:
        success:
          type: boolean
        message:
          type: string
        id:
          type: string
          format: ident
    Tag:
      description: |
        A tag used to annotate items. A tag may have a category which
        groups tags together.        
      required:
        - id
        - name
        - created
      properties:
        id:
          type: string
          format: ident
        name:
          type: string
        category:
          type: string
        created:
          type: integer
          format: date-time
    TagList:
      description: |
        A list of tags.        
      required:
        - count
        - items
      properties:
        count:
          type: integer
          format: int32
        items:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
    UserPass:
      description: |
        Account name and password.        
      required:
        - account
        - password
      properties:
        account:
          type: string
        password:
          type: string
        rememberMe:
          type: boolean
    AuthResult:
      description: |
        The response to a authentication request.        
      required:
        - collective
        - user
        - 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
    adminHeader:
      type: apiKey
      in: header
      name: Docspell-Admin-Secret
  parameters:
    id:
      name: id
      in: path
      description: An identifier
      required: true
      schema:
        type: string
    userId:
      name: userId
      in: path
      description: An identifier
      required: true
      schema:
        type: string
    itemId:
      name: itemId
      in: path
      description: An identifier for an item
      required: true
      schema:
        type: string
    full:
      name: full
      in: query
      description: Whether to list full data or just name and id.
      required: false
      schema:
        type: boolean
    owning:
      name: full
      in: query
      description: Whether to get owning folders
      required: false
      schema:
        type: boolean
    checksum:
      name: checksum
      in: path
      description: A SHA-256 checksum
      required: true
      schema:
        type: string
    q:
      name: q
      in: query
      description: A query string.
      required: false
      schema:
        type: string
    limit:
      name: limit
      in: query
      description: A limit for a search query
      schema:
        type: integer
        format: int32
    offset:
      name: offset
      in: query
      description: A offset into the results for a search query
      schema:
        type: integer
        format: int32
    withDetails:
      name: withDetails
      in: query
      description: Whether to return details to each item.
      schema:
        type: boolean
    name:
      name: name
      in: path
      description: An e-mail connection name
      required: true
      schema:
        type: string
    mailId:
      name: mailId
      in: path
      description: The id of a sent mail.
      required: true
      schema:
        type: string
    contactKind:
      name: kind
      in: query
      required: false
      description: |
        One of the available contact kinds.        
      schema:
        type: string
    withFallback:
      name: withFallback
      in: query
      description: Whether to provide a fallback or not.
      required: false
      schema:
        type: boolean
    clientId:
      name: clientId
      in: path
      required: true
      description: |
        some identifier for a client application        
      schema:
        type: string