General Translation Context API

openapi: 3.1.0
info:
  title: General Translation Branches Context 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: Context
  description: Generate translation context such as glossaries and instructions.
paths:
  /v2/project/setup/should-generate:
    get:
      tags:
      - Context
      summary: Check if context generation is needed
      deprecated: true
      operationId: shouldGenerateContext
      parameters:
      - $ref: '#/components/parameters/GtApiVersion'
      - $ref: '#/components/parameters/GtProjectId'
      responses:
        '200':
          description: Whether context generation is recommended.
          content:
            application/json:
              schema:
                type: object
                properties:
                  shouldSetupProject:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/project/setup/generate:
    post:
      tags:
      - Context
      summary: Generate translation context
      description: Generate glossaries and translation instructions for the project.
      operationId: generateContext
      parameters:
      - $ref: '#/components/parameters/GtApiVersion'
      - $ref: '#/components/parameters/GtProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - files
              properties:
                files:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    required:
                    - fileId
                    - versionId
                    properties:
                      branchId:
                        type: string
                      fileId:
                        type: string
                      versionId:
                        type: string
                locales:
                  type: array
                  items:
                    type: string
                  description: Target locales for glossary generation.
                force:
                  type: boolean
                  default: false
      responses:
        '200':
          description: Context generation queued or completed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  setupJobId:
                    type: string
                  status:
                    type: string
                    enum:
                    - queued
                    - completed
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/project/setup/status/{jobId}:
    get:
      tags:
      - Context
      summary: Get context generation job status
      deprecated: true
      operationId: getContextStatus
      parameters:
      - $ref: '#/components/parameters/GtApiVersion'
      - $ref: '#/components/parameters/GtProjectId'
      - name: jobId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Context job status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobId:
                    type: string
                  status:
                    type: string
                    enum:
                    - queued
                    - processing
                    - completed
                    - failed
                    - unknown
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message.
  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
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      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'
  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.

        '