openapi: 3.0.3
info:
  title: Gengo Account Job API
  version: '2.0'
  description: The Gengo API (v2) lets you programmatically order human translation. Submit text or file jobs, group them into orders, retrieve translated content, manage comments and revisions, run quotes, look up supported language pairs, and manage glossaries. Jobs move through a defined status lifecycle (queued -> available -> pending -> reviewable -> approved) and can notify your system via callback URLs. Authentication uses a public api_key plus an HMAC-SHA1 signature (api_sig) computed over a Unix timestamp (ts) with your private key.
  contact:
    name: Gengo Support
    url: https://developers.gengo.com
    email: support@gengo.com
  termsOfService: https://gengo.com/terms-of-service/
  x-apis-json:
    generated: '2026-07-19'
    method: generated
    source: https://developers.gengo.com/v2/api_methods/
    note: Faithfully generated from the published Gengo API v2 reference (endpoints, HTTP methods, summaries, parameters and response envelope documented at developers.gengo.com). Gengo does not publish an OpenAPI/Swagger file.
servers:
- url: https://api.gengo.com/v2
  description: Production
- url: http://api.sandbox.gengo.com/v2
  description: Sandbox (test environment; free test credits, faux-translator triggers)
security:
- ApiKey: []
tags:
- name: Job
  description: Operations on a single translation job.
paths:
  /translate/job/{id}:
    get:
      tags:
      - Job
      operationId: getJob
      summary: Retrieves a specific job.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Job id.
      responses:
        '200':
          description: Job envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        default:
          $ref: '#/components/responses/Error'
    put:
      tags:
      - Job
      operationId: updateJob
      summary: Updates a job (approve, reject, revise, or purchase a reviewable job).
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Job id.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                data:
                  type: string
                  description: JSON-encoded action (e.g. {"action":"approve"|"reject"|"revise"|"purchase"}).
      responses:
        '200':
          description: Update result envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        default:
          $ref: '#/components/responses/Error'
    delete:
      tags:
      - Job
      operationId: cancelJob
      summary: Cancels the job. You can only cancel a job if it has not been started by a translator.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Job id.
      responses:
        '200':
          description: Cancellation result envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        default:
          $ref: '#/components/responses/Error'
  /translate/job/{id}/revisions:
    get:
      tags:
      - Job
      operationId: getJobRevisions
      summary: Gets list of revision resources for a job.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Job id.
      responses:
        '200':
          description: Revisions envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        default:
          $ref: '#/components/responses/Error'
  /translate/job/{id}/revision/{rev_id}:
    get:
      tags:
      - Job
      operationId: getJobRevision
      summary: Gets a specific revision for a job.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Job id.
      - name: rev_id
        in: path
        required: true
        schema:
          type: integer
        description: Revision id.
      responses:
        '200':
          description: Revision envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        default:
          $ref: '#/components/responses/Error'
  /translate/job/{id}/feedback:
    get:
      tags:
      - Job
      operationId: getJobFeedback
      summary: Retrieves the feedback you have submitted for a particular job.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Job id.
      responses:
        '200':
          description: Feedback envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        default:
          $ref: '#/components/responses/Error'
  /translate/job/{id}/comments:
    get:
      tags:
      - Job
      operationId: getJobComments
      summary: Retrieves the comment thread for a job.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Job id.
      responses:
        '200':
          description: Comment thread envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        default:
          $ref: '#/components/responses/Error'
  /translate/job/{id}/comment:
    post:
      tags:
      - Job
      operationId: postJobComment
      summary: Submits a new comment to the job's comment thread.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        description: Job id.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                data:
                  type: string
                  description: JSON-encoded comment body, e.g. {"body":"Please use British spelling"}.
      responses:
        '200':
          description: Comment result envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        default:
          $ref: '#/components/responses/Error'
components:
  responses:
    Error:
      description: Error envelope (opstat=error) carrying a numeric Gengo error code.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        opstat:
          type: string
          example: error
        err:
          type: object
          properties:
            code:
              type: integer
              example: 1100
            msg:
              type: string
              example: api_sig is a required field
      required:
      - opstat
      - err
    Envelope:
      type: object
      properties:
        opstat:
          type: string
          enum:
          - ok
          - error
        response:
          type: object
      required:
      - opstat
  securitySchemes:
    ApiKey:
      type: apiKey
      in: query
      name: api_key
      description: Public API key identifying the account. Every authenticated call must also include `ts` (Unix epoch) and `api_sig` (HMAC-SHA1 of `ts` keyed by the account private key). Keys are created on the account API settings page.