Orbit Translations API

An app's languages — read what is translated and run the translator

GitHub OpenAPI

Operations 2

GET /api/v1/apps/{app_id}/translations Read an app's translations #
POST /api/v1/apps/{app_id}/translations Translate an app into one language #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/orbitapps-io:orbitapps-io-translations-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

orbitapps-io-translations-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Orbit Apps Translations API
  version: 1.0.0
  description: Public REST API for Orbit Apps.
servers:
- url: https://api.orbitapps.io
  description: Production
security:
- bearerAuth: []
tags:
- name: Translations
  description: An app's languages — read what is translated and run the translator
paths:
  /api/v1/apps/{app_id}/translations:
    get:
      parameters:
      - in: path
        name: app_id
        required: true
        schema:
          type: string
          format: uuid
        description: App id from GET /api/v1/apps
      - in: query
        name: locale
        required: false
        schema:
          type: string
        description: Restrict to one language. Omit for a per-language summary.
      - in: query
        name: pending
        required: false
        schema:
          type: boolean
        description: Return the strings this language still needs instead of the ones it has — the authored English awaiting a translation, each with the `source_key` a translation is submitted under. Ignores `status`.
      - in: query
        name: status
        required: false
        schema:
          type: string
          enum:
          - machine
          - reviewed
          - stale
        description: Only stored strings with this review status. Ignored with `pending`.
      - in: query
        name: run_id
        required: false
        schema:
          type: string
          format: uuid
        description: Report this exact run rather than the language's newest.
      - in: query
        name: limit
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
        description: Strings per page, 1-200 (default 50). Detect the end when strings.length < limit.
      - in: query
        name: offset
        required: false
        schema:
          type: integer
          minimum: 0
        description: Rows to skip (default 0).
      responses:
        '200':
          description: The app's languages, and either a summary of all or the detail of one.
          content:
            application/json:
              schema:
                title: TranslationsRead
                description: 'One shape whether or not the request names a language. With `locale`: `plan`, `run` and `strings` describe that one. Without it: `summary` carries a row per available language and `strings` is empty.'
                type: object
                properties:
                  locales:
                    title: AppLocales
                    description: The languages the app serves. Written through PATCH /api/v1/apps/{id}.
                    type: object
                    properties:
                      active:
                        description: The language the app is authored in. Never translated into itself.
                        type: string
                      available:
                        description: The other languages it offers.
                        type: array
                        items:
                          type: string
                      glossary:
                        description: Names a model must not translate, such as the product's own.
                        type: array
                        items:
                          type: string
                    required:
                    - active
                    - available
                    - glossary
                    additionalProperties: false
                  locale:
                    description: The language this reply describes, or null when it describes all of them.
                    oneOf:
                    - type: string
                    - type: 'null'
                  plan:
                    oneOf:
                    - title: TranslationPlan
                      description: What a run would do for one language, costing nothing to ask.
                      type: object
                      properties:
                        total:
                          description: Distinct authored strings in the app.
                          type: integer
                        pending:
                          description: How many of them this language still needs. 0 means nothing to run.
                          type: integer
                        orphans:
                          description: Stored strings the app no longer contains. Reported, never deleted.
                          type: integer
                      required:
                      - total
                      - pending
                      - orphans
                      additionalProperties: false
                    - type: 'null'
                  run:
                    oneOf:
                    - title: TranslationRun
                      description: One run of one language, in the uniform async-job shape.
                      type: object
                      properties:
                        id:
                          description: Run id, the same value POST answered with.
                          type: string
                        locale:
                          type: string
                        status:
                          description: queued → running → succeeded | failed | cancelled.
                          type: string
                          enum:
                          - queued
                          - running
                          - succeeded
                          - failed
                          - cancelled
                        attempt:
                          description: Which attempt is current; a failed run is retried up to max_attempts.
                          type: integer
                        max_attempts:
                          type: integer
                        error:
                          description: The last failure this run recorded, when it has one.
                          oneOf:
                          - type: string
                          - type: 'null'
                      required:
                      - id
                      - locale
                      - status
                      - attempt
                      - max_attempts
                      - error
                      additionalProperties: false
                    - type: 'null'
                  summary:
                    type: array
                    items:
                      title: TranslationSummary
                      description: One language's state. Present for every available language when the request names none.
                      type: object
                      properties:
                        locale:
                          type: string
                        total:
                          type: integer
                        pending:
                          type: integer
                        orphans:
                          type: integer
                        run_status:
                          description: How this language's newest run ended, or null when it has never had one.
                          oneOf:
                          - type: string
                            enum:
                            - queued
                            - running
                            - succeeded
                            - failed
                            - cancelled
                          - type: 'null'
                      required:
                      - locale
                      - total
                      - pending
                      - orphans
                      - run_status
                      additionalProperties: false
                  strings:
                    type: array
                    items:
                      title: Translation
                      description: One string of this language. A translated one carries its `content`; one the request asked for with `pending` has none yet, and its stored-only fields are null — there is no row until something translates it.
                      type: object
                      properties:
                        format:
                          description: '`plain` for body copy, `attribute` for a placeholder, alt or aria-* value.'
                          type: string
                        locale:
                          type: string
                        content:
                          description: The translation, or null when there is none yet.
                          oneOf:
                          - type: string
                          - type: 'null'
                        source:
                          description: The authored English.
                          type: string
                        updated_at:
                          oneOf:
                          - type: string
                          - type: 'null'
                        source_key:
                          description: Hash of the authored string, and the key a translation is submitted under. Stable across restyling and re-use, so a re-run never re-bills it.
                          type: string
                        status:
                          description: '`reviewed` is a person''s own wording, and no run overwrites it. Null when untranslated.'
                          oneOf:
                          - type: string
                            enum:
                            - machine
                            - reviewed
                            - stale
                          - type: 'null'
                        id:
                          description: Null for a string nothing has translated yet.
                          oneOf:
                          - type: string
                          - type: 'null'
                        context:
                          description: The author's disambiguator, when they wrote one.
                          oneOf:
                          - type: string
                          - type: 'null'
                      required:
                      - id
                      - locale
                      - source_key
                      - source
                      - content
                      - status
                      - format
                      - context
                      - updated_at
                      additionalProperties: false
                  limit:
                    type: integer
                  offset:
                    type: integer
                required:
                - locales
                - locale
                - plan
                - run
                - summary
                - strings
                - limit
                - offset
                additionalProperties: false
        '404':
          description: App does not exist, or the caller has no visibility.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                additionalProperties: false
      tags:
      - Translations
      summary: Read an app's translations
      description: 'Everything about one app''s languages in one request: which it offers, how much of each is translated, how its newest run is going, and the stored strings.


        Omit `locale` for a `summary` row per available language, each with its `run_status` — the call to make first. Pass `locale` for that one language''s `plan`, its `run`, and the stored strings themselves.


        Add `pending=true` and `strings` carries what the language still NEEDS instead: the authored English awaiting translation, each with the `source_key` to submit it under. That is the read for a caller who intends to translate the app itself — POST them back as `strings`.


        `plan.pending` is what a run would still have to do, so a client that started one re-reads this until `pending` reaches 0 or `run.status` turns terminal. `run` is the newest run of that language unless `run_id` names another.


        Pagination is offset-based over `strings`; the response carries no total count. Detect the end when `strings.length < limit`.


        Visibility mirrors GET /api/v1/apps/{id}: 404 opacity for non-members.'
      operationId: getApiV1AppsByAppIdTranslations
      x-operation-id-source: derived
    post:
      parameters:
      - in: path
        name: app_id
        required: true
        schema:
          type: string
          format: uuid
        description: App id from GET /api/v1/apps
      requestBody:
        content:
          application/json:
            schema:
              title: TranslationRunStart
              description: Which language to translate, and whether to redo what a machine already did.
              type: object
              properties:
                locale:
                  description: A language from the app's `available` list. The authored language is refused.
                  type: string
                force:
                  description: Re-translate rows a previous run wrote. Reviewed rows are never redone. Default false. Ignored with `strings`.
                  type: boolean
                strings:
                  description: 'Translations you already have, as `{source_key: text}` — the keys come from this endpoint''s `pending` read. Sending them STORES them instead of starting a run, so no model is asked and the org''s provider is not needed at all. A key the app''s text no longer hashes to is named back rather than stored, and a string a person reviewed is left alone.'
                  type: object
                  additionalProperties:
                    type: string
                    minLength: 1
                model:
                  description: Who produced those translations, recorded on each row as its only trace of provenance — a model id such as `claude-opus-5`. Defaults to `caller-supplied`. Only read with `strings`.
                  type: string
                  maxLength: 100
              required:
              - locale
              additionalProperties: false
      responses:
        '202':
          description: The queued run.
          content:
            application/json:
              schema:
                title: TranslationRunStarted
                description: What the request did, and what the language still needs afterwards.
                type: object
                properties:
                  run_id:
                    description: The run to watch, or null when nothing was started — nothing was outstanding, or you supplied the strings yourself.
                    oneOf:
                    - type: string
                    - type: 'null'
                  stored:
                    description: How many supplied strings were saved. 0 when a run was started instead.
                    type: integer
                  unknown:
                    description: Supplied keys the app's text no longer hashes to. Named rather than stored, because a row under one is a translation nothing would ever look up.
                    type: array
                    items:
                      type: string
                  locale:
                    type: string
                  status:
                    type: string
                    enum:
                    - queued
                    - running
                    - succeeded
                    - failed
                    - cancelled
                  total:
                    type: integer
                  pending:
                    type: integer
                required:
                - run_id
                - stored
                - unknown
                - locale
                - status
                - total
                - pending
                additionalProperties: false
        '200':
          description: Supplied strings were stored, or nothing was outstanding — either way no run was started and nothing was spent.
          content:
            application/json:
              schema:
                title: TranslationRunStarted
                description: What the request did, and what the language still needs afterwards.
                type: object
                properties:
                  run_id:
                    description: The run to watch, or null when nothing was started — nothing was outstanding, or you supplied the strings yourself.
                    oneOf:
                    - type: string
                    - type: 'null'
                  stored:
                    description: How many supplied strings were saved. 0 when a run was started instead.
                    type: integer
                  unknown:
                    description: Supplied keys the app's text no longer hashes to. Named rather than stored, because a row under one is a translation nothing would ever look up.
                    type: array
                    items:
                      type: string
                  locale:
                    type: string
                  status:
                    type: string
                    enum:
                    - queued
                    - running
                    - succeeded
                    - failed
                    - cancelled
                  total:
                    type: integer
                  pending:
                    type: integer
                required:
                - run_id
                - stored
                - unknown
                - locale
                - status
                - total
                - pending
                additionalProperties: false
        '403':
          description: Caller has visibility but lacks the role to write.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                additionalProperties: false
        '404':
          description: App does not exist, or the caller has no visibility.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                additionalProperties: false
        '422':
          description: The language is not offered, is the authored one, or the org has no AI provider connected.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                additionalProperties: false
      tags:
      - Translations
      summary: Translate an app into one language
      description: 'Two ways to fill a language, and the body decides which.


        WITH `strings` — `{source_key: text}`, the keys from this endpoint''s `pending` read — the translations are STORED and no model is asked. No AI provider is needed, nothing is spent, and a caller that is itself a translator can fill an app this way. A key the app''s text no longer hashes to comes back in `unknown` rather than being stored; a string a person reviewed is left alone. Rows are written `machine` and carry `model`, so a later forced run may still redo them.


        WITHOUT `strings` — starts a run and answers 202 immediately with its `run_id`. A run takes minutes: progress arrives through GET /api/v1/apps/{app_id}/translations?locale=, where `run.status` moves queued → running → succeeded | failed and `plan.pending` falls as strings land.


        The language must already be on the app''s `available` list; add it with PATCH /api/v1/apps/{id} first. The app''s own authored language is refused — its pages already serve that text.


        A run is idempotent by construction: it translates what is outstanding and skips what is stored, so re-running after a failure pays only for the remainder, and a run with nothing outstanding answers 200 without starting anything. A string a person corrected is never overwritten, `force` included.


        A run asks the org''s own provider, on its own plan. With none connected a RUN is refused with 422 rather than enqueued — supplying `strings` needs no provider and is never refused for that.


        Authorization: `[:write :resource]` (owner/admin/member); viewer is rejected with 403. Supports the `Idempotency-Key` header.'
      operationId: postApiV1AppsByAppIdTranslations
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: opaque
      description: 'An Orbit api token, sent as `Authorization: Bearer <token>`.


        Mint one with the RFC 8628 device-authorization grant (`POST /api/v1/device/code`, then poll `POST /api/v1/device/token`), or from Studio.


        Every token carries a scope set from the `[verb resource]` RBAC catalog — `read:app`, `write:deployment`, `manage:secret`, and so on. The full vocabulary is published as `scopes_supported` at `/.well-known/oauth-protected-resource` (RFC 9728) and `/.well-known/oauth-authorization-server` (RFC 8414). Grant an agent the narrowest set that does its job.'
externalDocs:
  description: Full documentation
  url: https://docs.orbitapps.io
x-id:
- reitit.openapi/default