Because translation is asynchronous, callers can supply a callback_url when creating a translation and Unbabel will POST a notification to that HTTP endpoint when the job changes status (for example completed). This is a server-to-endpoint webhook callback, not a WebSocket; the exact payload shape is modeled from the documented callback behavior.
openapi: 3.0.3
info:
title: Unbabel Translation API
description: >-
The Unbabel Translation API (tapi/v2) is an asynchronous REST API for the
Unbabel Language Operations (LangOps) platform. Callers submit text with a
source/target language pair, tone, and topic; Unbabel returns a job
identifier (uid) immediately and processes the translation with always-on AI
plus optional human review. Results are retrieved by uid, by listing jobs by
status, or delivered to a callback URL. The API also exposes a pure
machine-translation path (mt_translation) and helper resources for language
pairs, tones, topics, word count, and account details.
Authentication uses a token header of the form
`Authorization: ApiKey <username>:<api_key>`. The production base URL is
https://api.unbabel.com/tapi/v2 and a sandbox is available at
https://sandbox.unbabel.com/tapi/v2. Endpoints for translation,
mt_translation, language_pair, tone, topic, account, and wordcount are
confirmed from Unbabel's public developer docs and the official unbabel-py
client; the asynchronous callback (webhook) payload is modeled from the
documented callback behavior.
version: '2.0'
contact:
name: Unbabel Developers
url: https://developers.unbabel.com
servers:
- url: https://api.unbabel.com/tapi/v2
description: Production
- url: https://sandbox.unbabel.com/tapi/v2
description: Sandbox
security:
- apiKeyAuth: []
tags:
- name: Translation
description: Submit and manage AI-plus-human translation jobs.
- name: Machine Translation
description: Pure machine-translation jobs, optionally upgradeable to human review.
- name: Language Pairs
description: Supported source-to-target language combinations.
- name: Tone and Topic
description: Available tones and topics/domains for a translation.
- name: Word Count
description: Billable word count calculation for a block of text.
- name: Account
description: Authenticated customer account information.
paths:
/translation/:
get:
operationId: listTranslations
tags:
- Translation
summary: List translations
description: Lists translation jobs, optionally filtered by status.
parameters:
- name: status
in: query
required: false
schema:
type: string
enum: [new, accepted, translating, delivered, canceled, failed]
description: Filter jobs by their current status.
responses:
'200':
description: A list of translation jobs.
content:
application/json:
schema:
type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/Translation'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createTranslation
tags:
- Translation
summary: Submit a translation
description: >-
Asynchronously submits text for translation. Returns immediately with the
job uid and status; the completed translation is retrieved later by uid or
delivered to the optional callback_url.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TranslationRequest'
responses:
'201':
description: The created translation job.
content:
application/json:
schema:
$ref: '#/components/schemas/Translation'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
patch:
operationId: bulkUpdateTranslations
tags:
- Translation
summary: Bulk translation operations
description: Submits or updates multiple translation jobs in a single request.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/TranslationRequest'
responses:
'202':
description: Bulk request accepted.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/translation/{uid}/:
get:
operationId: getTranslation
tags:
- Translation
summary: Retrieve a translation
description: Retrieves a single translation job by its uid.
parameters:
- name: uid
in: path
required: true
schema:
type: string
description: The unique identifier of the translation job.
responses:
'200':
description: The requested translation job.
content:
application/json:
schema:
$ref: '#/components/schemas/Translation'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/mt_translation/:
get:
operationId: listMachineTranslations
tags:
- Machine Translation
summary: List machine translations
description: Lists machine-translation jobs, optionally filtered by status.
parameters:
- name: status
in: query
required: false
schema:
type: string
description: Filter machine-translation jobs by status.
responses:
'200':
description: A list of machine-translation jobs.
content:
application/json:
schema:
type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/Translation'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createMachineTranslation
tags:
- Machine Translation
summary: Submit a machine translation
description: Submits text for pure machine translation with no human review.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TranslationRequest'
responses:
'201':
description: The created machine-translation job.
content:
application/json:
schema:
$ref: '#/components/schemas/Translation'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/mt_translation/{uid}/:
get:
operationId: getMachineTranslation
tags:
- Machine Translation
summary: Retrieve a machine translation
description: Retrieves a single machine-translation job by its uid.
parameters:
- name: uid
in: path
required: true
schema:
type: string
responses:
'200':
description: The requested machine-translation job.
content:
application/json:
schema:
$ref: '#/components/schemas/Translation'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: upgradeMachineTranslation
tags:
- Machine Translation
summary: Upgrade a machine translation
description: >-
Upgrades an existing machine-translation job to a full human-reviewed
translation.
parameters:
- name: uid
in: path
required: true
schema:
type: string
responses:
'200':
description: The upgraded translation job.
content:
application/json:
schema:
$ref: '#/components/schemas/Translation'
'404':
$ref: '#/components/responses/NotFound'
/language_pair/:
get:
operationId: listLanguagePairs
tags:
- Language Pairs
summary: List language pairs
description: >-
Lists the supported source-to-target language pairs, optionally filtered
by a set of training languages.
parameters:
- name: train_langs
in: query
required: false
schema:
type: string
description: Comma-separated language codes to filter the returned pairs.
responses:
'200':
description: A list of supported language pairs.
content:
application/json:
schema:
type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/LanguagePair'
'401':
$ref: '#/components/responses/Unauthorized'
/tone/:
get:
operationId: listTones
tags:
- Tone and Topic
summary: List tones
description: Lists the tones available for a translation, such as formal or friendly.
responses:
'200':
description: A list of available tones.
content:
application/json:
schema:
type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/Tone'
'401':
$ref: '#/components/responses/Unauthorized'
/topic/:
get:
operationId: listTopics
tags:
- Tone and Topic
summary: List topics
description: Lists the topics/domains available to provide subject-matter context.
responses:
'200':
description: A list of available topics.
content:
application/json:
schema:
type: object
properties:
objects:
type: array
items:
$ref: '#/components/schemas/Topic'
'401':
$ref: '#/components/responses/Unauthorized'
/wordcount/:
post:
operationId: calculateWordCount
tags:
- Word Count
summary: Calculate word count
description: Calculates the billable word count for a block of text.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- text
properties:
text:
type: string
description: The text whose words should be counted.
text_format:
type: string
enum: [text, html, xliff]
default: text
responses:
'200':
description: The calculated word count.
content:
application/json:
schema:
type: object
properties:
word_count:
type: integer
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/account/:
get:
operationId: getAccount
tags:
- Account
summary: Retrieve account
description: Retrieves the authenticated customer account's information and balance.
responses:
'200':
description: The account details for the authenticated credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
'401':
$ref: '#/components/responses/Unauthorized'
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: Authorization
description: >-
Token authentication of the form `Authorization: ApiKey
<username>:<api_key>`.
responses:
BadRequest:
description: The request was malformed or missing required parameters.
Unauthorized:
description: Missing or invalid API credentials.
NotFound:
description: The requested resource was not found.
schemas:
TranslationRequest:
type: object
required:
- text
- source_language
- target_language
properties:
text:
type: string
description: The source text to translate.
source_language:
type: string
description: Source language code (for example en).
target_language:
type: string
description: Target language code (for example pt).
text_format:
type: string
enum: [text, html, xliff]
default: text
tone:
type: string
description: Optional tone/register for the translation.
topic:
type: string
description: Optional topic/domain for subject-matter context.
callback_url:
type: string
format: uri
description: >-
Optional HTTP endpoint Unbabel will POST a notification to when the
job status changes.
instructions:
type: string
description: Optional free-text instructions for the translator.
Translation:
type: object
properties:
uid:
type: string
description: Unique identifier of the translation job.
status:
type: string
description: Current job status (new, accepted, translating, delivered, etc.).
text:
type: string
description: The original source text.
translatedText:
type: string
description: The translated text, present once the job is delivered.
source_language:
type: string
target_language:
type: string
text_format:
type: string
tone:
type: string
topic:
type: string
price:
type: number
description: Price of the translation job.
wordcount:
type: integer
callback_url:
type: string
format: uri
LanguagePair:
type: object
properties:
lang_pair:
type: object
properties:
source_language:
$ref: '#/components/schemas/Language'
target_language:
$ref: '#/components/schemas/Language'
Language:
type: object
properties:
name:
type: string
shortname:
type: string
Tone:
type: object
properties:
name:
type: string
description:
type: string
Topic:
type: object
properties:
name:
type: string
Account:
type: object
properties:
username:
type: string
email:
type: string
balance:
type: number
description: Remaining prepaid balance or credit on the account.
Notification:
type: object
description: >-
Modeled payload POSTed to a job's callback_url when its status changes.
Shape inferred from documented callback behavior, not a published schema.
properties:
uid:
type: string
status:
type: string
translatedText:
type: string