openapi: 3.0.1
info:
  title: Tolgee API
  description: >-
    Subset of the Tolgee localization platform REST API covering projects, keys,
    translations, languages, import/export, and screenshots. Tolgee is open
    source and can be self-hosted; this specification targets Tolgee Cloud at
    https://app.tolgee.io. Project-scoped resources are authenticated with a
    Project API key (prefixed `tgpak_`) sent in the `X-API-Key` header. A
    Project API key is bound to a single project, so endpoints that implicitly
    operate on "the current project" (such as export) are accessible when
    authenticated with that key.
  termsOfService: https://tolgee.io/terms_and_conditions
  contact:
    name: Tolgee Support
    email: support@tolgee.io
  license:
    name: Source available / AGPL and commercial (self-hosted)
    url: https://docs.tolgee.io/platform/self_hosting/licensing
  version: v2
servers:
  - url: https://app.tolgee.io
    description: Tolgee Cloud
tags:
  - name: Projects
    description: Create and manage localization projects.
  - name: Keys
    description: Manage translation keys within a project.
  - name: Translations
    description: Read and write translations and their states.
  - name: Languages
    description: Manage project languages (locales).
  - name: Import/Export
    description: Export localization files and import translation data.
  - name: Screenshots
    description: Attach visual context screenshots to keys.
  - name: API Keys
    description: Inspect the current API key.
security:
  - ApiKeyAuth: []
paths:
  /v2/api-keys/current:
    get:
      operationId: getCurrentApiKey
      tags:
        - API Keys
      summary: Get the current API key
      description: >-
        Returns information about the Project API key used to authenticate the
        request, including its scopes and associated project.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyModel'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/projects:
    get:
      operationId: getAllProjects
      tags:
        - Projects
      summary: List projects
      description: Returns a paginated list of projects the caller can access.
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - name: search
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedProjectsModel'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createProject
      tags:
        - Projects
      summary: Create a project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectModel'
        '400':
          $ref: '#/components/responses/BadRequest'
  /v2/projects/{projectId}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getProject
      tags:
        - Projects
      summary: Get a project
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectModel'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: editProject
      tags:
        - Projects
      summary: Update a project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectModel'
    delete:
      operationId: deleteProject
      tags:
        - Projects
      summary: Delete a project
      responses:
        '200':
          description: OK
  /v2/projects/{projectId}/keys:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getKeys
      tags:
        - Keys
      summary: List keys
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedKeysModel'
    post:
      operationId: createKey
      tags:
        - Keys
      summary: Create a key
      description: >-
        Creates a key and, optionally, its translations in one request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateKeyRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyModel'
        '400':
          $ref: '#/components/responses/BadRequest'
  /v2/projects/{projectId}/keys/{id}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
    delete:
      operationId: deleteKey
      tags:
        - Keys
      summary: Delete a key
      responses:
        '200':
          description: OK
  /v2/projects/{projectId}/keys/search:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: searchForKey
      tags:
        - Keys
      summary: Search for keys
      parameters:
        - name: search
          in: query
          required: true
          schema:
            type: string
        - name: languageTag
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedKeysModel'
  /v2/projects/{projectId}/keys/import:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: importKeys
      tags:
        - Keys
      summary: Import keys
      description: Bulk-creates keys with translations.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportKeysRequest'
      responses:
        '200':
          description: OK
  /v2/projects/{projectId}/translations:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getTranslations
      tags:
        - Translations
      summary: Get translations in project
      description: >-
        Returns a paginated, filterable view of keys and their translations.
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - name: languages
          in: query
          required: false
          description: Language tags to return; all languages if omitted.
          schema:
            type: array
            items:
              type: string
        - name: search
          in: query
          required: false
          schema:
            type: string
        - name: filterState
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              enum:
                - UNTRANSLATED
                - TRANSLATED
                - REVIEWED
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeysWithTranslationsPagedModel'
    put:
      operationId: setTranslations
      tags:
        - Translations
      summary: Update translations for an existing key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetTranslationsRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetTranslationsResponse'
    post:
      operationId: createOrUpdateTranslations
      tags:
        - Translations
      summary: Create a key or update its translations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetTranslationsRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetTranslationsResponse'
  /v2/projects/{projectId}/translations/{translationId}/set-state/{state}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: translationId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - name: state
        in: path
        required: true
        schema:
          type: string
          enum:
            - UNTRANSLATED
            - TRANSLATED
            - REVIEWED
    put:
      operationId: setTranslationState
      tags:
        - Translations
      summary: Set translation state
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranslationModel'
  /v2/projects/{projectId}/languages:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: getLanguages
      tags:
        - Languages
      summary: List languages
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedLanguagesModel'
    post:
      operationId: createLanguage
      tags:
        - Languages
      summary: Create a language
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LanguageRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LanguageModel'
  /v2/projects/{projectId}/languages/{languageId}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: languageId
        in: path
        required: true
        schema:
          type: integer
          format: int64
    put:
      operationId: editLanguage
      tags:
        - Languages
      summary: Update a language
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LanguageRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LanguageModel'
    delete:
      operationId: deleteLanguage
      tags:
        - Languages
      summary: Delete a language
      responses:
        '200':
          description: OK
  /v2/projects/export:
    get:
      operationId: exportData
      tags:
        - Import/Export
      summary: Export translations
      description: >-
        Exports the current project's translations as a downloadable archive
        (ZIP) or single file. The project is determined by the Project API key.
      parameters:
        - name: format
          in: query
          required: false
          description: Target file format.
          schema:
            type: string
            enum:
              - JSON
              - JSON_TOLGEE
              - XLIFF
              - PO
              - APPLE_STRINGS
              - APPLE_XLIFF
              - ANDROID_XML
              - FLUTTER_ARB
              - PROPERTIES
            default: JSON
        - name: languages
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
        - name: filterState
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              enum:
                - UNTRANSLATED
                - TRANSLATED
                - REVIEWED
        - name: filterNamespace
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
        - name: structureDelimiter
          in: query
          required: false
          description: Character that introduces nesting in structured output (empty disables nesting).
          schema:
            type: string
            default: '.'
        - name: zip
          in: query
          required: false
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: OK
          content:
            application/zip:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                type: object
                additionalProperties: true
  /v2/projects/{projectId}/import:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    post:
      operationId: addImportFiles
      tags:
        - Import/Export
      summary: Add files to import
      description: >-
        Uploads one or more translation files to begin the import process.
        Conflicts are resolved in subsequent steps before applying.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                files:
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
        '200':
          description: OK
  /v2/projects/{projectId}/import/apply:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
    put:
      operationId: applyImport
      tags:
        - Import/Export
      summary: Apply staged import
      parameters:
        - name: forceMode
          in: query
          required: false
          schema:
            type: string
            enum:
              - OVERRIDE
              - KEEP
              - 'NO'
      responses:
        '200':
          description: OK
  /v2/projects/{projectId}/keys/{keyId}/screenshots:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: keyId
        in: path
        required: true
        schema:
          type: integer
          format: int64
    get:
      operationId: getKeyScreenshots
      tags:
        - Screenshots
      summary: List screenshots for a key
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreenshotListModel'
    post:
      operationId: uploadScreenshot
      tags:
        - Screenshots
      summary: Upload a screenshot for a key
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                screenshot:
                  type: string
                  format: binary
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScreenshotModel'
  /v2/projects/{projectId}/keys/{keyId}/screenshots/{screenshotId}:
    parameters:
      - $ref: '#/components/parameters/ProjectId'
      - name: keyId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - name: screenshotId
        in: path
        required: true
        schema:
          type: integer
          format: int64
    delete:
      operationId: deleteScreenshot
      tags:
        - Screenshots
      summary: Delete a screenshot
      responses:
        '200':
          description: OK
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Project API key prefixed with `tgpak_`. Scoped to a single project.
  parameters:
    ProjectId:
      name: projectId
      in: path
      required: true
      description: Numeric project identifier.
      schema:
        type: integer
        format: int64
    Page:
      name: page
      in: query
      required: false
      description: Zero-based page index.
      schema:
        type: integer
        format: int32
        default: 0
    Size:
      name: size
      in: query
      required: false
      description: Page size.
      schema:
        type: integer
        format: int32
        default: 20
  responses:
    Unauthorized:
      description: Missing or invalid API key.
    BadRequest:
      description: Invalid request payload.
    NotFound:
      description: Resource not found.
  schemas:
    ApiKeyModel:
      type: object
      properties:
        id:
          type: integer
          format: int64
        description:
          type: string
        projectId:
          type: integer
          format: int64
        scopes:
          type: array
          items:
            type: string
        username:
          type: string
    CreateProjectRequest:
      type: object
      required:
        - name
        - languages
      properties:
        name:
          type: string
        slug:
          type: string
        description:
          type: string
        baseLanguageTag:
          type: string
        languages:
          type: array
          items:
            $ref: '#/components/schemas/LanguageRequest'
        organizationId:
          type: integer
          format: int64
    ProjectModel:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        slug:
          type: string
        description:
          type: string
        baseLanguage:
          $ref: '#/components/schemas/LanguageModel'
    PagedProjectsModel:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            projects:
              type: array
              items:
                $ref: '#/components/schemas/ProjectModel'
        page:
          $ref: '#/components/schemas/PageMeta'
    CreateKeyRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        namespace:
          type: string
        translations:
          type: object
          additionalProperties:
            type: string
          description: Map of language tag to translation text.
        tags:
          type: array
          items:
            type: string
    KeyModel:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        namespace:
          type: string
        tags:
          type: array
          items:
            type: string
    PagedKeysModel:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            keys:
              type: array
              items:
                $ref: '#/components/schemas/KeyModel'
        page:
          $ref: '#/components/schemas/PageMeta'
    ImportKeysRequest:
      type: object
      required:
        - keys
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/CreateKeyRequest'
    SetTranslationsRequest:
      type: object
      required:
        - key
        - translations
      properties:
        key:
          type: string
        namespace:
          type: string
        translations:
          type: object
          additionalProperties:
            type: string
          description: Map of language tag to translation text.
    SetTranslationsResponse:
      type: object
      properties:
        keyId:
          type: integer
          format: int64
        keyName:
          type: string
        translations:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/TranslationModel'
    TranslationModel:
      type: object
      properties:
        id:
          type: integer
          format: int64
        text:
          type: string
        state:
          type: string
          enum:
            - UNTRANSLATED
            - TRANSLATED
            - REVIEWED
        auto:
          type: boolean
        outdated:
          type: boolean
    KeysWithTranslationsPagedModel:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            keys:
              type: array
              items:
                type: object
                properties:
                  keyId:
                    type: integer
                    format: int64
                  keyName:
                    type: string
                  keyNamespace:
                    type: string
                  translations:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/TranslationModel'
        page:
          $ref: '#/components/schemas/PageMeta'
    LanguageRequest:
      type: object
      required:
        - name
        - tag
      properties:
        name:
          type: string
        tag:
          type: string
          description: BCP-47 language tag, e.g. en, de, fr-FR.
        originalName:
          type: string
        flagEmoji:
          type: string
    LanguageModel:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string
        originalName:
          type: string
        flagEmoji:
          type: string
        base:
          type: boolean
    PagedLanguagesModel:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            languages:
              type: array
              items:
                $ref: '#/components/schemas/LanguageModel'
        page:
          $ref: '#/components/schemas/PageMeta'
    ScreenshotModel:
      type: object
      properties:
        id:
          type: integer
          format: int64
        filename:
          type: string
        fileUrl:
          type: string
        width:
          type: integer
        height:
          type: integer
    ScreenshotListModel:
      type: object
      properties:
        _embedded:
          type: object
          properties:
            screenshots:
              type: array
              items:
                $ref: '#/components/schemas/ScreenshotModel'
    PageMeta:
      type: object
      properties:
        size:
          type: integer
          format: int32
        totalElements:
          type: integer
          format: int64
        totalPages:
          type: integer
          format: int32
        number:
          type: integer
          format: int32