openapi: 3.0.3
info:
  title: Gengo Account Jobs 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: Jobs
  description: Submit and manage groups of translation jobs.
paths:
  /translate/jobs:
    post:
      tags:
      - Jobs
      operationId: postJobs
      summary: Submits a job or group of jobs to translate. Request should be no larger than 100MB.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                data:
                  type: string
                  description: JSON-encoded jobs payload (a `jobs` map plus optional `as_group`, `process`).
      responses:
        '200':
          description: Submitted order/jobs envelope (order_id + job ids)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        default:
          $ref: '#/components/responses/Error'
    get:
      tags:
      - Jobs
      operationId: getJobs
      summary: Retrieves a list of resources for the most recent jobs filtered by the given parameters.
      parameters:
      - name: status
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/JobStatus'
        description: Filter by job status.
      - name: timestamp_after
        in: query
        required: false
        schema:
          type: integer
        description: Epoch time; only jobs created after this time.
      - name: count
        in: query
        required: false
        schema:
          type: integer
        description: Maximum number of jobs to return.
      responses:
        '200':
          description: List of recent job resources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        default:
          $ref: '#/components/responses/Error'
    put:
      tags:
      - Jobs
      operationId: updateJobs
      summary: Updates a group of jobs to translate. Request should be no larger than 100MB.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                data:
                  type: string
                  description: JSON-encoded action + job_ids.
      responses:
        '200':
          description: Update result envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        default:
          $ref: '#/components/responses/Error'
  /translate/jobs/{ids}:
    get:
      tags:
      - Jobs
      operationId: getJobsByIds
      summary: Retrieves a list of jobs requested by a comma-separated list of job ids.
      parameters:
      - name: ids
        in: path
        required: true
        schema:
          type: string
        description: Comma-separated list of job ids.
      responses:
        '200':
          description: Jobs 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
    JobStatus:
      type: string
      enum:
      - queued
      - available
      - pending
      - reviewable
      - approved
      - revising
      - rejected
      - canceled
      - hold
      description: The lifecycle status of a translation job.
  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.