openapi: 3.0.1
info:
  title: SEAL Operator REST API
  description: This is the REST API of the SEAL Operator system. It is used by the
    graphical front-end and may also be used for integration purposes. The API can be
    used to access the SERVICES installed with SEAL Operator in order to manage
    DOCUMENTS in REPOSITORIES, organize documents in LISTS and work with the
    TASKS provided by the services. The API requires OAuth2/OIDC authentication.
    See the SEAL Operator Integrators Guide for details.
  contact:
    name: SEAL Systems AG, Röttenbach, Germany
    url: https://sealsystems.de/
    email: sales@sealsystems.de
  license:
    name: Requires SEAL Operator License (Proprietary)
    url: https://sealsystems.de/products/operator
  version: "0.5"
servers:
- url: https://localhost:3008/v1
paths:
  /services:
    get:
      tags:
      - Services
      summary: Get list of available services
      description: |
        A GET call to this route will return a list of active services
        currently available through the API.
      responses:
        200:
          description: OK, collection of services is returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Service'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the service list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include the error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
  /services/{sid}:
    get:
      tags:
      - Services
      summary: Retrieve service metadata
      description: |
        A GET call to this route will return metadata of the service.
      parameters:
      - name: sid
        in: path
        description: ID of the service.
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK, service metadata is returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the service metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: The requested service was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
  /repo/inactives:
    post:
      tags:
      - Repositories
      summary: Test for documents not actively used in a task
      description: |
        Filters list of document IDs and returns only documents currently not used in a task in status processing.
      requestBody:
        description: list of document IDs
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
                example: ce4a9e70-62b5-4f2c-976e-4632a99b0fbd
        required: true
      responses:
        200:
          description: OK, response contains list of inactive documents
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  example: ce4a9e70-62b5-4f2c-976e-4632a99b0fbd
        400:
          description: Invalid data type in POST request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN

  /services/{sid}/repo:
    get:
      tags:
      - Repositories
      summary: Access the document repository within a service
      description: |
        Some services (not all) expose access to documents.
        All documents available through a service are accessible via the 'repo'
        route. This route provides access to the repository root collection,
        containing documents and/or child collections. Use metadata property
        names and regular expressions in URL query string to search for entries
        (documents or collections) and the offset and limit parameters to control
        the number of results returned.
      parameters:
      - name: sid
        in: path
        description: ID of the repository.
        required: true
        schema:
          type: string
      - name: offset
        in: query
        description: Index of first result to return.
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        description: Number of results to return. Maximum is 500.
        schema:
          type: integer
          default: 50
      - name: sort
        in: query
        description: |
          Sort query results. Comma-separated list of property names, prefixed with '-'
          for descending sort order. Example: 'sort=date,-name'
        schema:
          type: string
      - name: scope
        in: query
        description: |
          Set the scope when searching for documents. Possible values are `root`
          and `all`, default is `all`.
        schema:
          type: string
          default: all
      - name: embed
        in: query
        description: |
          Include sub-resource or sub-collection data in response.
          "permissions": include access rights records for each entry.
          "thumb": include base64-encoded thumbnail image for each entry, e. g.
          ```
          "embedded": {
            "content-type": "image/png"
            "thumb": "A9cX0..."
          }
          ```
        schema:
          type: string
      responses:
        200:
          description: OK, collection of entries is returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RepoEntry'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: Service not found or no repository available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
    post:
      tags:
      - Repositories
      summary: Create new entry in the root collection of the repository.
      description: |
        Creates a new record in the current repository, inside the
        root collection, and assigns the posted metadata.
      parameters:
      - name: sid
        in: path
        description: ID of the service.
        required: true
        schema:
          type: string
      - name: x-owner
        in: header
        description: |
          User that should own the new entry. The user creating the entry
          becomes its creator, adding an owner is optional. Owner and
          creator rights can be managed through roles & rights.
          User identifiers can be anything, e. g. SAMaccountname or UPN.
          Must be matched with a claim from the JWT token in order to
          work in the user interface.
        required: false
        schema:
          type: string
      requestBody:
        description: Metadata of the entry to be created
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BaseRepoEntry'
        required: true
      responses:
        200:
          description: OK, entry created. Entry metadata returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepoEntry'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: Service does not exist or has no repository
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be created. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
  /services/{sid}/repo/command:
    post:
      tags:
      - Repositories
      summary: Launch a repository command
      description: |
        Launches a command in the given repository. Returns a JSON object
        containing a command ID for tracking status of asynchronous commands.
      parameters:
      - name: sid
        in: path
        description: ID of the service.
        required: true
        schema:
          type: string
      requestBody:
        description: |
          The command entry and its parameter to be created. Currently supported
           commands are `copy` and `move`. The parameters for both commands:
          ```json
          {
            "action": "copy|move",
            "parameter": {
              "source": "source href",
              "parent": "uuid of target parent"
            }
          }
          ```
          The source may be a remote repository in later implementations, so an `href` is needed here.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Command'
        required: true
      responses:
        200:
          description: OK, command started. Command ID will be returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandStatus'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist, has no repository or repository does not
            support commands.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be created. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN

  /services/{sid}/repo/command/{cid}:
    get:
      tags:
      - Repositories
      summary: Retrieve a command's status
      description: |
        Returns a JSON object containing the status of the command. Command resources
        are automatically deleted after a final state (success or failure) was delivered
        once to the client or it is expired.
      parameters:
      - name: sid
        in: path
        description: ID of the service.
        required: true
        schema:
          type: string
      - name: cid
        in: path
        description: ID of the command.
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK, status of command resource is returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommandStatus'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist, has no repository or the given command ID
            was not recognized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN

  /services/{sid}/repo/{uuid}:
    get:
      tags:
      - Repositories
      summary: Retrieve metadata of a repository entry (document or collection).
      description: |
        Given a 'uuid' parameter, this route retrieves an entry's
        metadata. The entry may be either a document or a collection.
      parameters:
      - name: sid
        in: path
        description: ID of the service.
        required: true
        schema:
          type: string
      - name: uuid
        in: path
        description: ID of the repository entry
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK, entry metadata is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepoEntry'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist, has no repository or the given uuid was not
            found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN

    put:
      tags:
      - Repositories
      summary: Replace repository entry metadata
      description: |
        Completely replace the metadata record of the given entry.
        Only record metadata can be replaced; internal auto-generated metadata
        (links, embedded), if given, are ignored.
      parameters:
      - name: sid
        in: path
        description: ID of the repository.
        required: true
        schema:
          type: string
      - name: uuid
        in: path
        description: UUID of the entry
        required: true
        schema:
          type: string
      requestBody:
        description: |
          New entry metadata. Note that changing the entry type is not
          possible by updating metadata.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BaseRepoEntry'
        required: true
      responses:
        200:
          description: OK, entry metadata replaced, new metadata returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepoEntry'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist, has no repository or the given uuid was not
            found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN

    post:
      tags:
      - Repositories
      summary: Create a new entry in a collection
      description: |
        If the entry under the given UUID is a collection, then a POST request
        to this route will create a new entry in the collection. Whether the
        created entry will be a document or another collection depends on the
        metadata enclosed in the request body. See RepoEntry data model.
      parameters:
      - name: sid
        in: path
        description: ID of the service.
        required: true
        schema:
          type: string
      - name: uuid
        in: path
        description: UUID of the collection in which to create a new entry
        required: true
        schema:
          type: string
      - name: x-owner
        in: header
        description: |
          User that should own the new entry. The user creating the entry
          becomes its creator, adding an owner is optional. Owner and
          creator rights can be managed through roles & rights.
          User identifiers can be anything, e. g. SAMaccountname or UPN.
          Must be matched with a claim from the JWT token in order to
          work in the user interface.
        required: false
        schema:
          type: string
      requestBody:
        description: Metadata of the entry to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BaseRepoEntry'
        required: true
      responses:
        200:
          description: OK, new entry created, metadata of the entry returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepoEntry'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist, has no repository or the given UUID was not
            found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        405:
          description: |
            Method not allowed. The entry under 'uuid' is not a collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN

    delete:
      tags:
      - Repositories
      summary: Delete the entry
      description: |
        Removes the current entry from the repository. This will not only
        remove the reference within SEAL Operator, but the actual record and content
        in the target system.
      parameters:
      - name: sid
        in: path
        description: ID of the service.
        required: true
        schema:
          type: string
      - name: uuid
        in: path
        description: UUID of the entry to delete
        required: true
        schema:
          type: string
      - name: force
        in: query
        description: Delete document even if it is still in use by one or more tasks.
        schema:
          type: boolean
      responses:
        204:
          description: OK, entry was deleted.
          content: {}
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: Forbidden (deletion refused by target system)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist, has no repository or the given uuid was not
            found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be deleted. Returns collection of tasks
            using the current document.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN

    patch:
      tags:
      - Repositories
      summary: Update repository entry metadata (partial)
      description: |
        Update the given entry's metadata. Only data given with the patch will
        be changed/added, no existing entries removed. Internal auto-generated
        metadata (links, embedded), if given, are ignored.
      parameters:
      - name: sid
        in: path
        description: ID of the service.
        required: true
        schema:
          type: string
      - name: uuid
        in: path
        description: UUID of the entry
        required: true
        schema:
          type: string
      requestBody:
        description: New entry metadata.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BaseRepoEntry'
        required: true
      responses:
        200:
          description: OK, entry metadata replaced, new metadata returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepoEntry'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist, has no repository or the given uuid was not
            found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error.  Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN

  /services/{sid}/repo/{uuid}/children:
    get:
      tags:
      - Repositories
      summary: Access children of a collection
      description: |
        Some services (not all) expose access to documents.
        All documents available through a service are accessible via the 'repo'
        route. This route provides access to the children of a collection, containing
        documents and/or collections. Use metadata property names and regular
        expressions in URL query string to search for entries (documents or
        collections), offset and limit parameters to control the number of
        results returned.
      parameters:
      - name: sid
        in: path
        description: ID of the repository.
        required: true
        schema:
          type: string
      - name: uuid
        in: path
        description: UUID of the parent collection
        required: true
        schema:
          type: string
      - name: offset
        in: query
        description: Index of first result to return.
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        description: Number of results to return. Maximum is 500.
        schema:
          type: integer
          default: 50
      - name: sort
        in: query
        description: |
          Sort query results. Comma-separated list of property names, prefixed with '-'
          for descending sort order. Example: 'sort=date,-name'
        schema:
          type: string
      - name: embed
        in: query
        description: |
          Include sub-resource or sub-collection data in response.
          "permissions": include access rights records for each entry.
          "icon": include icon-font and value for each entry, e. g.
          ```
          "embedded": {
            "icon": "material:play"
          }
          ```
          "thumb": include base64 encoded thumbnail image for each entry, e. g.
          ```
          "embedded": {
            "content-type": "image/png"
            "thumb": "A9cX0..."
          }
          ```
        schema:
          type: string
      responses:
        200:
          description: OK, collection of entries is returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RepoEntry'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Not found. Either no entry was found under the given 'uuid', or the
            entry is not a collection, or the collection has no children (yet).
            See error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error.  Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN

  /services/{sid}/repo/{uuid}/content:
    get:
      tags:
      - Repositories
      summary: Retrieve document binary content
      description: |
        If the entry under 'uuid' is a document, then this route provides access
        to the binary content (i. e. the actual file).
      parameters:
      - name: sid
        in: path
        description: ID of the service.
        required: true
        schema:
          type: string
      - name: uuid
        in: path
        description: UUID of the document
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK, content is returned.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to read the binary content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Not found. Either no entry was found under the given 'uuid', or the
            entry is not a document, or the document has no binary content (yet).
            See error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN

    put:
      tags:
      - Repositories
      summary: Create or update document binary content
      description: |
        Upload binary content of a document. Create if none exists, or
        replace existent file. Uploading binary content to collection type
        entries is not supported.
      parameters:
      - name: sid
        in: path
        description: ID of the service.
        required: true
        schema:
          type: string
      - name: uuid
        in: path
        description: UUID of the document
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
              description: binary data for upload
        required: true
      responses:
        204:
          description: OK, content was updated.
          content: {}
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to update the binary content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist, has no repository, the given uuid was not
            found or entry is not a document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        406:
          description: |
            Method not allowed. The entry under 'uuid' is not a document, or the
            document does not support changing of the bianry content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN

    delete:
      tags:
      - Repositories
      summary: Delete document binary content
      description: |
        Deletes the binary content of a document, leaving metadata only.
        Note that some repositories will not allow this operation. To delete
        binary content from such repositories, you will need to delete the entire
        document. Deleting binary content is not supported by collection type
        entries.
      parameters:
      - name: sid
        in: path
        description: ID of the service.
        required: true
        schema:
          type: string
      - name: uuid
        in: path
        description: UUID of the document
        required: true
        schema:
          type: string
      responses:
        204:
          description: OK, content was deleted.
          content: {}
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to delete the binary content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist, has no repository, the given UUID was not
            found or entry has no content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        405:
          description: |
            Method not allowed. Either the entry under 'uuid' is not a document,
            or it does not support deleting of the binary content. See error
            message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be deleted. Returns collection of tasks
            using the current document.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN

  /services/{sid}/repo/{uuid}/preview:
    get:
      tags:
      - Repositories
      summary: Retrieve preview of a document's binary content
      description: |
        If the entry under 'uuid' is a document, then this route provides access
        to the preview content. Collection type entries do not support the
        preview option.
      parameters:
      - name: sid
        in: path
        description: ID of the service.
        required: true
        schema:
          type: string
      - name: uuid
        in: path
        description: UUID of the document
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK, preview is returned.
          content: {}
        401:
          description: Unauthorized (Auth token invalid)
          content:
            image/jpeg:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to read the binary content.
          content:
            image/jpeg:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Not found. Either no entry was found under the given 'uuid', or the
            entry is not a document, or the document has no binary content, or the
            preview is not created (so far). See error message for details.
          content:
            image/jpeg:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            image/jpeg:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            image/jpeg:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN

  /tasks:
    get:
      tags:
      - Tasks
      summary: Retrieve meta-collection of all tasks managed by all services.
      description: |
        This route provides access to the root collection of known tasks for all services supporting tasks.
        Use property names and regular expressions in URL query string to search for tasks,
        e. g. 'metadata.creationDay' to search for the property 'creationDay' stored in the task metadata.
        Use the 'embed' parameter to include information about instances and sub-ressources.
        Use the 'inputDocument' parameter to search for a task containing a given document, and use 'inlineCount'
        to get the number of found tasks.
      parameters:
      - name: inputDocument
        in: query
        description: A document UUID to look for in the input lists of
          all tasks.
        schema:
          type: string
      - name: embed
        in: query
        description: |
          Information about sub-collections and/or sub-resources to include
          in the response.
          - "metadata": include task metadata.
          - "input": include input lists metadata
          - "inputlist": include whole input lists
          - "output": include output lists metadata
          - "cstats": connector specific job IDs and states
        schema:
          type: string
      - name: inlineCount
        in: query
        description: |
          Return a JSON object containing the number of tasks found, according
          to the query parameters, instead of an array with tasks.
        schema:
          type: boolean
      responses:
        200:
          description: |
            OK, collection of tasks or count is returned. Example for count:
            ```
            {
              count: 0
            }
            ```
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: No (matching) tasks found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
  /services/{sid}/tasks:
    get:
      tags:
      - Tasks
      summary: Access collection of tasks managed by the service.
      description: |
        This route provides access to the root collection of known tasks for
        the current service.
        Use property names and regular expressions in URL query string to search
        for tasks, e. g. 'metadata.creationDay' to search for the property 'creationDay'
        stored in the task metadata.
        Use the offset and limit parameters to control the number of
        results returned.
        Use the 'embed' parameter to include information about instances and
        sub-resources.
      parameters:
      - name: sid
        in: path
        description: ID of the service managing the tasks
        required: true
        schema:
          type: string
      - name: offset
        in: query
        description: Index of first result to return.
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        description: Number of results to return. Maximum is 500.
        schema:
          type: integer
          default: 50
      - name: sort
        in: query
        description: |
          Sort query results. Comma-separated list of property names, prefixed
          with '-' for descending sort order. Example: 'sort=date,-name'
        schema:
          type: string
      - name: inputDocument
        in: query
        description: A document UUID to search for in the input lists of
          all tasks.
        schema:
          type: string
      - name: embed
        in: query
        description: |
          Information about sub-collections and/or sub-resources to include
          in the response.
          - "metadata": include task metadata.
          - "input": include input list metadata
          - "inputlist": include whole input list
          - "output": include output list metadata
          - "cstats": connector specific job IDs and states
        schema:
          type: string
      - name: inlineCount
        in: query
        description: |
          Return a JSON object containing the number of tasks found, according
          to the query parameters, instead of an array with tasks.
        schema:
          type: boolean
      responses:
        200:
          description: |
            OK, collection of tasks or count is returned. Example for count:
            ```
            {
              count: 0
            }
            ```
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist or does not provide tasks, or no (matching)
            tasks were found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
    post:
      tags:
      - Tasks
      summary: Create a new task
      description: |
        Adds a new task to the collection, given metadata is assigned.
        If JSON data is given in the body, the tasks is created with the given
        metadata assigned, the tasks input list must be filled after creation.
        Otherwise, the task is created with default metadata, and its input list
        is populated with the RList or CSV content given in the request body.
      parameters:
      - name: sid
        in: path
        description: ID of the service managing the new task
        required: true
        schema:
          type: string
      - name: x-owner
        in: header
        description: |
          User that should own the new task. The user creating the task
          becomes its creator, adding an owner is optional. Owner and
          creator rights can be managed through roles & rights.
          User identifiers can be anything, e. g. SAMaccountname or UPN.
          Must be matched with a claim from the JWT token in order to
          work in the user interface.
        required: false
        schema:
          type: string
      requestBody:
        description: Task metadata
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Task'
          application/rli:
            schema:
              type: string
              description: Repro list text document containing metadata
              example: |
                [JOBINFO]
                PRINTJOB_NAME "Ansegisel"

                [RECEIVER]
                default
                Pippin

                [Pippin]
                status "der mittlere"
                name "Pippin"

                [default]
                status "unbekannt"

                [REPRO_LIST_FORMAT]
                FIELD RECEIVER ^0
                FIELD status ^1
                FIELD name ^2

                [REPRO_LIST]
                ^Ansegisel^^Ansguise
                ^Pippin
          text/csv:
            schema:
              type: string
              description: CSV-formatted text document containing metadata
              example: |
                list.name,item.metadata.Color,item.href,item.metadata.name,item.metadata.Printer
                Karl Martell,color,/v1/services/operator-fileupload/repo/1d431501-f5e3-480b-8ad2-bc31a09338f8,Arnulf.ps,HUGO
                Karl Martell,gray,/v1/services/operator-fileupload/repo/1d431501-f5e3-480b-8ad2-bc31a09338f8,Ansegisel.ps,hpm402
                Karl Martell,color,/v1/services/operator-fileupload/repo/1d431501-f5e3-480b-8ad2-bc31a09338f8,Pippin.ps,pdfout
        required: true
      responses:
        200:
          description: OK, task created. Task metadata returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist or does not provide tasks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be created. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
  /services/{sid}/tasks/{tid}:
    get:
      tags:
      - Tasks
      summary: Retrieve metadata of a task.
      description: |
        This route provides access to a Task's root record. The record
        contains taks metadata (such as parameters controlling it), details
        are available via sub-resources and sub-collections.
      parameters:
      - name: sid
        in: path
        description: ID of the service managing the task
        required: true
        schema:
          type: string
      - name: tid
        in: path
        description: ID of the task.
        required: true
        schema:
          type: string
      - name: embed
        in: query
        description: |
          Embed sub-resources in the response.
          - "input": include list of input documents
          - "output": include list of output documents
        schema:
          type: string
      - name: force
        in: query
        description: Force status update from backend system.
        schema:
          type: boolean
      responses:
        200:
          description: OK. Task metadata is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist or does not provide tasks, or the given
            task uuid was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
    put:
      tags:
      - Tasks
      summary: Replace task metadata
      description: |
        A put call to the task root record completely replaces task metadata,
        but does not affect sub-resources or sub-collections.
      parameters:
      - name: sid
        in: path
        description: ID of the service managing the task
        required: true
        schema:
          type: string
      - name: tid
        in: path
        description: ID of the task to update.
        required: true
        schema:
          type: string
      requestBody:
        description: New metadata for the task
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskMetadata'
        required: true
      responses:
        200:
          description: OK, task updated and returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist or does not provide tasks, or the given
            task uuid was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
    delete:
      tags:
      - Tasks
      summary: Delete a task
      description: |
        Deletes a task from the collection. This is only possible if the task
        is not currently active and if the user has sufficient access rights.
      parameters:
      - name: sid
        in: path
        description: ID of the service managing the task
        required: true
        schema:
          type: string
      - name: tid
        in: path
        description: ID of the task to delete.
        required: true
        schema:
          type: string
      responses:
        204:
          description: OK. Task deleted.
          content: {}
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist or does not provide tasks, or the given
            task UUID was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict. Task cannot be deleted because it is currently active.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
    patch:
      tags:
      - Tasks
      summary: Update task metadata (partial)
      description: |
        Does a partial update to the Task metadata. Given metadata replaces
        existing one, or is added to the record if not yet present. No metadata
        is deleted.
      parameters:
      - name: sid
        in: path
        description: ID of the service managing the task
        required: true
        schema:
          type: string
      - name: tid
        in: path
        description: ID of the task to update.
        required: true
        schema:
          type: string
      requestBody:
        description: New metadata for the task
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskMetadata'
        required: true
      responses:
        200:
          description: OK, task is updated and updated metadata returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist or does not provide tasks, or the given
            task UUID was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
  /services/{sid}/tasks/{tid}/action:
    post:
      tags:
      - Tasks
      summary: Trigger an action on a task
      description: |
        Trigger a new action on the task. Currently supported
        actions are `start`, `abort`, `pause` and `resume`.
      parameters:
      - name: sid
        in: path
        description: ID of the service.
        required: true
        schema:
          type: string
      - name: tid
        in: path
        description: ID of the task.
        required: true
        schema:
          type: string
      requestBody:
        description: |
          The body contains a JSON object with the name of the action.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Action'
        required: true
      responses:
        204:
          description: OK, action started.
          content: {}
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist or does not provide tasks, the given
            task UUID was not found or actions are not available on this task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, action could not be triggered. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
  /services/{sid}/tasks/{tid}/input:
    get:
      tags:
      - Tasks
      summary: Retrieve list of task input items
      description: |
        This route provides access to a Task's list of input documents. Input
        lists of tasks are structure-wise identical with lists in general,
        they differ in that they are task-internal and hence not available via
        the /lists route. Input lists can have list-level metadata, and each
        list item can have metadata as well.
        A call to this route will provide the list-level metadata and an
        inventory of the collection. Access input list items via the 'items'
        sub-collection. Use the 'embed' parameter to include item metadata
        in the result.
      parameters:
      - name: sid
        in: path
        description: ID of the service managing the task
        required: true
        schema:
          type: string
      - name: tid
        in: path
        description: ID of the task.
        required: true
        schema:
          type: string
      - name: embed
        in: query
        description: |
          Use 'embed' to include sub-collection metadata in the result.
          - "items": Include list-item metadata.
        schema:
          type: string
      responses:
        200:
          description: OK, collection of input list items returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist or does not provide tasks, the given
            task uuid was not found or the task has no input list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Intenral Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
    put:
      tags:
      - Tasks
      summary: Replace input list metadata
      description: |
        A PUT call to the input list root record completely replaces the
        list metadata but does not affect any list items.
      parameters:
      - name: sid
        in: path
        description: ID of the service managing the task
        required: true
        schema:
          type: string
      - name: tid
        in: path
        description: ID of the task to update.
        required: true
        schema:
          type: string
      requestBody:
        description: New metadata for the task input list
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskMetadata'
        required: true
      responses:
        200:
          description: OK, input list updated and returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist or does not provide tasks, the given
            task UUID was not found or the task has no input list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
    post:
      tags:
      - Tasks
      summary: Append a new item to the input list of the task
      description: |
        Creates a new entry in the given task's input list. Given metadata
        is assigned to the new list item.
      parameters:
      - name: sid
        in: path
        description: ID of the service managing the task
        required: true
        schema:
          type: string
      - name: tid
        in: path
        description: ID of the task.
        required: true
        schema:
          type: string
      - name: href
        in: query
        description: |
          URL of the document to add. This is a convenient way of
          adding a document without constructing a list item first.
        schema:
          type: string
      requestBody:
        description: |
          Complete list item metadata for the new task input list item.
          Use EITHER doc OR item parameter; if both exist, item is used.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListItem'
          application/rli:
            schema:
              type: string
              description: Repro-list-formatted document metadata
              example: |
                [JOBINFO]
                PRINTJOB_NAME "Ansegisel"

                [RECEIVER]
                default
                Pippin

                [Pippin]
                status "der mittlere"
                name "Pippin"

                [default]
                status "unbekannt"

                [REPRO_LIST_FORMAT]
                FIELD RECEIVER ^0
                FIELD status ^1
                FIELD name ^2

                [REPRO_LIST]
                ^Ansegisel^^Ansguise
                ^Pippin
          text/csv:
            schema:
              type: string
              description: CSV-formatted document metadata
              example: |
                list.name,item.metadata.Color,item.href,item.metadata.name,item.metadata.Printer
                Karl Martell,color,/v1/services/operator-fileupload/repo/1d431501-f5e3-480b-8ad2-bc31a09338f8,Arnulf.ps,HUGO
                Karl Martell,gray,/v1/services/operator-fileupload/repo/1d431501-f5e3-480b-8ad2-bc31a09338f8,Ansegisel.ps,hpm402
                Karl Martell,color,/v1/services/operator-fileupload/repo/1d431501-f5e3-480b-8ad2-bc31a09338f8,Pippin.ps,pdfout
        required: false
      responses:
        200:
          description: OK, task input list item created, item data returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ListItem'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist or does not provide tasks, the given
            task UUID was not found or the task has no input list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
    patch:
      tags:
      - Tasks
      summary: Update input list metadata (partial)
      description: |
        Does a partial update to the input list metadata. Given metadata replaces
        existing one, or is added to the record if not yet present. No metadata
        is deleted.
      parameters:
      - name: sid
        in: path
        description: ID of the service managing the task
        required: true
        schema:
          type: string
      - name: tid
        in: path
        description: ID of the task to update.
        required: true
        schema:
          type: string
      - name: embed
        in: query
        description: |
          Use 'embed' to include sub-collection metadata for updating.
          - "items": Include list-item data including indices for reordering.
# FIXME: embed nur in GET-Routen. (tt)
# FIXME: ist -items ein Parameter oder ein Wert für "embed"? (tt)
        schema:
          type: string
      requestBody:
        description: New metadata for the input list.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/List'
        required: true
      responses:
        200:
          description: OK, input list updated and returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist or does not provide tasks, the given
            task UUID was not found or the task has no input list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN

  /services/{sid}/tasks/{tid}/input/{id}:
    get:
      tags:
      - Tasks
      summary: Retrieve task item details
      description: |
        A GET call to this route returns input list item metadata.
      parameters:
      - name: sid
        in: path
        description: ID of the service managing the task
        required: true
        schema:
          type: string
      - name: tid
        in: path
        description: ID of the task.
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: ID of the input list item
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK, input list item data returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListItem'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist or does not provide tasks, the given
            task uuid was not found or the task has no input list, or just the
            given list item uuid was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN

    put:
      tags:
      - Tasks
      summary: Replace a task input list item
      description: |
        Replaces the task input list item's metadata, including the document
        reference.
      parameters:
      - name: sid
        in: path
        description: ID of the service managing the task
        required: true
        schema:
          type: string
      - name: tid
        in: path
        description: ID of the task.
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: ID of the input list item
        required: true
        schema:
          type: string
      requestBody:
        description: |
          Complete item metadata for the task item.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListItem'
        required: false
      responses:
        200:
          description: OK, list item updated. Item data returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListItem'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist or does not provide tasks, the given
            task UUID was not found or the task has no input list, or just the
            given list item UUID was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN

    delete:
      tags:
      - Tasks
      summary: Delete a task input list item
      description: |
        Deletes an item from a task's input list. The deleted ID is
        permanently orphaned, other list items keep their IDs.
      parameters:
      - name: sid
        in: path
        description: ID of the service managing the task
        required: true
        schema:
          type: string
      - name: tid
        in: path
        description: ID of the task.
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: ID of the input list item to delete
        required: true
        schema:
          type: string
      responses:
        204:
          description: OK, input list item deleted.
          content: {}
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist or does not provide tasks, the given
            task UUID was not found or the task has no input list, or just the
            given list item UUID was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be deleted. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN

    patch:
      tags:
      - Tasks
      summary: Update a task input list item (partial)
      description: |
        Updates task input list item metadata, replacing present entries and
        adding missing ones. No metadata is deleted by the patch.
      parameters:
      - name: sid
        in: path
        description: ID of the service managing the task
        required: true
        schema:
          type: string
      - name: tid
        in: path
        description: ID of the task.
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: ID of the task input list item to update
        required: true
        schema:
          type: string
      requestBody:
        description: |
          (Partial) metadata of an input list item.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListItem'
        required: false
      responses:
        200:
          description: OK, task input list item updated. Item data returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListItem'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist or does not provide tasks, the given
            task UUID was not found or the task has no input list, or just the
            given list item UUID was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN

  /tasks/{tid}/input/{id}/content:
    get:
      tags:
      - Tasks
      summary: Retrieve input document content
      description: |
        Resolve input document href and return content as octet-stream.
      parameters:
      - name: tid
        in: path
        description: ID of the task.
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: ID of the task input list item to retrieve
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK, content is returned.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to read the binary content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Not found. Either no entry was found under the given 'uuid', or the
            entry is not a document, or the document has no binary content (yet).
            See error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN

  /services/{sid}/tasks/{tid}/output:
    get:
      tags:
      - Tasks
      summary: Access list of task output items
      description: |
        This route provides access to a task's list of output documents. Output
        lists of tasks have the same structure as lists in general,
        they differ in that they are task-internal and hence not available via
        the /lists route. Output lists can have list-level metadata, and each
        list item can have metadata as well.
        A call to this route will provide the list-level metadata and an
        inventory of the collection. Access output list items via the 'items'
        sub-collection. Use the 'embed' parameter to include item metadata
        in the result.
      parameters:
      - name: sid
        in: path
        description: ID of the service managing the task
        required: true
        schema:
          type: string
      - name: tid
        in: path
        description: ID of the task.
        required: true
        schema:
          type: string
      - name: embed
        in: query
        description: |
          Use 'embed' to include sub-collection metadata in the result.
          - "items": Include list-item metadata.
        schema:
          type: string
      responses:
        200:
          description: OK, collection of output list items returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist or does not provide tasks, the given
            task UUID was not found or the task has no output list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
  /services/{sid}/tasks/{tid}/output/{id}:
    get:
      tags:
      - Tasks
      summary: Retrieve task output list item details
      description: |
        This route provides access to individual task output items.
      parameters:
      - name: sid
        in: path
        description: ID of the service managing the task
        required: true
        schema:
          type: string
      - name: tid
        in: path
        description: ID of the task.
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: ID of the output list item
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK, output list item data returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListItem'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            Service does not exist or does not provide tasks, the given
            task uuid was not found or the task has no output list, or just the
            given list item uuid was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
  /lists:
    get:
      tags:
      - Lists
      summary: Access collection of available Lists
      description: |
        This is the collection of Lists of the authenticated user. Use metadata property
        names and regular expressions in URL query string to search for entries
        and the offset and limit parameters to control the number of results returned.
      parameters:
      - name: offset
        in: query
        description: Index of first result to return.
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        description: Number of results to return. Maximum is 500.
        schema:
          type: integer
          default: 50
      - name: sort
        in: query
        description: |
          Sort query results. Comma-separated list of property names, prefixed with '-'
          for descending sort order. Example: 'sort=date,-name'
        schema:
          type: string
      - name: embed
        in: query
        description: |
          Include information about collection members.
          - "items": Include item data
          - "permissions": User access rights on each list
          - "metadata": Return list of lists metadata. Example:
            ```
            {
              exportTypes: [{
                name: 'csv',
                description: 'Export a CSV file',
                mimeType: 'text/csv'
              }],
              importTypes: [{
                name: 'csv',
                description: 'Import a CSV file',
                mimeType: 'text/csv'
              }]
            }
            ```
        schema:
          type: string
      responses:
        200:
          description: OK, collection of lists is returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/List'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: No lists available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
    post:
      tags:
      - Lists
      summary: Create new list
      description: |
        Creates a new entry in the list of lists. The `Content-Type` HTTP header
        defines the format of the import data. Default is JSON. If a URL is
        given in query as parameter `href`, the list to import is retrieved from that URL.
      parameters:
      - name: href
        in: query
        description: |
          URL of the list to add. Example: `http://somehost:3456/path/to/mylist.csv`
        schema:
          type: string
      requestBody:
        description: metadata of the document list to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/List'
          application/rli:
            schema:
              type: string
              description: Repro list text document containing metadata
              example: |
                [JOBINFO]
                PRINTJOB_NAME "Ansegisel"

                [RECEIVER]
                default
                Pippin

                [Pippin]
                status "der mittlere"
                name "Pippin"

                [default]
                status "unbekannt"

                [REPRO_LIST_FORMAT]
                FIELD RECEIVER ^0
                FIELD status ^1
                FIELD name ^2

                [REPRO_LIST]
                ^Ansegisel^^Ansguise
                ^Pippin
          text/csv:
            schema:
              type: string
              description: CSV-formatted text document containing metadata
              example: |
                list.name,item.metadata.Color,item.href,item.metadata.name,item.metadata.Printer
                Karl Martell,color,/v1/services/operator-fileupload/repo/1d431501-f5e3-480b-8ad2-bc31a09338f8,Arnulf.ps,HUGO
                Karl Martell,gray,/v1/services/operator-fileupload/repo/1d431501-f5e3-480b-8ad2-bc31a09338f8,Ansegisel.ps,hpm402
                Karl Martell,color,/v1/services/operator-fileupload/repo/1d431501-f5e3-480b-8ad2-bc31a09338f8,Pippin.ps,pdfout
        required: true
      responses:
        200:
          description: OK, list created. List metadata returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be created. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
  /lists/{lid}:
    get:
      tags:
      - Lists
      summary: Retrieve list metadata
      description: |
        This is the root record for a given list. It contains list-level
        metadata. Use the 'embed' parameter to include information about
        sub-resource like items or access rights.
        The client controls the exported data format with the `Accept` HTTP header
        field. Default is JSON.
      parameters:
      - name: lid
        in: path
        description: ID of the list.
        required: true
        schema:
          type: string
      - name: embed
        in: query
        description: |
          Include information about collection members or sub-resources.
          - "items": Include item data
          - "permissions": Include user access rights for the current user.
        schema:
          type: string
      responses:
        200:
          description: OK, metadata is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: The given list UUID was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
    put:
      tags:
      - Lists
      summary: Replace list metadata
      description: |
        This will completely replace the existing list metadata (if any) by the
        given metadata. Note that only list metadata itself can be updated.
        Internal auto-generated metadata (links; embedded), if present,
        are ignored.
      parameters:
      - name: lid
        in: path
        description: ID of the list.
        required: true
        schema:
          type: string
      requestBody:
        description: |
          New metadata for the list
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/List'
        required: false
      responses:
        200:
          description: OK, document list updated. New metadata returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: The given list UUID was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
    delete:
      tags:
      - Lists
      summary: Delete list
      description: |
        Deletes the list, including all its items (but keep the
        documents referred to by the items).
      parameters:
      - name: lid
        in: path
        description: ID of the list to delete
        required: true
        schema:
          type: string
      responses:
        204:
          description: OK, list removed.
          content: {}
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: The given list UUID was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
    patch:
      tags:
      - Lists
      summary: Update list metadata (partial)
      description: |
        Updates or adds part of the list metadata. Only given metadata
        will be replaced or added, no metadata will be removed. Note that
        only List metadata can be updated; internal auto-generated metadata
        (links, embedded), if present, are ignored.
      parameters:
      - name: lid
        in: path
        description: ID of the list
        required: true
        schema:
          type: string
      requestBody:
        description: |
          New metadata for the list
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/List'
        required: false
      responses:
        200:
          description: OK, document list updated. New metadata returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: The given list UUID was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
  /lists/{lid}/items:
    get:
      tags:
      - Lists
      summary: Get list items
      description: |
        This is the collection of items currently in the list. For performance
        reasons, only references are returned by default.
        Use metadata property names and regular expressions in URL query string
        to search for entries and the offset and limit parameters to control
        the number of results returned.
      parameters:
      - name: lid
        in: path
        description: ID of the list.
        required: true
        schema:
          type: string
      - name: offset
        in: query
        description: Index of first result to return.
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        description: Number of results to return. Maximum is 500.
        schema:
          type: integer
          default: 50
      - name: sort
        in: query
        description: |
          Sort query results. Comma-separated list of property names, prefixed with '-'
          for descending sort order. Example: 'sort=href,-index'
        schema:
          type: string
      - name: embed
        in: query
        description: |
          Sub-resources to include in the response.
          - "items": Include metadata for each list item
          - "permissions": Include user access rights
        schema:
          type: string
      responses:
        200:
          description: OK, collection of list items is returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ListItem'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: List not found or no list items present
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
    post:
      tags:
      - Lists
      summary: Appended an item to the list
      description: |
        Lists are ordered sets, items have consecutive indices (0..n).
        POSTing to this route will append a new item to the list (at the end)
      parameters:
      - name: lid
        in: path
        description: ID of the list.
        required: true
        schema:
          type: string
      - name: href
        in: query
        description: |
          Relative URL of the document instance to add to the list
        schema:
          type: string
      requestBody:
        description: |
          Use EITHER href OR item. If both exist, item is used.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListItem'
        required: false
      responses:
        200:
          description: OK, new item has been added to the list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListItem'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: The given list UUID was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be created. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
  /lists/{lid}/items/{id}:
    get:
      tags:
      - Lists
      summary: Retrieve list item metadata
      description: |
        Get metadata record of a list item. Note that the 'id' is NOT the
        index, which is part of item metadata, but the UUID.
      parameters:
      - name: lid
        in: path
        description: ID of the list.
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: ID of the list item
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK, list item data is returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListItem'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: The given list or list item uuid was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
    put:
      tags:
      - Lists
      summary: Replace a list item
      description: |
        Update and replace the entire metadata record of the current list item.
        Note that the ID is NOT the index of the item in the list. The index
        is part of item metadata.
      parameters:
      - name: lid
        in: path
        description: ID of the list.
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: ID of the element.
        required: true
        schema:
          type: string
      requestBody:
        description: |
          New item data to replace existing entry
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListItem'
        required: true
      responses:
        200:
          description: OK, list item is updated, item data returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListItem'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: The given list or list item UUID was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
    delete:
      tags:
      - Lists
      summary: Delete a list item
      description: |
        Deletes an entry from a list. Only the list entry is removed, not
        the document. Note that id is NOT the index of an item in the list.
        The index is part of item metadata.
      parameters:
      - name: lid
        in: path
        description: ID of the list
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: ID of the item to delete
        required: true
        schema:
          type: string
      responses:
        204:
          description: OK, list item removed.
          content: {}
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: The given list or list item UUID was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
    patch:
      tags:
      - Lists
      summary: Update list item (partial)
      description: |
        Update the metadata record of the current list item, adding missing
        entries but removing nothing. Note that the ID is NOT the index of the
        item in the list. The index is part of item metadata.
      parameters:
      - name: lid
        in: path
        description: ID of the list.
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: ID of the element.
        required: true
        schema:
          type: string
      - name: href
        in: query
        description: |
          Relative URL of document to link. This is a convenient way
          of just updating the href property of the existent list item.
        schema:
          type: string
      requestBody:
        description: |
          New link data to replace existing entry. Use EITHER item OR
          href; if both exist, item is used.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListItem'
        required: false
      responses:
        200:
          description: OK, list item updated, item data returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListItem'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: The given list or list item UUID was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be updated. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
  /ui:
    get:
      tags:
      - Panels
      summary: Retrieve list of default UI panels available to the user.
      description: |
        The SEAL Operator user interface provides the user with a set of
        default panels to use. A GET call to this route returns a list of panels
        available to the current user. Default panels cannot be edited or deleted.
      responses:
        200:
          description: OK, list of UI panel configurations returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PanelItem'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
  /ui/{pid}:
    get:
      tags:
      - Panels
      summary: Retrieve the default configuration of a UI panel
      description: |
        A GET call to this route returns a JSON object containing the default
        configuration of the panel.
      parameters:
      - name: pid
        in: path
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK, panel configuration is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigItem'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: |
            The panel with the given ID was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
  /panels:
    get:
      tags:
      - Panels
      summary: Retrieve list of UI panels available to the current user
      description: |
        The SEAL Operator user interface provides the user with a set of
        panels to use. A GET call to this route returns a list of user defined
        panels available to the current user. Use property names and regular
        expressions in URL query string to search for entries. User-specific
        configurations can be stored using a POST request; these can also be
        edited and deleted later.
      responses:
        200:
          description: OK, list of UI panel configurations returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConfigItem'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: No panels found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Intenral Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
    post:
      tags:
      - Panels
      summary: Create a new panel and save its configuration.
      description: |
        Users can create new panels and save their configuration under a given
        name for further use.
        If the ConfigItem does not contain a "name" key, a name for the
        configuration will be auto-generated.
        If the ConfigItem contains a "createpanel" key with value "1",
        an event is sent to the UI indicating the creation of a new panel
        with the objective of showing it.
        If the ConfigItem contains a "serviceId" key with the name of a
        service as value, a new task is created in the given service
        (if the given service provides tasks).
        If the ConfigItem contains a "taskId" key with the UUID of an
        existing task as value, a new UI panel will be created and the
        given task assigned.
      parameters:
        - name: x-owner
          in: header
          description: |
            User that should own the new panel. The user creating the panel
            becomes its creator, adding an owner is optional. Owner and
            creator rights can be managed through roles & rights.
            User identifiers can be anything, e. g. SAMaccountname or UPN.
            Must be matched with a claim from the JWT token in order to
            work in the user interface.
          required: false
          schema:
            type: string
      requestBody:
        description: |
          ConfigItem containing the configuration to store.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigItem'
        required: true
      responses:
        200:
          description: |
            OK, configuration was saved. The returned configItem contains
            the generated ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigItem'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict. A panel configuration under the "name" given in the
            ConfigItem already exists.
          content: {}
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
  /panels/{pid}:
    get:
      tags:
      - Panels
      summary: Retrieve a specific panel configuration
      description: |
        Returns the configuration for a panel stored by the current user.
      parameters:
      - name: pid
        in: path
        description: ID of the panel
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK, configuration returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigItem'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: Panel not found. The given PID is unknown.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
    put:
      tags:
      - Panels
      summary: Updates a saved panel configuration
      description: |
        A PUT request to a panel configuration will replace the entire stored
        configuration with the one contained in the request body.
        It is possible to use a different value for the "name" key in order
        to rename the saved configuration; however, the new name must not be
        in use. Note that only user-specific panel configurations can be updated.
      parameters:
      - name: pid
        in: path
        description: ID of the panel
        required: true
        schema:
          type: string
      requestBody:
        description: |
          ConfigItem containing the configuration to store.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigItem'
        required: true
      responses:
        200:
          description: OK, configuration updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigItem'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The current user lacks access rights, or is trying to
            update a read-only default configuration.
            schema:
              $ref: '#/definitions/Error'
          content: {}
        404:
          description: Panel not found. The given PID is unknown.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict. A panel configuration under the "name" given in the
            ConfigItem already exists.
          content: {}
        500:
          description: Intenral Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
    delete:
      tags:
      - Panels
      summary: Delete a stored panel configuration
      description: |
        User-specific panel configurations can be delete by a DELETE request to
        this route.
      parameters:
      - name: pid
        in: path
        description: ID of the panel configuration to remove.
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK, panel configuration was deleted, return deleted configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigItem'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The current user lacks access rights, or is trying to
            delete a read-only default configuration.
            schema:
              $ref: '#/definitions/Error'
          content: {}
        404:
          description: Panel not found. The given PID is unknown.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
  /config:
    get:
      tags:
      - Configuration
      summary: Access a configuration item or path
      description: |
        Use this route to browse the configuration.
        Configuration is structured unix file-system like, in a path/to/item way.
        Use path/to/item as 'path' parameter to access a specific item or together
        with 'keys' parameter for retrieving only keys.
      parameters:
      - name: path
        in: query
        description: Path/to/config/item
        schema:
          type: string
      - name: keys
        in: query
        description: |
          Return an array of strings containing all recursively fetched
          keys below the given 'path'. Without or an empty 'path' all
          available keys are returned.

           **Example response:**
          ```
          [
          "key1",
          "path/to/key2",
          "some/other/path/to/key3"
          ]
          ```
        allowEmptyValue: true
        schema:
          type: boolean
      responses:
        200:
          description: OK, configuration items returned.
          content:
            application/json:
              schema:
                type: object
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: The ConfigItem was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
      - Configuration
      summary: Store a configuration item
      description: |
        Stores the ConfigItem in the request body at the given path.
      parameters:
      - name: path
        in: query
        description: Path/to/config/item
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigItem'
        required: true
      responses:
        200:
          description: OK, configuration stored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigItem'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. User lacks access rights to change configuration.
            schema:
              $ref: '#/definitions/Error'
          content: {}
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - Configuration
      summary: Delete a configuration item
      description: |
        Deletes a single ConfigItem at the given path or all ConfigItems in the
        whole tree below if 'path' does not point to a leaf item.
      parameters:
      - name: path
        in: query
        description: Path/to/config/item
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK, configuration deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigItem'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. User lacks access rights to change configuration.
            schema:
              $ref: '#/definitions/Error'
          content: {}
        404:
          description: The ConfigItem was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /messages:
    get:
      tags:
      - Messages
      summary: Access the users messages
      description: |
        Every user has his own list of messages containing info, warning and error messages of various panels and actions.
        The messages are stored on server until they expire. This route provides access to the messages.
        Use property names and regular expressions in URL query string to search for
        entries and the offset and limit parameters to control the number of results returned.
      parameters:
      - name: offset
        in: query
        description: Index of first result to return.
        schema:
          type: integer
          default: 0
      - name: limit
        in: query
        description: Number of results to return. Maximum is 500.
        schema:
          type: integer
          default: 25
      - name: sort
        in: query
        description: |
          Sort query results. Comma-separated list of property names, prefixed with '-'
          for descending sort order. Example: 'sort=date,-type'
        schema:
          type: string
      responses:
        200:
          description: OK, list of entries is returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Message'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: Mo (matching) messages found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
    post:
      tags:
      - Messages
      summary: Create new message entry.
      description: |
        Creates a new record in the message list and assigns the posted data.
        The server adds a UUID and a creation date to each entry if not already present.
      requestBody:
        description: metadata of the entry to be created
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostMessage'
        required: true
      responses:
        200:
          description: OK, entry created. Entry metadata returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: The service does not provide messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, resource could not be created. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
  /messages/{uuid}:
    patch:
      tags:
      - Messages
      summary: Update a message
      description: |
        Update a message entry. Only data given with the patch will be
         changed/added; no entries removed. Updating uuid and creation date is prohibited.
      parameters:
      - name: uuid
        in: path
        description: ID of the message entry
        required: true
        schema:
          type: string
      requestBody:
        description: new metadata of the entry to be updated
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Message'
        required: true
      responses:
        200:
          description: OK, message entry updated, new message returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: Message not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        409:
          description: |
            Conflict, message could not be updated. See error message for
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
  /services/{sid}/function:
    get:
      tags:
      - Functions
      summary: List connector-specific functions
      description: |
        Services may expose individual functions, e. g. to provide dynamic
        data for selection lists in UI panels. The function routes are
        synchronous calls in contrast to the asynchronous commands.
        This route returns all supported functions of a service.
      parameters:
      - name: sid
        in: path
        description: ID of the service.
        required: true
        schema:
          type: string
      responses:
        200:
          description: OK, list of functions is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Functions'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: Service does not exist or does not provide functions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
  /services/{sid}/function/{fid}:
    post:
      tags:
      - Functions
      summary: Access a service-specific function
      description: |
        This route triggers a service-specific function and returns the result.
        The function routes are synchronous calls in contrast to the asynchronous commands.
      parameters:
      - name: sid
        in: path
        description: ID of the repository.
        required: true
        schema:
          type: string
      - name: fid
        in: path
        description: Name of the function to calls
        required: true
        schema:
          type: string
      - name: params
        in: query
        description: |
          String with a list of function specific parameter as key value pairs. Syntax:
          ```
          params="key::value[;key::value]*"
          ```
        schema:
          type: string
      responses:
        200:
          description: OK, function result is returned.
          content: {}
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: Service does not exist or does not provide this function
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN
  /sessions:
    get:
      tags:
      - Sessions
      summary: Get session information
      description: |
        Retrieve number of open sessions of the current user
      responses:
        200:
          description: OK, return object with session information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionInfo'
        401:
          description: Unauthorized (Auth token invalid)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        403:
          description: |
            Forbidden. The user lacks rights to access the service list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        404:
          description: No sessions available.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - oauth:
        - authN

  /auth:
    get:
      tags:
      - Auth
      summary: Get information about identity provider confguration
      description: |
        Get information about identity provider confguration
      responses:
        200:
          description: OK, return object with idp configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthInfo'
        500:
          description: Internal Application Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: |
            Unexpected error. Please report a bug and include error details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    AuthInfo:
      type: object
      properties:
        url:
          type: string

    Task:
      type: object
      properties:
        name:
          type: string
        sid:
          type: string
        tid:
          type: string
        metadata:
          type: object
          properties: {}
          description: Task metadata. Note that these do not contain item metadata.
        created:
          type: integer
          description: Timestamp of task creation
          format: date-time
        started:
          type: integer
          description: Timestamp of task started
          format: date-time
        finished:
          type: integer
          description: Timestamp of task finished
          format: date-time
        inputListLength:
          type: integer
          description: Number of items in input list
        outputListLength:
          type: integer
          description: Number of items in output list
        status:
          $ref: '#/components/schemas/StatusType'
        links:
          type: object
          properties: {}
          description: |
            If requested, the links section contains hrefs to
            - "self": the task itself
            - "input": input documents
            - "output": output documents
        embedded:
          type: object
          properties: {}
          description: |
            Embedded sub-resources or sub-collections, as requested through the
            "embed" query parameter
    Action:
      type: object
      properties:
        action:
          type: string
          enum:
          - start
          - abort
          - pause
          - resume
      description: |
        A JSON object containing the name of the command to execute and its parameters.
    Message:
      type: object
      properties:
        uuid:
          type: string
          description: A server-side-specific UUID for each new entry
        type:
          type: string
          description: The message type
          enum:
          - info
          - warning
          - error
        text:
          type: string
          description: The message text
        date:
          type: integer
          description: The creation time of the message as timestamp
          format: int64
        source:
          type: string
          description: Name of the panel which created the message
        read:
          type: boolean
          description: Flag if the message has already been read by user
      description: |
        A JSON object containing a message
    RepoEntry:
      type: object
      properties:
        id:
          type: string
          description: Local ID of the document within the repository.
        uuid:
          type: string
          description: Global ID of the document, created by SEAL Operator
        name:
          type: string
          description: (File) name of the entry
        type:
          type: string
          description: Type of RepoEntry.
          enum:
          - document
          - collection
        links:
          type: object
          properties:
            self:
              type: string
              description: Href to the document itself
        embedded:
          type: object
          properties: {}
          description: |
            Embedded sub-resources as requested through the "embed" query
            parameter, e. g. "permissions", "icon", "thumb".
        metadata:
          type: object
          properties: {}
          description: Metadata assigned to the entry
      description: |
        A RepoEntry represents a record within the repository part of a service.
        A RepoEntry may be either a document or a collection. All RepoEntries
        may contain metadata and user permission records. collections may also
        contain children, while documents may have binary content.
    TaskMetadata:
      type: object
      properties:
        name:
          type: string
          description: Name of the task
        metadata:
          type: object
          properties: {}
          description: Metadata assigned to the task
      description: |
        A task metadata object contains user-specific metadata with any number of arbitrary
        properties and the optional property 'name'.
    PanelItem:
      type: object
      properties:
        pid:
          type: string
          description: unique ID of the PanelListItem
        name:
          type: string
        type:
          type: string
          description: the panel type the configuration is for, e. g. scratch, p4,...
      description: A JSON object containing name and ID of a PanelListItem
    SessionInfo:
      type: object
      properties:
        no:
          type: integer
          description: number of currently open sessions of this user
      description: Informations about users sessions
    Service:
      type: object
      properties:
        id:
          type: string
          description: Identifier of the service within SEAL Operator
        name:
          type: string
          description: Label describing the service
        metadata:
          type: object
          properties: {}
          description: Metadata of the service
        links:
          type: object
          properties: {}
          description: |
            If requested by MIME type, the links section contains hrefs to
            - "self": The service itself
            - "permissions": User permissions on the service
        embedded:
          type: object
          properties: {}
          description: |
            Sub-collections and/or sub-resources requested through the embed
            query parameter.
      description: |
        A service represents a target system connected to the SEAL Operator
        framework. It may be able to process tasks and/or provide access to
        documents, under its /tasks and /repo routes.
    ConfigItem:
      type: object
      description: |
        A JSON object containing key-value pairs representing the configuration.
    Error:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        metadata:
          type: object
          properties: {}
    Functions:
      type: object
      description: |
        Contains for each available function one object with an href to the function.
        Key of each object is the function name.
    Command:
      type: object
      properties:
        action:
          type: string
          enum:
          - copy
          - move
        parameter:
          type: object
          properties: {}
          description: |
            Command-specific parameter, e. g. hrefs of documents
      description: |
        A JSON object containing the name of the command to execute and its paramters.
    StatusType:
      type: string
      description: Definition of allowed status names
      enum:
      - open
      - processing
      - completed
      - paused
      - aborted
      - failed
    List:
      type: object
      properties:
        uuid:
          type: string
          description: Unique ID of the list, generated by SEAL Operator.
        name:
          type: string
          description: User-specific name for the list. Does not have to be unique.
        created:
          type: integer
          description: Timestamp of list creation
          format: date-time
        lastModified:
          type: integer
          description: Timestamp of list creation
          format: date-time
        listLength:
          type: integer
          description: Number of items in list
        links:
          type: object
          properties: {}
          description: |
            If requested by MIME type, the links section contains hrefs to
            - "self": the list itself
        embedded:
          type: object
          properties:
            listItems:
              type: array
              items:
                $ref: '#/components/schemas/ListItem'
          description: |
            Embedded sub-resources or sub-collections, as requested through the
            "embed" query parameter
        metadata:
          type: object
          properties: {}
          description: List metadata. Note that these do not contain item metadata.
      description: |
        A list is an ordered sequence of documents as list items. Each list can
        contain arbitrary metadata. List items may also have metadata assigned,
        which does not replace but complement document metadata. A document may
        not be unique within a list, i. e. a List can contain several items all
        pointing to the same document (but most likely with different item
        metadata).
    CommandStatus:
      type: object
      properties:
        cid:
          type: string
        status:
          $ref: '#/components/schemas/StatusType'
        command:
          $ref: '#/components/schemas/Command'
      description: A JSON object containing a command and its current status
    ListItem:
      type: object
      properties:
        index:
          type: integer
          description: |
            This is the index of an item in a list. The index is maintained
            by the SEAL Operator backend. Setting the index to a value beyond
            the end of the list will move the item to the end of the list.
            Setting the index to 0 will move th item to the top of the list.
            Setting the index to a value in use by another item will replace
            this item, moving it (and all with higher indices) one space down
            in the list, by increasing their index values.
        href:
          type: string
          description: URL location of linked ressource
        metadata:
          type: object
          properties: {}
          description: Additional data to be stored with the link
    BaseRepoEntry:
      type: object
      properties:
        name:
          type: string
          description: (File) name of the entry
        type:
          type: string
          description: Type of RepoEntry.
          enum:
          - document
          - collection
        metadata:
          type: object
          properties: {}
          description: Metadata assigned to the entry
      description: |
        A RepoEntry contains user-specific metadata with any number of arbitrary
        properties and two mandatory properties 'name' and 'type'.
    PostMessage:
      type: object
      properties:
        type:
          type: string
          description: The message type
          enum:
          - info
          - warning
          - error
        text:
          type: string
          description: The message text
        source:
          type: string
          description: Name of the panel which created the message
      description: |
        A JSON object containing a message

  securitySchemes:
    oauth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://your.auth.host/your/auth/path
          tokenUrl: https://your.auth.host/your/token/path
          scopes:
            authN: User is authenticated
