General Translation Tags API

openapi: 3.2.0
info:
  title: General Translation Branches Tags API
  version: 2026-03-06.v1
  description: 'The public General Translation API. Use it to upload source content and translated files, download translations, queue and translate content, manage branches and tags, and read project and job status.


    Most endpoints operate on a single project and live under `https://api2.gtx.dev`. The runtime translation endpoint (`POST /v2/translate`) is served from `https://runtime2.gtx.dev`.


    Authenticate every request with an API key as a bearer token in the standard `Authorization: Bearer <key>` header. Project keys (`gtx-api-`, `gtx-dev-`) are bound to one project. Organization keys (`gtx-org-`) work across projects but must include the target project in the `gt-project-id` header for project-scoped routes.

    '
  contact:
    name: General Translation Support
    email: support@generaltranslation.com
    url: https://generaltranslation.com
servers:
- url: https://api2.gtx.dev
  description: Project and file API
- url: https://runtime2.gtx.dev
  description: Runtime translation API (POST /v2/translate)
security:
- Bearer: []
tags:
- name: Tags
  description: Tag file versions.
paths:
  /v2/project/tags/create:
    post:
      tags:
      - Tags
      summary: Create or update a tag
      description: Create or upsert a tag that points at a set of file versions.
      operationId: createTag
      parameters:
      - $ref: '#/components/parameters/GtApiVersion'
      - $ref: '#/components/parameters/GtProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - tagId
              - files
              properties:
                tagId:
                  type: string
                  minLength: 1
                  maxLength: 255
                files:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    required:
                    - fileId
                    - versionId
                    - branchId
                    properties:
                      fileId:
                        type: string
                        minLength: 1
                      versionId:
                        type: string
                        minLength: 1
                      branchId:
                        type: string
                        minLength: 1
                message:
                  type: string
                  maxLength: 255
      responses:
        '200':
          description: Created or updated tag.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tag:
                    type: object
                    properties:
                      id:
                        type: string
                      tagId:
                        type: string
                      message:
                        type: string
                      createdAt:
                        type: string
                        format: date-time
                      updatedAt:
                        type: string
                        format: date-time
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  responses:
    BadRequest:
      description: The request was invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The API key lacks the required permission, or the action is not allowed on the current plan.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    GtProjectId:
      name: gt-project-id
      in: header
      required: false
      description: Target project ID. Required when authenticating with an organization API key.
      schema:
        type: string
    GtApiVersion:
      name: gt-api-version
      in: header
      required: false
      description: 'API version. Defaults to the earliest supported version. Latest is `2026-03-06.v1`.

        '
      schema:
        type: string
        enum:
        - 2025-01-01.v0
        - 2025-11-03.v1
        - 2026-02-18.v1
        - 2026-03-06.v1
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message.
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      description: 'API key sent as a bearer token in the standard `Authorization: Bearer <key>` header. Use a project key (`gtx-api-`, `gtx-dev-`) or an organization key (`gtx-org-`). Organization keys must also send `gt-project-id` on project-scoped routes.

        '