openapi: 3.0.1
info:
  title: Lingo.dev Engine Account Asynchronous API
  description: REST API for the Lingo.dev (formerly Replexica) hosted Localization Engine. Synchronous operations localize, recognize, and estimate key-value content in a single request; the asynchronous jobs API submits content and a set of target locales and creates a job group with one independent job per locale, with results delivered via polling, webhook, or WebSocket. All requests are authenticated with an organization-scoped API key sent in the X-API-Key header.
  termsOfService: https://lingo.dev/en/terms
  contact:
    name: Lingo.dev Support
    url: https://lingo.dev
  version: '1.0'
servers:
- url: https://api.lingo.dev
  description: Lingo.dev Localization Engine
security:
- ApiKeyAuth: []
tags:
- name: Asynchronous
paths:
  /jobs/localization:
    post:
      operationId: createLocalizationJobGroup
      tags:
      - Asynchronous
      summary: Create an asynchronous localization job group
      description: Submits content and a list of target locales. Creates a job group with one independent background job per locale and returns 202 with the group ID and per-locale job summaries. Results are delivered per locale via polling, webhook, or WebSocket as each job completes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJobGroupRequest'
      responses:
        '202':
          description: Accepted. Job group created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobGroup'
        '401':
          description: Missing or invalid API key.
        '422':
          description: Invalid request payload.
    get:
      operationId: listLocalizationJobs
      tags:
      - Asynchronous
      summary: List localization jobs
      description: Lists localization jobs with pagination and filtering.
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
        description: Maximum number of jobs to return.
      - name: cursor
        in: query
        schema:
          type: string
        description: Pagination cursor.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobList'
  /jobs/localization/{groupId}:
    get:
      operationId: getLocalizationJobGroup
      tags:
      - Asynchronous
      summary: Get a localization job group
      description: Retrieves the status of a localization job group and its per-locale jobs.
      parameters:
      - name: groupId
        in: path
        required: true
        schema:
          type: string
        description: The ID of the job group to retrieve.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobGroup'
        '404':
          description: Job group not found.
components:
  schemas:
    CreateJobGroupRequest:
      type: object
      required:
      - data
      - targetLocales
      properties:
        sourceLocale:
          type: string
          nullable: true
          example: en
        targetLocales:
          type: array
          items:
            type: string
          description: One job is created per target locale.
          example:
          - es
          - fr
          - de
        data:
          type: object
          additionalProperties:
            type: string
        webhookUrl:
          type: string
          description: Optional URL to receive per-locale completion events.
    JobList:
      type: object
      properties:
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/Job'
        nextCursor:
          type: string
          nullable: true
    Job:
      type: object
      properties:
        jobId:
          type: string
        targetLocale:
          type: string
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
        data:
          type: object
          additionalProperties:
            type: string
          description: Localized output (present when completed).
    JobGroup:
      type: object
      properties:
        groupId:
          type: string
          description: Identifier of the job group.
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - partial
          - failed
          description: Aggregate status; partial when some locale jobs fail.
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/Job'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key