Orbit Translations API
An app's languages — read what is translated and run the translator
An app's languages — read what is translated and run the translator
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/orbitapps-io:orbitapps-io-translations-api"
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.
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: 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