openapi: 3.1.0
info:
  title: capito AI - API - ERSTE
  version: 2.0.0
tags:
  - name: Account
    description: Endpoints for managing the user's account.
  - name: Customization
    description: Endpoints for customizing the Assistance & Translation functionality.
  - name: Assistance
    description: Endpoints for getting assistance for content.
  - name: Translation
    description: Endpoints for translating (simplifying) content.
  - name: Feedback
    description: Endpoints for managing feedback on the analysis/simplification.
  - name: Internationalisation
    description: Endpoints for accessing the Internationalisation-Service.
paths:
  /v2/account/me:
    get:
      tags:
        - Account
      summary: The user's account information.
      description: |
        Requires Account Role: `verified`
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Account"
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - ALFA: [ ]
        - ApiToken: [ ]
  /v2/account/me/settings:
    put:
      tags:
        - Account
      summary: Update the user's account settings.
      description: |
        Requires Account Role: `verified`
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccountSettings"
        required: true
      responses:
        205:
          description: Reset Content
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        403:
          $ref: "#/components/responses/ForbiddenResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - ALFA: [ ]
        - ApiToken: [ ]
  /v2/account/{account-id}/lists/dictionary:
    put:
      tags:
        - Customization
      summary: "Add a new entry to the Personal Dictionary."
      description: |
        Required Role:
        - Account: `admin`
      parameters:
        - $ref: "#/components/parameters/AccountID"
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/PersonalDictionaryEntry"
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/PersonalDictionaryEntry"
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        409:
          description: Conflict (Entry with the same phrase and locale already exists)
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
    get:
      tags:
        - Customization
      summary: "Fetch the entries of the Personal Dictionary."
      description: |
        Required Role:
        - Account: `verified`
      parameters:
        - $ref: "#/components/parameters/AccountID"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/PersonalDictionary"
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
  /v2/account/{account-id}/lists/dictionary/{entry-id}:
    delete:
      tags:
        - Customization
      summary: "Delete an entry from the Personal Dictionary."
      description: |
        Required Role:
        - Account: `admin`
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/ListEntryID"
      responses:
        205:
          description: Reset Content
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        404:
          $ref: "#/components/responses/NotFoundResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
  /v2/account/{account-id}/lists/snippets:
    put:
      tags:
        - Customization
      summary: "Add a new entry to the Snippets."
      description: |
        Required Role:
        - Account: `admin`
      parameters:
        - $ref: "#/components/parameters/AccountID"
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/SnippetsEntry"
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SnippetsEntry"
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
    get:
      tags:
        - Customization
      summary: "Fetch the entries of the Snippets."
      description: |
        Required Role:
        - Account: `verified`
      parameters:
        - $ref: "#/components/parameters/AccountID"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Snippets"
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
  /v2/account/{account-id}/lists/snippets/{entry-id}:
    delete:
      tags:
        - Customization
      summary: "Delete an entry from the Snippets."
      description: |
        Required Role:
        - Account: `admin`
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/ListEntryID"
      responses:
        205:
          description: Reset Content
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
  /v2/account/{account-id}/lists/spellings:
    put:
      tags:
        - Customization
      summary: "Add a new entry to the Spellings."
      description: |
        The value for `similar.autodetect` will default to `false` if not set explicitly to keep legacy behaviour.
        
        Required Role:
        - Account: `admin`
      parameters:
        - $ref: "#/components/parameters/AccountID"
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/SpellingEntry"
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SpellingEntry"
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
    get:
      tags:
        - Customization
      summary: "Fetch the entries of the Spellings."
      description: |
        Required Role:
        - Account: `verified`
      parameters:
        - $ref: "#/components/parameters/AccountID"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/SpellingEntries"
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
  /v2/account/{account-id}/lists/spellings/{entry-id}:
    delete:
      tags:
        - Customization
      summary: "Delete an entry from the Spellings."
      description: |
        Required Role:
        - Account: `admin`
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/ListEntryID"
      responses:
        205:
          description: Reset Content
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
  /v2/assistance/me/scores:
    put:
      tags:
        - Assistance
      summary: The score.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContentLocalised"
        required: true
      responses:
        200:
          description: Successful Response
          content:
            application/json:
              schema:
                properties:
                  a1:
                    description: Score for proficiency 'a1'
                    example:
                      combined: 20
                    allOf:
                      - $ref: "#/components/schemas/Score"
                  a2:
                    description: Score for proficiency 'a2'
                    example:
                      combined: 59
                    allOf:
                      - $ref: "#/components/schemas/Score"
                  b1:
                    description: Score for proficiency 'b1'
                    example:
                      combined: 93
                    allOf:
                      - $ref: "#/components/schemas/Score"
                type: object
                required:
                  - a1
                  - a2
                  - b1
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - ALFA: [ ]
        - ApiToken: [ ]
  /v2/assistance/me/tokens:
    put:
      tags:
        - Assistance
      summary: The tokens.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContentLocalised"
        required: true
      responses:
        200:
          description: Successful Response
          content:
            application/json:
              schema:
                properties:
                  tokens:
                    items:
                      $ref: "#/components/schemas/Token"
                    type: array
                    maxItems: 1048576
                    title: Tokens
                    description: The tokens.
                type: object
                required:
                  - tokens
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - ALFA: [ ]
        - ApiToken: [ ]
  /v2/assistance/me/lexicon:
    put:
      tags:
        - Assistance
      summary: The entries available in the lexicon.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContentLocalised"
        required: true
      responses:
        200:
          description: Successful Response
          content:
            application/json:
              schema:
                properties:
                  entries:
                    items:
                      $ref: "#/components/schemas/LexiconEntry"
                    type: array
                    maxItems: 4096
                    title: Entries
                    description: List of all entries found in the capito Lexicon.
                type: object
                required:
                  - entries
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - ALFA: [ ]
        - ApiToken: [ ]
  /v2/assistance/me/analysis:
    put:
      tags:
        - Assistance
      summary: The result of the analysis incl. suggestions.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContentTargeted"
        required: true
      responses:
        200:
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - ALFA: [ ]
        - ApiToken: [ ]
  /v2/translation/me:
    put:
      tags:
        - Translation
      summary: The translation of the given text.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContentTargeted"
        required: true
      responses:
        200:
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContentTranslated"
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - ALFA: [ ]
        - ApiToken: [ ]
  /v2/i18n/me/issues/{id}:
    get:
      summary: The localised strings for an Issue.
      tags:
        - Internationalisation
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/IssueID"
        - name: Accept-Language
          in: header
          schema:
            allOf:
              - $ref: "#/components/schemas/Locale"
            default: en
        - name: lang
          in: query
          description: Overrides the header `Accept-Language`.
          schema:
            allOf:
              - $ref: "#/components/schemas/Locale"
            default: en
      responses:
        200:
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LocalisedIssue"
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        404:
          description: Not Found
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - ALFA: [ ]
        - ApiToken: [ ]
  /v2/feedback/me/assistance/expected-issues:
    get:
      tags:
        - Feedback
      summary: All possible expected issues.
      parameters:
        - name: Accept-Language
          in: header
          schema:
            $ref: "#/components/schemas/Locale"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          $ref: "#/components/schemas/IssueID"
                        title_short:
                          type: string
                          minLength: 1
                          maxLength: 96
                      required:
                        - id
                        - title_short
                      title: Localised Issue
                      example:
                        id: gender
                        title_short: Gender
                    minItems: 1
                    maxItems: 64
                required:
                  - data
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        403:
          $ref: "#/components/responses/ForbiddenResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - ALFA: [ ]
        - ApiToken: [ ]
  /v2/feedback/me/assistance/issues:
    get:
      tags:
        - Feedback
      summary: All feedback for assistance given.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        submitted_at:
                          type: string
                          format: date-time
                        last_processed_at:
                          type: string
                          format: date-time
                        status:
                          type: string
                          enum:
                            - new
                            - approved
                            - rejected
                      allOf:
                        - $ref: "#/components/schemas/FeedbackAssistanceIssue"
                      required:
                        - status
                        - modified_at
                    minItems: 0
                    maxItems: 32
                required:
                  - data
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        403:
          $ref: "#/components/responses/ForbiddenResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - ALFA: [ ]
        - ApiToken: [ ]
    post:
      tags:
        - Feedback
      summary: Submit feedback on an assistance issue.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FeedbackAssistanceIssue"
        required: true
      responses:
        201:
          description: Created
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        403:
          $ref: "#/components/responses/ForbiddenResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - ALFA: [ ]
        - ApiToken: [ ]
  /v2/feedback/me/translation/questions:
    get:
      tags:
        - Feedback
      summary: The questions asked for feedback.
      parameters:
        - name: Accept-Language
          in: header
          schema:
            $ref: "#/components/schemas/Locale"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          $ref: "#/components/schemas/QuestionID"
                        text:
                          type: string
                          minLength: 1
                          maxLength: 256
                          description: The localized text to show to the user.
                      required:
                        - id
                        - text
                      title: Localised Question
                      example:
                        id: gender
                        text: How satisfied are you with the translation?
                    minItems: 1
                    maxItems: 16
                required:
                  - data
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        403:
          $ref: "#/components/responses/ForbiddenResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - ALFA: [ ]
        - ApiToken: [ ]
  /v2/feedback/me/translation:
    post:
      tags:
        - Feedback
      summary: Submit feedback on a translation.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                source:
                  allOf:
                    - $ref: "#/components/schemas/Content"
                  title: The original content.
                result:
                  allOf:
                    - $ref: "#/components/schemas/Content"
                  title: The result of the translation.
                configuration:
                  type: object
                  properties:
                    locale:
                      $ref: "#/components/schemas/Locale"
                    proficiency:
                      $ref: "#/components/schemas/Proficiency"
                  required:
                    - locale
                    - proficiency
                questionnaire:
                  type: object
                  properties:
                    answers:
                      type: array
                      items:
                        type: object
                        properties:
                          question_id:
                            $ref: "#/components/schemas/QuestionID"
                          score:
                            type: integer
                            minimum: 0
                            maximum: 5
                        required:
                          - question_id
                          - score
                      minItems: 1
                      maxItems: 16
                      uniqueItems: true
                  required:
                    - answers
              required:
                - source
                - result
                - configuration
                - questionnaire
        required: true
      responses:
        201:
          description: Created
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        403:
          $ref: "#/components/responses/ForbiddenResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - ALFA: [ ]
        - ApiToken: [ ]
components:
  securitySchemes:
    ALFA:
      type: openIdConnect
      openIdConnectUrl: https://idp-p.alfa.s-mxs.net/kerberoslogin/openid-configuration
    ApiToken:
      type: apiKey
      in: header
      name: Authorization
      description: |
        The `token` itself must be prefixed by `Token` followed by a space (`' '`) (e.g. `Token abc123`) to be considered valid (similar to the `Bearer `-schema for JSON-Web-Token).
        
        Creating new API-Token or revoking existing ones is only possible via *capito* after written approval by one of the administrators (David Pichler, Gerald Mirtitsch).
        Also required is the ID of the account for which the API-Token is to be generated for.
  parameters:
    AccountID:
      name: account-id
      in: path
      required: true
      schema:
        allOf:
          - $ref: "#/components/schemas/AccountID"
    MemberID:
      name: member-id
      in: path
      required: true
      schema:
        allOf:
          - $ref: "#/components/schemas/AccountID"
    ListEntryID:
      name: entry-id
      in: path
      required: true
      schema:
        allOf:
          - $ref: "#/components/schemas/ListEntryID"
  schemas:
    AccountRole:
      type: string
      enum:
        - unverified
        - verified
        - feedback
      description: Can be used to determine which endpoints are user is allowed to access.
      title: Account Role
    AccountID:
      type: string
      pattern: ^\S{1,128}$
      title: Id
      description: The ID of the user.
      example: user_1
    Account:
      properties:
        id:
          $ref: "#/components/schemas/AccountID"
        name:
          type: string
          maxLength: 128
          minLength: 1
          title: Name
          description: The name of the user (used on the Invoice).
          example: atempo Betriebsgesellschaft mbH
        metadata:
          allOf:
            - $ref: "#/components/schemas/AccountMetadata"
          description: Further information on the account.
        settings:
          allOf:
            - $ref: "#/components/schemas/AccountSettings"
          description: The settings.
        roles:
          type: array
          items:
            $ref: "#/components/schemas/AccountRole"
          minItems: 1
          maxItems: 8
          uniqueItems: true
        is_admin:
          type: boolean
          description: Indicated if an account has Administrator privileges.
      type: object
      required:
        - id
        - name
        - email
        - metadata
        - settings
        - roles
        - is_admin
      title: Account
    AccountMetadata:
      properties:
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The date and time when the account was created.
          example: 2022-08-10T00:45:08.243691
        deleted_at:
          type: string
          format: date-time
          nullable: true
          title: Deleted At
          description: The date and time when the user requested a deletion of his/her account.
          example: 2023-09-20T19:33:27.241807
      type: object
      required:
        - created_at
        - deleted_at
      title: Account Metadata
    AccountSettings:
      properties:
        tutorial_shown_at:
          type: string
          format: date-time
          nullable: true
          title: The timestamp when the tutorial was shown to the user.
      type: object
      required:
        - tutorial_shown_at
      title: Account Settings
    ListEntryID:
      type: string
      format: uuid
    PersonalDictionary:
      type: object
      properties:
        items:
          type: array
          maxItems: 128
          items:
            $ref: "#/components/schemas/PersonalDictionaryEntry"
      required:
        - items
    PersonalDictionaryEntry:
      type: object
      properties:
        id:
          allOf:
            - $ref: "#/components/schemas/ListEntryID"
          readOnly: true
        phrase:
          type: string
          minLength: 1
          maxLength: 64
          examples:
            - capito.ai
        locale:
          allOf:
            - $ref: "#/components/schemas/Locale"
        description:
          type: string
          minLength: 1
          maxLength: 512
          examples:
            - A tool for making text understandable
      required:
        - id
        - phrase
        - locale
        - description
    Snippets:
      type: object
      properties:
        items:
          type: array
          maxItems: 128
          items:
            $ref: "#/components/schemas/SnippetsEntry"
      required:
        - items
    SnippetsEntry:
      type: object
      properties:
        id:
          allOf:
            - $ref: "#/components/schemas/ListEntryID"
          readOnly: true
        shorthand:
          type: string
          minLength: 1
          maxLength: 64
          examples:
            - disclaimer
        locale:
          allOf:
            - $ref: "#/components/schemas/Locale"
        full_text:
          type: string
          minLength: 1
          maxLength: 1024
          examples:
            - This is a long disclaimer text from the year 2024 that is standardized.
      required:
        - id
        - shorthand
        - locale
        - full_text
    SpellingEntries:
      type: object
      properties:
        items:
          type: array
          minItems: 0
          maxItems: 128
          items:
            $ref: "#/components/schemas/SpellingEntry"
      required:
        - items
    SpellingEntry:
      type: object
      properties:
        id:
          allOf:
            - $ref: "#/components/schemas/ListEntryID"
          readOnly: true
        phrase:
          type: string
          minLength: 1
          maxLength: 96
          examples:
            - capito.ai
        locale:
          allOf:
            - $ref: "#/components/schemas/Locale"
        similar:
          type: object
          properties:
            autodetect:
              type: boolean
            items:
              type: array
              items:
                type: object
                properties:
                  phrase:
                    type: string
                    minLength: 1
                    maxLength: 96
                required:
                  - phrase
              minItems: 0
              maxItems: 8
              examples:
                - - phrase: capitoAI
                  - phrase: capito-ai
                  - phrase: atempo
          required:
            - items
      required:
        - id
        - phrase
        - locale
        - similar
    Proficiency:
      type: string
      enum:
        - a1
        - a2
        - b1
      title: Proficiency
      description: The Proficiency targeted by the user.
    Locale:
      type: string
      enum:
        - cs
        - de
        - en
        - es
        - fr
        - hr
        - hu
        - pl
        - ro
        - sk
        - sl
      title: Locale
      description: The Locale of a String Resource
    LocalisedResourceID:
      type: string
      pattern: ^[0-9a-z-]{1,128}$
      title: Localised Resource ID
    LocalisedResource:
      properties:
        id:
          type: string
          pattern: ^[0-9a-z-]{1,128}$
          title: The ID.
          example: issue-trademark-spelling-summary
        locale:
          title: The locale.
          example: en
          allOf:
            - $ref: "#/components/schemas/Locale"
        content:
          type: string
          maxLength: 512
          minLength: 1
          title: The content of the String Resource.
          example: The trademark is spelled incorrectly.
      type: object
      required:
        - id
        - locale
        - content
      title: Localised Resource
    Content:
      type: string
      maxLength: 1048576
      title: Content
      description: UTF8-encoded string.
      example: |-
        This document showcases the incredible features of capitoDigital.
        Starting with the analysis of text to look for issues concerning the text's
        accessibility; and ending with automated simplification based on machine-learning
        and sophisticated algorithms, developed in-house by our own experts in
        computer linguistic. Why may one ask? Because this is our goal: Help people
        understand!
    ContentLocalised:
      properties:
        content:
          minLength: 1
          maxLength: 10000
          allOf:
            - $ref: "#/components/schemas/Content"
        locale:
          allOf:
            - $ref: "#/components/schemas/Locale"
      type: object
      required:
        - content
        - locale
      title: Content (Localised)
    ContentTargeted:
      allOf:
        - $ref: "#/components/schemas/ContentLocalised"
        - type: object
          properties:
            proficiency:
              description: The proficiency of the result.
              allOf:
                - $ref: "#/components/schemas/Proficiency"
          required:
            - proficiency
      title: Content (Targeted)
    ContentTranslated:
      properties:
        content:
          allOf:
            - $ref: "#/components/schemas/Content"
      type: object
      required:
        - content
      title: Content (Simplified)
    TokenLocation:
      properties:
        start:
          type: integer
          maximum: 1048576.0
          minimum: 0.0
          title: Start
          description: The start index.
          example: 51
        length:
          type: integer
          maximum: 1048576.0
          minimum: 0.0
          title: Length
          description: The number of characters after the start index.
          example: 13
      type: object
      required:
        - start
        - length
      title: Location
    Token:
      properties:
        locations:
          items:
            $ref: "#/components/schemas/TokenLocation"
          type: array
          maxItems: 1048576
          title: Locations
          description: The location.
      type: object
      required:
        - locations
      title: Token
    LexiconEntry:
      properties:
        locations:
          items:
            $ref: "#/components/schemas/TokenLocation"
          type: array
          maxItems: 32
          title: Locations
          description: The locations of the entry.
        description:
          type: string
          title: Description
          description: The description based on the capito Lexicon.
          example: |-
            'capito digital'' is a product of the atempo GesmbH aimed at 
            helping write understandable texts.
      type: object
      required:
        - locations
        - description
      title: Lexicon Entry
    Score:
      properties:
        combined:
          type: integer
          maximum: 100.0
          minimum: 0.0
          title: Combined
          description: The combined score.
          example: 93
      type: object
      required:
        - combined
      title: Score
    Result:
      properties:
        issues:
          items:
            $ref: "#/components/schemas/Issue"
          type: array
          maxItems: 4096
          title: Issues
          description: The list of issues found during the analysis.
      type: object
      required:
        - issues
      title: Result
    IssueID:
      type: string
      pattern: ^[0-9a-z-]{1,128}$
      title: ID
      description: The ID.
      example: issue-trademark-spelling-summary
    LocalisedIssue:
      type: object
      properties:
        id:
          $ref: "#/components/schemas/IssueID"
        locale:
          $ref: "#/components/schemas/Locale"
        title_short:
          type: string
          minLength: 1
          maxLength: 96
        title_long:
          type: string
          minLength: 1
          maxLength: 256
        description:
          type: string
          minLength: 1
          maxLength: 512
        details:
          type: string
          minLength: 1
          maxLength: 2048
      required:
        - title_long
        - title_short
        - description
        - details
      title: Localised Issue
      example:
        id: verb-blacklisted-relaxed
        locale: en
        title_short: Word choice
        title_long: You should only use common verbs (activity words).
        description: Verbs are activity words. They express actions.
        details: I run, she writes
    Issue:
      properties:
        id:
          $ref: "#/components/schemas/IssueID"
        metadata:
          description: The metadata.
          allOf:
            - $ref: "#/components/schemas/IssueMetadata"
        description:
          description: The description of the issue.
          allOf:
            - $ref: "#/components/schemas/IssueDescription"
        params:
          deprecated: true
          items:
            $ref: "#/components/schemas/IssueParameter"
          type: array
          maxItems: 32
          title: Params
          description: The list of parameters. Those can be used to customize the
            generic description of an issue.
        locations:
          items:
            $ref: "#/components/schemas/TokenLocation"
          type: array
          maxItems: 32
          minItems: 1
          title: Locations
          description: The locations where is issue was found.
        suggestions:
          items:
            $ref: "#/components/schemas/Suggestion"
          type: array
          maxItems: 8
          title: Suggestions
          description: The suggestions available for this issue.
      type: object
      required:
        - id
        - metadata
        - description
        - params
        - locations
        - suggestions
      title: Issue
    IssueDescription:
      properties:
        summary_id:
          title: Summary Resource ID
          description: The Resource ID of the summary.
          example: issue-spelling-trademark-summary
          allOf:
            - $ref: "#/components/schemas/LocalisedResourceID"
        details_id:
          title: Details Resource ID
          description: The Resource ID of the details.
          example: issue-spelling-trademark-details
          allOf:
            - $ref: "#/components/schemas/LocalisedResourceID"
      type: object
      required:
        - summary_id
        - details_id
      title: Issue Description
    IssueMetadata:
      properties:
        category:
          example: vocabulary
          allOf:
            - $ref: "#/components/schemas/IssueCategory"
        severity:
          example: warning
          allOf:
            - $ref: "#/components/schemas/IssueSeverity"
      type: object
      required:
        - category
        - severity
      title: Issue Metadata
    IssueCategory:
      type: string
      enum:
        - gender
        - grammar
        - layout
        - sentence
        - text
        - vocabulary
      title: Issue Category
      description: The Category of the Issue
    IssueSeverity:
      type: string
      enum:
        - error
        - information
        - notice
        - warning
      title: Issue Severity
      description: The severity of the issue.
    IssueParameter:
      properties:
        key:
          type: string
          pattern: ^[0-9a-z-]{1,128}$
          title: Key
          description: The key.
          example: original-value
        value:
          type: string
          maxLength: 64
          minLength: 1
          title: Value
          description: The value.
          example: capitoDigital
      type: object
      required:
        - key
        - value
      title: Issue Parameter
    Suggestion:
      properties:
        transformations:
          items:
            $ref: "#/components/schemas/SuggestionTransformation"
          type: array
          maxItems: 32
          minItems: 1
          title: Transformations
          description: The list of elements of which the suggestion is comprised of.
          example:
            - location:
                start: 51
                length: 13
              content: capito digital
        confidence:
          description: The certainty of the suggestion to be valid.
          allOf:
            - $ref: "#/components/schemas/SuggestionConfidence"
        recommended_actions:
          items:
            $ref: "#/components/schemas/RecommendedAction"
          type: array
          uniqueItems: true
          title: Recommended Actions
          description: An ordered set of recommended actions which might be performed
            for this suggestion.
        description:
          type: string
          title: Description
          description: Further information on this suggestion.
          example: Incorrect spelling of trademark.
      type: object
      required:
        - transformations
        - confidence
        - recommended_actions
        - description
      title: Suggestion
    RecommendedAction:
      type: string
      enum:
        - apply-transformations
      title: Recommended Action
      description: The recommended action to be taken by the user for this suggestion.
    SuggestionConfidence:
      type: string
      enum:
        - low
        - high
      title: Suggestion Confidence
      description: The Confidence of the Suggestion
    SuggestionTransformation:
      properties:
        location:
          description: The location of the element.
          allOf:
            - $ref: "#/components/schemas/TokenLocation"
        content:
          type: string
          maxLength: 256
          title: Content
          description: The content of the element.
      type: object
      required:
        - location
        - content
      title: Suggestion Transformation
    QuestionID:
      type: string
      pattern: ^[0-9a-z-]{1,64}$
      minLength: 1
      maxLength: 128
      title: Question ID
      description: The unique ID which is language-invariant.
    FeedbackAssistanceIssue:
      type: object
      properties:
        source:
          allOf:
            - $ref: "#/components/schemas/Content"
          title: The original content.
        configuration:
          type: object
          properties:
            locale:
              $ref: "#/components/schemas/Locale"
            proficiency:
              $ref: "#/components/schemas/Proficiency"
          required:
            - locale
            - proficiency
        locations:
          items:
            $ref: "#/components/schemas/TokenLocation"
          type: array
          minItems: 1
          maxItems: 32
          title: The Locations
          description: The locations on which the feedback is referring to.
        issue_shown:
          nullable: true
          allOf:
            - $ref: "#/components/schemas/IssueID"
          title: Issue ID shown
          description: The ID of the issue shown or null.
          example: spelling-trademark
        issue_expected:
          nullable: true
          allOf:
            - $ref: "#/components/schemas/IssueID"
          title: Expected Issue ID
          description: The type/ID of the issue that the user would have liked to see.
        reason:
          type: string
          enum:
            - false-positive
            - false-negative
          title: Reason/Type of feedback
          description: |-
            * Use `false-positive` to indicate that the issue should **NOT** have been shown.
            * Use `false-negative` to indicate that an issue should have been shown.
          example: false-positive
        description:
          type: string
          nullable: true
          minLength: 0
          maxLength: 1024
          title: A short description of reasoning
          description: Details on why the issue displayed may not be correct.
          example: The trademark is registered as "capitoDigital", not "capito digital".
      required:
        - source
        - configuration
        - locations
        - issue_shown
        - issue_expected
        - reason
        - description
  responses:
    UnauthorizedResponse:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                minLength: 0
                maxLength: 512
                example: Additional information.
            required:
              - error
    NotFoundResponse:
      description: Not Found
    ForbiddenResponse:
      description: Forbidden
    InternalServerErrorResponse:
      description: Internal Server Error
    ServiceUnavailableErrorResponse:
      description: Service Unavailable / Timeout
