General Translation Files API

openapi: 3.1.0
info:
  title: General Translation Branches Files 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: Files
  description: Upload, download, publish, move, and inspect project files.
paths:
  /v2/project/files/upload-files:
    post:
      tags:
      - Files
      summary: Upload source files
      description: Upload one or more source files to the project. Max 100 files per request.
      operationId: uploadSourceFiles
      parameters:
      - $ref: '#/components/parameters/GtApiVersion'
      - $ref: '#/components/parameters/GtProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: object
                    required:
                    - source
                    properties:
                      source:
                        $ref: '#/components/schemas/SourceFileInput'
                sourceLocale:
                  type: string
                  description: Overrides the project default source locale.
                  example: en
      responses:
        '201':
          description: Files uploaded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  uploadedFiles:
                    type: array
                    items:
                      type: object
                      properties:
                        branchId:
                          type: string
                        fileId:
                          type: string
                        versionId:
                          type: string
                        fileName:
                          type: string
                        fileFormat:
                          type: string
                        dataFormat:
                          type: string
                  count:
                    type: integer
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v2/project/files/upload-translations:
    post:
      tags:
      - Files
      summary: Upload translated files
      description: Upload translated files linked to their source files. Max 100 files per request.
      operationId: uploadTranslations
      parameters:
      - $ref: '#/components/parameters/GtApiVersion'
      - $ref: '#/components/parameters/GtProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: object
                    required:
                    - source
                    - translations
                    properties:
                      source:
                        $ref: '#/components/schemas/SourceFileInput'
                      translations:
                        type: array
                        minItems: 1
                        items:
                          type: object
                          required:
                          - content
                          - fileName
                          - fileFormat
                          - locale
                          properties:
                            content:
                              type: string
                              description: Base64-encoded translated file content.
                            fileName:
                              type: string
                            fileFormat:
                              type: string
                            locale:
                              type: string
                            dataFormat:
                              type: string
                            transformFormat:
                              type: string
                              description: Output file format transformation.
                sourceLocale:
                  type: string
                  description: Overrides the project default source locale.
      responses:
        '201':
          description: Translations uploaded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  uploadedFiles:
                    type: array
                    items:
                      type: object
                      properties:
                        branchId:
                          type: string
                        fileId:
                          type: string
                        versionId:
                          type: string
                        fileName:
                          type: string
                        locale:
                          type: string
                        fileFormat:
                          type: string
                        dataFormat:
                          type: string
                  count:
                    type: integer
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v2/project/files/diffs:
    post:
      tags:
      - Files
      summary: Submit translation diffs
      description: Overwrite translations with user-provided localized content.
      operationId: submitDiffs
      parameters:
      - $ref: '#/components/parameters/GtApiVersion'
      - $ref: '#/components/parameters/GtProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - diffs
              properties:
                projectId:
                  type: string
                  description: Ignored. The project ID comes from the authenticated API key.
                diffs:
                  type: array
                  minItems: 1
                  items:
                    type: object
                    required:
                    - locale
                    - diff
                    - versionId
                    - fileId
                    - localContent
                    properties:
                      locale:
                        type: string
                      diff:
                        type: string
                        description: Diff content.
                      branchId:
                        type: string
                      versionId:
                        type: string
                      fileId:
                        type: string
                      localContent:
                        type: string
                        description: Localized file content that overwrites the stored translation.
      responses:
        '200':
          description: Diffs processed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  filesProcessed:
                    type: integer
                  entriesReceived:
                    type: integer
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v2/project/files/publish:
    post:
      tags:
      - Files
      summary: Publish or unpublish files
      description: Publish or unpublish translated files to the CDN. Requires CDN to be enabled.
      operationId: publishFiles
      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
                    - publish
                    properties:
                      fileId:
                        type: string
                      versionId:
                        type: string
                      branchId:
                        type: string
                      publish:
                        type: boolean
                        description: True to publish, false to unpublish.
      responses:
        '200':
          description: Publish results per file.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        fileId:
                          type: string
                        versionId:
                          type: string
                        locale:
                          type: string
                        branchId:
                          type: string
                        success:
                          type: boolean
                        error:
                          type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/project/files/download/{fileId}:
    get:
      tags:
      - Files
      summary: Download a single file
      deprecated: true
      description: Download a single source or translated file. Prefer the batch POST endpoint.
      operationId: downloadFile
      parameters:
      - $ref: '#/components/parameters/GtApiVersion'
      - $ref: '#/components/parameters/GtProjectId'
      - name: fileId
        in: path
        required: true
        schema:
          type: string
      - name: versionId
        in: query
        schema:
          type: string
        description: Defaults to the branch head version.
      - name: branchId
        in: query
        schema:
          type: string
        description: Defaults to the default branch.
      - name: locale
        in: query
        schema:
          type: string
        description: Translation locale. Omit to download the source file.
      responses:
        '200':
          description: File content.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string
                    description: Base64-encoded file content.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/project/files/download:
    post:
      tags:
      - Files
      summary: Download multiple files
      description: Download up to 100 source or translated files in one request.
      operationId: downloadFiles
      parameters:
      - $ref: '#/components/parameters/GtApiVersion'
      - $ref: '#/components/parameters/GtProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              maxItems: 100
              items:
                type: object
                required:
                - fileId
                properties:
                  fileId:
                    type: string
                  branchId:
                    type: string
                  versionId:
                    type: string
                  locale:
                    type: string
                    description: Translation locale. Omit for the source file.
                  useLatestAvailableVersion:
                    type: boolean
      responses:
        '200':
          description: Downloaded files.
          content:
            application/json:
              schema:
                type: object
                properties:
                  files:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        branchId:
                          type: string
                        fileId:
                          type: string
                        versionId:
                          type: string
                        fileName:
                          type: string
                        data:
                          type: string
                          description: Base64-encoded content.
                        metadata:
                          type: object
                          additionalProperties: true
                        fileFormat:
                          type: string
                        locale:
                          type: string
                  count:
                    type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/project/files/info:
    post:
      tags:
      - Files
      summary: Get file metadata
      description: Get detailed metadata for specific source and translated files.
      operationId: getFileInfo
      parameters:
      - $ref: '#/components/parameters/GtApiVersion'
      - $ref: '#/components/parameters/GtProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sourceFiles:
                  type: array
                  items:
                    type: object
                    required:
                    - fileId
                    - versionId
                    - branchId
                    properties:
                      fileId:
                        type: string
                      versionId:
                        type: string
                      branchId:
                        type: string
                translatedFiles:
                  type: array
                  items:
                    type: object
                    required:
                    - fileId
                    - versionId
                    - branchId
                    - locale
                    properties:
                      fileId:
                        type: string
                      versionId:
                        type: string
                      branchId:
                        type: string
                      locale:
                        type: string
      responses:
        '200':
          description: File metadata.
          content:
            application/json:
              schema:
                type: object
                properties:
                  sourceFiles:
                    type: array
                    items:
                      type: object
                      properties:
                        branchId:
                          type: string
                        fileId:
                          type: string
                        versionId:
                          type: string
                        fileName:
                          type: string
                        fileFormat:
                          type: string
                        dataFormat:
                          type:
                          - string
                          - 'null'
                        createdAt:
                          type: string
                          format: date-time
                        updatedAt:
                          type: string
                          format: date-time
                        approvalRequiredAt:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        publishedAt:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        locales:
                          type: array
                          items:
                            type: string
                        sourceLocale:
                          type: string
                  translatedFiles:
                    type: array
                    items:
                      type: object
                      properties:
                        branchId:
                          type: string
                        fileId:
                          type: string
                        versionId:
                          type: string
                        fileFormat:
                          type: string
                        dataFormat:
                          type:
                          - string
                          - 'null'
                        createdAt:
                          type: string
                          format: date-time
                        updatedAt:
                          type: string
                          format: date-time
                        approvedAt:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        publishedAt:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        completedAt:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        locale:
                          type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/project/translations/files/status/{fileId}:
    get:
      tags:
      - Files
      summary: Get translation status for a file
      operationId: getTranslationStatus
      parameters:
      - $ref: '#/components/parameters/GtApiVersion'
      - $ref: '#/components/parameters/GtProjectId'
      - name: fileId
        in: path
        required: true
        schema:
          type: string
      - name: versionId
        in: query
        schema:
          type: string
        description: Defaults to the branch head version.
      - name: branchId
        in: query
        schema:
          type: string
        description: Defaults to the default branch.
      responses:
        '200':
          description: Translation status for the file.
          content:
            application/json:
              schema:
                type: object
                properties:
                  translations:
                    type: array
                    items:
                      type: object
                      properties:
                        locale:
                          type: string
                        completedAt:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        approvedAt:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        publishedAt:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        createdAt:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        updatedAt:
                          type:
                          - string
                          - 'null'
                          format: date-time
                  sourceFile:
                    type: object
                    properties:
                      id:
                        type: string
                      branchId:
                        type: string
                      fileId:
                        type: string
                      versionId:
                        type: string
                      fileName:
                        type: string
                      sourceLocale:
                        type: string
                      fileFormat:
                        type: string
                      dataFormat:
                        type:
                        - string
                        - 'null'
                      createdAt:
                        type: string
                        format: date-time
                      updatedAt:
                        type: string
                        format: date-time
                      approvalRequiredAt:
                        type:
                        - string
                        - 'null'
                        format: date-time
                      locales:
                        type: array
                        items:
                          type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/project/files/moves:
    post:
      tags:
      - Files
      summary: Move or rename files
      description: Clone source files and their translations under new file IDs.
      operationId: moveFiles
      parameters:
      - $ref: '#/components/parameters/GtApiVersion'
      - $ref: '#/components/parameters/GtProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - moves
              properties:
                branchId:
                  type: string
                  description: Defaults to the default branch.
                moves:
                  type: array
                  items:
                    type: object
                    required:
                    - oldFileId
                    - newFileId
                    - newFileName
                    properties:
                      oldFileId:
                        type: string
                        minLength: 1
                      newFileId:
                        type: string
                        minLength: 1
                      newFileName:
                        type: string
                        minLength: 1
      responses:
        '200':
          description: Move results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        oldFileId:
                          type: string
                        newFileId:
                          type: string
                        success:
                          type: boolean
                        error:
                          type: string
                  summary:
                    type: object
                    properties:
                      total:
                        type: integer
                      succeeded:
                        type: integer
                      failed:
                        type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/project/files/orphaned:
    post:
      tags:
      - Files
      summary: Find orphaned files
      description: Return files on a branch that are not present in the provided file ID list.
      operationId: getOrphanedFiles
      parameters:
      - $ref: '#/components/parameters/GtApiVersion'
      - $ref: '#/components/parameters/GtProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - branchId
              properties:
                branchId:
                  type: string
                fileIds:
                  type: array
                  default: []
                  items:
                    type: string
      responses:
        '200':
          description: Orphaned files.
          content:
            application/json:
              schema:
                type: object
                properties:
                  orphanedFiles:
                    type: array
                    items:
                      type: object
                      properties:
                        fileId:
                          type: string
                        versionId:
                          type: string
                        fileName:
                          type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    ServiceUnavailable:
      description: The server is temporarily busy.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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'
    RateLimited:
      description: Rate limit or quota exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message.
    SourceFileInput:
      type: object
      required:
      - content
      - fileName
      - fileFormat
      - locale
      properties:
        content:
          type: string
          description: Base64-encoded file content.
        fileName:
          type: string
        fileFormat:
          type: string
          description: File format, e.g. json, yaml, xml.
        dataFormat:
          type: string
          description: Data format, e.g. STRING, JSX, ICU.
        locale:
          type: string
          description: Source locale code.
        fileId:
          type: string
          description: Derived from the file name when omitted.
        versionId:
          type: string
          description: Derived from the content hash when omitted.
        branchId:
          type: string
          description: Defaults to the default branch.
        checkedOutBranchId:
          type: string
        incomingBranchId:
          type: string
        formatMetadata:
          type: object
          additionalProperties: true
  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
  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.

        '