openapi: 3.1.0
info:
  title: capito digital - API - Commercial
  version: 2.5.0
tags:
  - name: Internal
    description: Endpoints which can only be accessed with a private key.
  - name: Account
    description: Endpoints for managing an account.
  - name: Authentication
    description: Endpoints for managing access to the platform.
  - name: Team-Account
    description: Endpoints for managing a _Team-Account_.
  - name: Customization
    description: Endpoints for customizing the Assistance & Translation functionality.
  - name: Assistance
    description: Endpoints for getting assistance for content.
  - name: Feedback
    description: Endpoints for managing feedback on the analysis/simplification.
  - name: Internationalisation
    description: Endpoints for accessing the localised strings.
  - name: Translation
    description: Endpoints for translating (simplifying) content.
  - name: Shop
    description: Endpoints for accessing the products purchased, products purchasable and checkout.
paths:
  /v2/account/search:
    get:
      tags:
        - Internal
      summary: Query for accounts.
      description: |
        Runs the given query and returns a list of accounts that match.

        Required Role:
        - Account: any
      parameters:
        - $ref: "#/components/parameters/ClientID"
        - in: query
          name: q
          required: true
          description: |
            The query which is executed.

            Possible fields to query are
             - `email` to find an exact match for the given email
          schema:
            type: string
            minLength: 1
            maxLength: 512
            examples:
            - email%3Dsupport%40capito.ai
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  accounts:
                    type: object
                    properties:
                      id:
                        allOf:
                          - $ref: "#/components/schemas/AccountID"
                    required:
                      - id
                required:
                  - accounts
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
  /v2/account/invite:
    post:
      tags:
        - Internal
      summary: Invite using an email.
      description: |
        Sends an email to an email-address asking to create a new account.
        The new user may also be added to a _Team-Account_ if one is specified.

        Required Role:
        - Account: any
      parameters:
        - $ref: "#/components/parameters/ClientID"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  allOf:
                    - $ref: "#/components/schemas/Email"
                team:
                  type: object
                  properties:
                    id:
                      allOf:
                        - $ref: "#/components/schemas/AccountID"
                    roles:
                      allOf:
                        - $ref: "#/components/schemas/TeamAccountRoles"
                  required:
                    - id
              required:
                - email
      responses:
        201:
          description: Created
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
  /v2/account:
    put:
      tags:
        - Account
      summary: Create/Register a new user account.
      description: |
        Creates a new _User-Account_ with the given credentials.
        
        This _User-Account_ will have the role `unverified` attached per default.
      requestBody:
        content:
          application/json:
            schema:
              properties:
                email:
                  type: string
                  format: email
                  title: Email
                  description: The email which will be used for logging in (i.e. username) and to which invoices will be sent to.
                  examples:
                   - atempo.graz@atempo.at
                password:
                  type: string
                  maxLength: 128
                  minLength: 8
                  title: Password
                  description: |-
                    The password which is needed to log into the account.
                    It  must meet the following criteria to be accepted:
                    * at least 1 lowercase letter
                    * at least 1 uppercase letter
                    * at least 1 digit
                    * at least 1 special character
                    * at least 8 characters
                    * at most 128 characters
                  examples:
                   - $ecure PassW0rd!
              type: object
              required:
                - email
                - password
              title: Credentials
        required: true
      responses:
        201:
          description: Created
        400:
          description: Bad Request
        409:
          description: Conflict (account already exists)
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
  /v2/account/verify:
    post:
      tags:
        - Account
      summary: Verify that the email is valid and reachable.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccountVerificationToken"
        required: true
      responses:
        204:
          description: No Content
        400:
          description: Bad Request
        404:
          description: Not Found (token does not exist)
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
  /v2/account/{account-id}/trigger-verification:
    post:
      tags:
        - Account
      summary: Request a verification email for this account.
      description: |
        Triggers the dispatch of an email to the user's email-address for verification.

        Required Role:
        - Account: any
        - Team-Account: `admin`
      parameters:
        - $ref: "#/components/parameters/AccountID"
      responses:
        204:
          description: No Content
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        409:
          description: Conflict (account is already verified)
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
  /v2/account/{account-id}:
    get:
      tags:
        - Account
      summary: Fetch the account information.
      description: |
        Required Role:
        - Account: any
        - Team-Account: `admin`, `member`
      parameters:
        - $ref: "#/components/parameters/AccountID"
      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:
        - Auth0: []
        - Token: []
    delete:
      tags:
        - Account
      summary: Delete the account.
      description: |
        Required Role:
        - Account: any
        - Team-Account: `admin`
      parameters:
        - $ref: "#/components/parameters/AccountID"
      responses:
        205:
          description: Reset Content
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        410:
          description: Gone (account was already deleted)
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
  /v2/account/{account-id}/profile:
    put:
      tags:
        - Account
      summary: Replace the account profile.
      description: |
        Required Role:
        - Account: `verified`
        - Team-Account: `admin`
      parameters:
        - $ref: "#/components/parameters/AccountID"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccountProfile"
      responses:
        205:
          description: Reset Content
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
    get:
      tags:
        - Account
      summary: Fetch the account profile.
      description: |
        Required Role:
        - Account: any
        - Team-Account: `admin`, `member`
      parameters:
        - $ref: "#/components/parameters/AccountID"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountProfile"
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
  /v2/account/{account-id}/settings:
    put:
      tags:
        - Account
      summary: Update the account's settings.
      description: |
        Required Role:
        - Account: `verified`
        - Team-Account: `admin`
      parameters:
        - $ref: "#/components/parameters/AccountID"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                tutorial_shown_at:
                  type: [string, 'null']
                  format: date-time
                  title: The timestamp when the tutorial was shown to the user.
                selected_account_id:
                  allOf:
                    - $ref: "#/components/schemas/AccountID"
                  type: [string, 'null']
                  title: Selected Account-ID (Team-ID)
                  description: |
                    If this value is either `undefined`, `null` or the same Account ID that is making the request
                    the value will be set to `me`.
              required:
                - tutorial_shown_at
              title: Account Settings
        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:
        - Auth0: []
        - Token: []
  /v2/account/{account-id}/member-of:
    put:
      tags:
        - Account
      summary: Create a new _Team-Account_.
      description: |
        Required Role:
        - Account: `verified`
        - Team-Account: not applicable

        The account making the request will have the role `admin` and `member` in the _Team-Account_.
      parameters:
        - $ref: "#/components/parameters/AccountID"
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/AccountProfile"
              properties:
                email:
                  allOf:
                    - $ref: "#/components/schemas/Email"
                  description: The email used communication and billing information.
              examples:
                - name: My Team
                  email: team@tiziano-anker.com
      responses:
        205:
          description: Reset Content
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
    get:
      tags:
        - Account
      summary: Fetch all _Team-Accounts_ of which the account is a member of.
      description: |
        Required Role:
        - Account: `verified`
        - Team-Account: not applicable
      parameters:
        - $ref: "#/components/parameters/AccountID"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  accounts:
                    $ref: "#/components/schemas/AccountMemberExtendedList"
                required:
                  - accounts
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
  /v2/account/{account-id}/lists/dictionary:
    put:
      tags:
        - Customization
      summary: "[WIP] Add a new entry to the Personal Dictionary."
      description: |
        Required Role:
        - Account: `verified`
        - Team-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: "[WIP] Fetch the entries of the Personal Dictionary."
      description: |
        Required Role:
        - Account: `verified`
        - Team-Account: `admin`, `member`
      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: "[WIP] Delete an entry from the Personal Dictionary."
      description: |
        Required Role:
        - Account: `verified`
        - Team-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: "[WIP] Add a new entry to the Snippets."
      description: |
        Required Role:
        - Account: `verified`
        - Team-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: "[WIP] Fetch the entries of the Snippets."
      description: |
        Required Role:
        - Account: `verified`
        - Team-Account: `admin`, `member`
      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: "[WIP] Delete an entry from the Snippets."
      description: |
        Required Role:
        - Account: `verified`
        - Team-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: "[WIP] Add a new entry to the Spellings."
      description: |
        Required Role:
        - Account: `verified`
        - Team-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: "[WIP] Fetch the entries of the Spellings."
      description: |
        Required Role:
        - Account: `verified`
        - Team-Account: `admin`, `member`
      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: "[WIP] Delete an entry from the Spellings."
      description: |
        Required Role:
        - Account: `verified`
        - Team-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}/members:
    put:
      tags:
        - Team-Account
      summary: Replace all members of the _Team-Account_.
      description: |
        This will replace all but the _User-Account_ making the request with the _User-Accounts_ found in the request body.
        
        Required Role:
        - Account: not applicable
        - Team-Account: `admin`
      parameters:
        - $ref: "#/components/parameters/AccountID"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccountMembers"
      responses:
        205:
          description: Reset Content
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
    get:
      tags:
        - Team-Account
      summary: Fetch all members of the _Team-Account_.
      description: |
        Required Role:
        - Account: not applicable
        - Team-Account: `admin`
      parameters:
        - $ref: "#/components/parameters/AccountID"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  members:
                    $ref: "#/components/schemas/AccountMemberList"
                required:
                  - members
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
    post:
      tags:
        - Team-Account
      summary: Add members to the _Team-Account_.
      description: |
        Required Role:
        - Account: not applicable
        - Team-Account: `admin`

        Account IDs which are already a member of the _Team-Account_ are ignored.
      parameters:
        - $ref: "#/components/parameters/AccountID"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccountMembers"
      responses:
        205:
          description: Reset Content
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
  /v2/account/{account-id}/members/{member-id}:
    get:
      tags:
        - Team-Account
      summary: Fetch the members of the _Team-Account_.
      description: |
        Required Role:
        - Account: not applicable
        - Team-Account: `admin`
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/MemberID"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/AccountMember"
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
    post:
      tags:
        - Team-Account
      summary: Update the member of the _Team-Account_.
      description: |
        Required Role:
        - Account: not applicable
        - Team-Account: `admin`

        Account IDs which are already a member of the account are ignored.
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/MemberID"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                roles:
                  type: array
                  items:
                    allOf:
                      - $ref: "#/components/schemas/TeamAccountRole"
                  minItems: 1
                  maxItems: 8
              required:
                - roles
      responses:
        205:
          description: Reset Content
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
    delete:
      tags:
        - Team-Account
      summary: Remove the member from the _Team-Account_.
      description: |
        Required Role:
        - Account: not applicable
        - Team-Account: `admin`
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/MemberID"
      responses:
        205:
          description: Reset Content
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
  /v2/auth/{account-id}/tokens:
    put:
      tags:
        - Authentication
      summary: Create a new token.
      description: |
        Required Role:
        - Account: `verified`
        - Team-Account: not applicable

        This will creates a new token that enables the access to our API.

        Those tokens can then be used in the `Authorization`-Header prefixed by `Token `
        (the space at the is required!) to get access to the API instead of using the JSON-Web-Token.
      parameters:
        - $ref: "#/components/parameters/AccountID"
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: "#/components/schemas/AuthToken"
      responses:
        201:
          description: Created
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
    get:
      tags:
        - Authentication
      summary: Fetch all tokens.
      description: |
        Required Role:
        - Account: `verified`
        - Team-Account: not applicable
      parameters:
        - $ref: "#/components/parameters/AccountID"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/AuthTokens"
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
  /v2/auth/{account-id}/tokens/{token-id}:
    delete:
      tags:
        - Authentication
      summary: Delete a token.
      description: |
        Required Role:
        - Account: `verified`
        - Team-Account: not applicable
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/AuthTokenID"
      responses:
        205:
          description: Reset Content
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
  /v2/assistance/{account-id}/scores:
    put:
      tags:
        - Assistance
      summary: The Score.
      description: |
        The Score is a single value per proficiency which represents the understandability of the text given.
        
        100 is the best score, 0 is the worst one.
        
        Required Role:
        - Account: `verified`
        - Team-Account: `admin`, `member`
      parameters:
        - $ref: "#/components/parameters/AccountID"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContentLocalised"
        required: true
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                properties:
                  a1:
                    description: Score for proficiency 'a1'
                    examples:
                      - combined: 20
                    allOf:
                      - $ref: "#/components/schemas/Score"
                  a2:
                    description: Score for proficiency 'a2'
                    examples:
                      - combined: 59
                    allOf:
                      - $ref: "#/components/schemas/Score"
                  b1:
                    description: Score for proficiency 'b1'
                    examples:
                      - combined: 93
                    allOf:
                      - $ref: "#/components/schemas/Score"
                type: object
                required:
                  - a1
                  - a2
                  - b1
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        402:
          description: Payment Required (quota exceeded for assistance)
        403:
          $ref: "#/components/responses/ForbiddenResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
  /v2/assistance/{account-id}/tokens:
    put:
      tags:
        - Assistance
      summary: The tokens.
      description: |
        Required Role:
        - Account: `verified`
        - Team-Account: `admin`, `member`
      parameters:
        - $ref: "#/components/parameters/AccountID"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContentLocalised"
        required: true
      responses:
        200:
          description: Success
          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"
        402:
          description: Payment Required (quota exceeded for assistance)
        403:
          $ref: "#/components/responses/ForbiddenResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
  /v2/assistance/{account-id}/lexicon:
    put:
      tags:
        - Assistance
      summary: The entries available in the lexicon.
      description: |
        The returned list of entries also contains the entries from the Personal Dictionary if an entry is found.
        
        Required Role:
        - Account: `verified`
        - Team-Account: `admin`, `member`
      parameters:
        - $ref: "#/components/parameters/AccountID"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContentLocalised"
        required: true
      responses:
        200:
          description: Success
          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 & Personal Dictionary.
                type: object
                required:
                  - entries
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        402:
          description: Payment Required (quota exceeded for assistance)
        403:
          $ref: "#/components/responses/ForbiddenResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
  /v2/assistance/{account-id}/analysis:
    put:
      tags:
        - Assistance
      summary: The result of the analysis including suggestions.
      description: |
        Required Role:
        - Account: `verified`
        - Team-Account: `admin`, `member`
      parameters:
        - $ref: "#/components/parameters/AccountID"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContentTargeted"
        required: true
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Result"
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        402:
          description: Payment Required (quota exceeded for assistance)
        403:
          $ref: "#/components/responses/ForbiddenResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
  /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"
      description: |
        Requires Account Role: `feedback`
      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 Expected Issue
                      examples:
                        - 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:
        - Auth0: []
        - Token: []
  /v2/feedback/me/assistance/issue:
    post:
      tags:
        - Feedback
      summary: Submit feedback on an assistance issue.
      description: |
        Requires Account Role: `feedback`
      requestBody:
        content:
          application/json:
            schema:
              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:
                  allOf:
                    - $ref: "#/components/schemas/IssueID"
                  type: [string, 'null']
                  title: Issue ID shown
                  description: The ID of the issue shown or null.
                  examples:
                   - spelling-trademark
                issue_expected:
                  allOf:
                    - $ref: "#/components/schemas/IssueID"
                  type: [string, 'null']
                  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.
                  examples:
                   - false-positive
                description:
                  type: string
                  minLength: 0
                  maxLength: 1024
                  title: A short description of reasoning
                  description: Details on why the issue displayed may not be correct.
                  examples:
                   - The trademark is registered as "capitoDigital", not "capito digital".
              required:
                - source
                - configuration
                - locations
                - issue_shown
                - issue_expected
                - reason
                - description
        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:
        - Auth0: []
        - Token: []
  /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"
      description: |
        Requires Account Role: `feedback`
      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
                      examples:
                        - 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:
        - Auth0: []
        - Token: []
  /v2/feedback/me/translation:
    post:
      tags:
        - Feedback
      summary: Submit feedback on a translation.
      description: |
        Requires Account Role: `feedback`
      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:
        - Auth0: []
        - Token: []
  /v2/i18n/{account-id}/issues/{id}:
    get:
      tags:
        - Internationalisation
      summary: The localised strings for an Issue.
      description: |
        Required Role:
        - Account: `verified`
        - Team-Account: `admin`, `member`
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - 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: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LocalisedIssue"
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        403:
          $ref: "#/components/responses/ForbiddenResponse"
        404:
          description: Not Found
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
  /v2/translation/{account-id}:
    put:
      tags:
        - Translation
      summary: The translation/simplification of the given text.
      description: |
        Required Role:
        - Account: `verified`
        - Team-Account: `admin`, `member`
      parameters:
        - $ref: "#/components/parameters/AccountID"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContentTargeted"
        required: true
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContentTranslated"
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        402:
          description: Payment Required (quota exceeded for assistance)
        403:
          $ref: "#/components/responses/ForbiddenResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
  /v2/shop/{account-id}/subscription:
    get:
      tags:
        - Shop
      summary: The user's current subscription.
      description: |
        Required Role:
        - Account: `verified`
        - Team-Account: `admin`
      parameters:
        - $ref: "#/components/parameters/AccountID"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Subscription"
        204:
          description: Not Content (no active subscription)
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        403:
          $ref: "#/components/responses/ForbiddenResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
  /v2/shop/{account-id}/quotas:
    get:
      tags:
        - Shop
      summary: The account's quotas of characters for the different services.
      description: |
        Required Role:
        - Account: `verified`
        - Team-Account: `admin`, `member`
      parameters:
        - $ref: "#/components/parameters/AccountID"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Quotas"
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        403:
          $ref: "#/components/responses/ForbiddenResponse"
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
  /v2/shop/{account-id}/portal:
    get:
      tags:
        - Shop
      summary: Generate an URL for the Customer Portal on Stripe.
      description: |
        Required Role:
        - Account: `verified`
        - Team-Account: `admin`
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - name: return_url
          in: query
          required: false
          schema:
            type: [string, 'null']
            format: uri
            minLength: 1
            title: The URL to redirect to from the Stripe Customer Portal.
        - name: deep_link
          in: query
          required: false
          schema:
            type: string
            enum:
              - overview
              - subscription_update
              - subscription_cancel
            title: The location where to create the link to.
            default: overview
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    minLength: 1
                    format: uri
                    title: Stripe Portal URL
                    description: The URL to redirect to.
                    examples:
                     - https://billing.stripe.com/session/{SESSION_SECRET}
                required:
                  - url
        204:
          description: No Content (no active subscription)
        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:
        - Auth0: []
        - Token: []
  /v2/shop/{account-id}/checkout:
    post:
      tags:
        - Shop
      summary: Purchase products.
      description: |
        Required Role:
        - Account: `verified`
        - Team-Account: `admin`
      parameters:
        - $ref: "#/components/parameters/AccountID"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                products:
                  type: array
                  items:
                    $ref: "#/components/schemas/ProductID"
                  minItems: 1
                  maxItems: 8
                  uniqueItems: true
                  title: Products
                  description: The products to add to the checkout.
                promotion_code:
                  $ref: "#/components/schemas/PromotionCode"
                success_url:
                  type: string
                  format: uri
                  title: Success URL
                  description: The URL to which to be redirected if the checkout was successful.
                cancel_url:
                  type: string
                  format: uri
                  title: Cancel URL
                  description: The URL to which to be redirected if the checkout is cancelled.
              required:
                - products
                - promotion_code
                - success_url
                - cancel_url
        required: true
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    title: ID
                    description: The ID of the session. May be used for logging purposes.
                    examples:
                     - cs_a1xaIhdV9b1X1CG9qZXJMIwbeuxvBiuKQs0a6m1ddMOX7aq1lWJ0oFXYBB
                  url:
                    type: string
                    minLength: 1
                    format: uri
                    title: Checkout URL
                    description: The URL to redirect to for finishing the payment process.
                    examples:
                     - https://checkout.stripe.com/c/pay/...
                required:
                  - id
                  - url
        400:
          description: Bad Request
        401:
          $ref: "#/components/responses/UnauthorizedResponse"
        403:
          $ref: "#/components/responses/ForbiddenResponse"
        409:
          description: Conflict (account already has an active subscription)
        500:
          $ref: "#/components/responses/InternalServerErrorResponse"
        503:
          $ref: "#/components/responses/ServiceUnavailableErrorResponse"
      security:
        - Auth0: []
        - Token: []
components:
  securitySchemes:
    Auth0:
      type: oauth2
      flows:
        password:
          tokenUrl: https://auth.capito.eu/oauth/token
          scopes: {}
    Token:
      type: http
      scheme: token
      description: |
        Requires a token to be in the `Authorization`-Header prefixed by `Token ` (the space at the end is required!).
  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"
    ClientID:
      in: header
      name: CAI-Client-ID
      required: true
      description: |
        A 192-bit, base64-encoded key used to authenticate the CAI-Client.

        This key **MUST NOT** be made public.
      schema:
        type: string
        format: byte
        minLength: 32
        maxLength: 32
        examples:
          - NDNhZWM1ZjRjYzdiNDhhNWJmNGM3YmQ5
    AuthTokenID:
      name: token-id
      in: path
      required: true
      schema:
        allOf:
          - $ref: "#/components/schemas/AuthTokenID"
    ListEntryID:
      name: entry-id
      in: path
      required: true
      schema:
        allOf:
          - $ref: "#/components/schemas/ListEntryID"
  schemas:
    Email:
      type: string
      maxLength: 128
      minLength: 1
      title: Email
      examples:
       - support@atempo.at
    AccountID:
      type: string
      pattern: ^\S{1,128}$
      title: Id
      description: The ID of the account.
      examples:
       - capito|123
    AccountRole:
      type: string
      enum:
        - unverified
        - verified
        - feedback
      description: Can be used to determine which endpoints a account is allowed to access.
      title: Account Role
    TeamAccountRole:
      type: string
      enum:
        - admin
        - member
      description: Can be used to determine which endpoints a Team-Account is allowed to access.
      title: Team-Account Role
    TeamAccountRoles:
      type: array
      minItems: 1
      maxItems: 8
      items:
        allOf:
          - $ref: "#/components/schemas/TeamAccountRole"
    AccountMember:
      type: object
      properties:
        id:
          allOf:
            - $ref: "#/components/schemas/AccountID"
        roles:
          allOf:
            - $ref: "#/components/schemas/TeamAccountRoles"
      required:
        - id
        - roles
      title: Account Member
      description: The member of an account.
    AccountMemberExtended:
      type: object
      allOf:
        - $ref: "#/components/schemas/AccountMember"
        - type: object
          properties:
            created_at:
              type: string
              format: date-time
            emails:
              type: array
              items:
                allOf:
                  - $ref: "#/components/schemas/Email"
              minItems: 1
          required:
            - created_at
            - emails
      title: Account Member (Extended)
      description: The member of an account with more data.
    AccountMemberList:
      type: array
      minItems: 1
      maxItems: 128
      items:
        $ref: "#/components/schemas/AccountMember"
      title: Account Members List
      description: List of all members.
    AccountMembers:
      type: object
      properties:
        members:
          $ref: "#/components/schemas/AccountMemberList"
      required:
        - members
      title: Account Members
      description: List of all members.
    AccountMemberExtendedList:
      type: array
      minItems: 1
      maxItems: 128
      items:
        $ref: "#/components/schemas/AccountMemberExtended"
      title: Account Members (Extended) List
      description: List of all members (extended).
    AccountMembersExtended:
      type: object
      properties:
        members:
          $ref: "#/components/schemas/AccountMembersExtended"
      required:
        - members
      title: Account Members (Extended) List
      description: List of all extended members.
    AccountProfileName:
      type: string
      minLength: 1
      maxLength: 64
      title: Account Profile Name
      examples:
       - Tiziano Anker
    AccountProfile:
      type: object
      properties:
        name:
          allOf:
            - $ref: "#/components/schemas/AccountProfileName"
      required:
        - name
      title: Account Profile
    AccountType:
      type: string
      enum:
        - user
        - team
      title: Account Type
    Account:
      properties:
        id:
          allOf:
            - $ref: "#/components/schemas/AccountID"
        email:
          allOf:
            - $ref: "#/components/schemas/Email"
          description: The email of the user used to for logging into the account.
        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:
            oneOf:
              - $ref: "#/components/schemas/AccountRole"
              - $ref: "#/components/schemas/TeamAccountRole"
          minItems: 1
          maxItems: 8
          uniqueItems: true
        type:
          allOf:
            - $ref: "#/components/schemas/AccountType"
        is_verified:
          type: boolean
          description: A flag indicating if the account's email is verified.
      type: object
      required:
        - id
        - email
        - metadata
        - settings
        - roles
      title: Account
    Accounts:
      type: array
      minItems: 1
      maxItems: 16
      items:
        $ref: "#/components/schemas/Account"
      title: Accounts
      description: List of accounts.
    AccountMetadata:
      properties:
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The date and time when the account was created.
          examples:
           - 2022-08-10T00:45:08.243691
        deleted_at:
          type: [string, 'null']
          format: date-time
          title: Deleted At
          description: The date and time when the user requested a deletion of his/her account.
          examples:
           - 2023-09-20T19:33:27.241807
      type: object
      required:
        - created_at
        - deleted_at
      title: Account Metadata
    AccountSettings:
      properties:
        tutorial_shown_at:
          type: [string, 'null']
          format: date-time
          title: The timestamp when the tutorial was shown to the user.
        selected_account_id:
          allOf:
            - $ref: "#/components/schemas/AccountID"
          title: Selected Account ID
          description: The currently selected Account-ID (Team-ID), defaults to `me`.
      type: object
      required:
        - tutorial_shown_at
        - selected_account_id
      title: Account Settings
    AccountVerificationToken:
      properties:
        token:
          type: string
          pattern: ^[2-9A-HJ-NP-Za-km-z]{64}$
          title: Token
      type: object
      required:
        - token
      title: Account Verification Token
    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
          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:
            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
    AuthTokenID:
      type: string
      format: uuid
    AuthToken:
      type: object
      properties:
        id:
          allOf:
            - $ref: "#/components/schemas/AuthTokenID"
          readOnly: true
        name:
          type: string
          minLength: 1
          maxLength: 128
          examples:
           - MacBook Pro
        token:
          type: string
          pattern: ^[2-9A-HJ-NP-Za-km-z]{64}$
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
      required:
        - id
        - name
        - token
        - created_at
      title: Authentication Token
    AuthTokens:
      type: object
      properties:
        tokens:
          type: array
          items:
            $ref: "#/components/schemas/AuthToken"
          maxItems: 5
      required:
        - tokens
    Proficiency:
      type: string
      enum:
        - a1
        - a2
        - b1
      title: Proficiency
      description: The Proficiency targeted by the user.
    Locale:
      type: string
      enum:
        - en
        - de
        - es
        - fr
        - ro
        - hu
        - sl
      title: Locale
    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
      examples:
        - 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
    Content:
      type: string
      maxLength: 16384
      title: Content
      description: UTF8-encoded string.
      examples:
       - |-
        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
          description: |-
            UTF8-encoded string.

            **Attention**: The actual length which is accepted by the server might be lower due to
            limits imposed by the purchased number of characters which can be processed.
          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.
          examples:
           - 51
        length:
          type: integer
          maximum: 1048576.0
          minimum: 0.0
          title: Length
          description: The number of characters after the start index.
          examples:
           - 13
      type: object
      required:
        - start
        - length
      title: Token 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.
          examples:
           - |-
            '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.
          examples:
           - 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
    QuestionID:
      type: string
      pattern: ^[0-9a-z-]{1,64}$
      minLength: 1
      maxLength: 128
      title: Question ID
      description: The unique ID which is language-invariant.
    IssueID:
      type: string
      pattern: ^[0-9a-z-]{1,128}$
      title: Issue ID
      description: The ID of an issue.
      examples:
       - issue-trademark-spelling-summary
    Issue:
      properties:
        id:
          $ref: "#/components/schemas/IssueID"
        metadata:
          $ref: "#/components/schemas/IssueMetadata"
        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
    IssueMetadata:
      properties:
        category:
          examples:
           - vocabulary
          allOf:
            - $ref: "#/components/schemas/IssueCategory"
        severity:
          examples:
           - 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.
    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.
          examples:
            -
            - location:
                start: 51
                length: 13
              content: capito digital
        confidence:
          $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.
          examples:
           - Incorrect spelling of trademark.
      type: object
      required:
        - transformations
        - confidence
        - recommended_actions
        - description
      title: Suggestion
    RecommendedAction:
      type: string
      enum:
        - apply-transformations
        - replace-manually
      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
    Subscription:
      properties:
        created_at:
          type: string
          format: date-time
          title: Start of Subscription
          description: The timestamp when the subscription was created.
        ends_at:
          type: [string, 'null']
          format: date-time
          title: End of Subscription
          description: The timestamp when the subscription will end.
          examples:
           - 2023-10-13T16:26:09.204376
        billing_cycle:
          properties:
            started_at:
              type: string
              format: date-time
              title: Start of current Billing Cycle
              description: The timestamp when the current billing cycle started.
            ends_at:
              type: string
              format: date-time
              title: End of current Billing Cycle
              description: The timestamp when the current billing cycle ends.
              examples:
               - 2023-10-11T21:34:47.482698
          type: object
          required:
            - started_at
            - ends_at
          title: Current billing cycle
      type: object
      required:
        - created_at
        - ends_at
        - billing_cycle
      title: Subscription
    Quota:
      type: object
      properties:
        remaining:
          type: number
          title: Remaining
          description: The number of characters remaining.
          minimum: 0
          maximum: 2147483648
          examples:
           - 500000
      required:
        - remaining
      title: Quota
    ServiceQuota:
      type: object
      properties:
        subscription:
          allOf:
            - $ref: "#/components/schemas/Quota"
          description: The quota from the active subscription.
          title: Subscription Quota
        pre_paid:
          allOf:
            - $ref: "#/components/schemas/Quota"
          description: The quota from pre-paid character packages.
          title: Pre-Paid Quota
        promotion:
          type: object
          allOf:
            - $ref: "#/components/schemas/Quota"
            - type: object
              properties:
                expires_at:
                  type: string
                  format: date-time
                  title: Expires At
                  description: The timestamp when the quota will be reset to 0.
                  examples:
                   - 2023-10-10T15:28:23.333102
              required:
                - expires_at
          description: The quota from promotions.
          title: Promotional Quota
      required:
        - subscription
        - pre_paid
      title: Service Quota
    Quotas:
      properties:
        assistance:
          allOf:
            - $ref: "#/components/schemas/ServiceQuota"
          title: Assistance Quota
          description: Quota used when content is processed by the Assistance-Service.
        translation:
          allOf:
            - $ref: "#/components/schemas/ServiceQuota"
          title: Translation Quota
          description: Quota used when content is processed by the Translation-Service.
      type: object
      required:
        - assistance
        - translation
      title: Quotas
    PromotionCode:
      type: string
      pattern: ^[A-Z_0-9]{0,64}$
      title: Promotion Code
      description: The promotion code to be applied in the checkout.
    ProductID:
      type: string
      minLength: 1
      maxLength: 64
      pattern: ^[a-zA-Z0-9_-]{1,64}$
      title: Product ID
  responses:
    UnauthorizedResponse:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                minLength: 0
                maxLength: 512
                examples:
                 - Additional information.
            required:
              - error
    ForbiddenResponse:
      description: Forbidden
    NotFoundResponse:
      description: Not Found
    InternalServerErrorResponse:
      description: Internal Server Error
    ServiceUnavailableErrorResponse:
      description: Service Unavailable / Timeout
