NAV Navbar
Logo

Introduction

SDL Machine Translation Edge (formerly known as SDL ETS) 8 features a REST API that exposes the functionality of MTE to any HTTP client. It uses predictable, resource-oriented URLs as well as standard HTTP verbs and response codes. CORS is supported, allowing client-side web applications to make cross-domain AJAX requests to the API. The majority of the endpoints return JSON, while a few return a base64-encoded string or XML.

The REST API is served on the master host at its own port. To find out the API server host and port, log in to the SDL MTE Web GUI as an admin user and click to [Username] > My Account. For the purposes of this documentation, we will reference an example server running at the host master-host and port 8001, with HTTPS enabled, so the base URL for the REST API will be:

https://master-host:8001/

Throughout the documentation, we will be using curl as our HTTP client to illustrate various interactions with the REST API. Keep in mind that, regardless of HTTP client, it is always a good idea to url-encode data that will be consumed by the API to ensure the integrity of the requests.

Versioning

In future releases of SDL MTE, improvements and changes will be made to the REST API. To reduce the chance of breaking your integrations, any backwards-incompatible changes to the API will warrant a new version number of the API. MTE 8.0 ships with v2 of the API, while MTE 7.x ships with v1 of the API. The API version is hardcoded into the URL:

https://master-host:8001/api/v2

All endpoints in this documentation are described by an HTTP verb and a partial resource identifier, for example:

GET /api/v2/dictionaries/{dictionaryId}

To get the full URL for an endpoint, simply append the partial resource identifier to the base URL:

GET https://master-host:8001/api/v2/dictionaries/{dictionaryId}

Authentication

Every request sent to the SDL MTE API must be authenticated, in one of two ways: (1) API key authentication, or (2) token authentication. If authentication fails, a 401 Unauthorized response will be returned. API key authentication allows you to make API requests immediately, while token authentication requires an extra step of first logging in to obtain an access token before making API requests.

API key authentication

# replace <api-key> with a valid API key
curl -u <api-key>: "https://master-host:8001/api/v2/translations"

One method of authenticating API requests is by supplying a valid API key. Each admin user has a unique API key. To obtain your API key, log in to the SDL MTE Web GUI as an admin user and click to [Username] > My Account, where the API key is displayed. You can easily change your API key on that page as well.

The API uses HTTP Basic Authentication for API key authentication, so you need to specify your API key as the username and leave the password blank.

The vast majority of the API examples below use API key authentication.

Token authentication

# login with username and password
curl -X POST https://master-host:8001/api/v2/auth -d username="jsmith@example.com" -d password="mypassword"
# => returns token

# replace <token> with returned token
curl -H "Authorization: Bearer <token>" "https://master-host:8001/api/v2/translations"

Another method of authenticating API requests is by supplying a valid access token. To obtain an access token, first log in by passing your username and password to the POST /api/v2/auth endpoint, which will return a valid access token that expires after 30 days.

The API uses Bearer Token Authentication for token authentication, so this access token must be specified in an Authorization: Bearer header in each of your API requests.

Pagination

If we retrieve the list of translations and provide no pagination parameters, the first page of 25 items will be returned:

curl -u <api-key>: "https://master-host:8001/api/v2/translations"

To return the second page of 50 items:

curl -u <api-key>: "https://master-host:8001/api/v2/translations?page=2&perPage=50"

All top-level resources have a list endpoint that retrieves a set of items of that resource-type. Some resources (language pairs, hosts) return all items in a single call, while the rest (translations, dictionaries, users) return only a page of items at a time.

List endpoints of resources that support pagination return the first page by default, and 25 items per page by default. Both the page number and the page size can be overriden using the optional page and perPage parameters, respectively. Those two values will be returned in the response, as well as two additional fields: totalItems and totalPages, which indicate the total number of items and pages there are, respectively.

Errors

The MTE API uses standard HTTP response codes to indicate whether an API request succeeded or failed. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error caused by invalid parameter(s) provided to the API call, and codes in the 5xx range indicate an error internal to the API server:

Code Description
200 OK – Everything worked as expected
400 Bad Request – The request was unacceptable due to some invalid or missing parameter
401 Unauthorized – The provided API key or access token was invalid, expired, or missing
403 Forbidden – The authenticated user lacks the required privileges to access the specified endpoint
404 Not Found – The specified endpoint does not exist
500 Internal Server Error – An error occurred within the API server

Failed API calls usually return an error object with the following fields:

If we try to create a user when the username already exists:

curl "https://master-host:8001/api/v2/users" \
    -X POST \
    -u u_jsmith@sdl.com_u0VmztKJrwqf: \
    -d displayName="John Smith" \
    -d username="jsmith@example.com"

This error response is returned:

{
    "error": {
        "code": 400,
        "message": "user could not be added",
        "details": "the specified user already exists: jsmith@example.com"
    }
}
Field Type Description
code int HTTP response status code
message string Human-readable message describing the error
details (optional) string Additional, more detailed message describing the error

Language and Script Codes

To refer to languages, SDL MTE employs a proprietary 3-letter language code system that roughly follows the ISO 639 standards for the majority of languages, with custom codes invented for the rest. For better compatibility with other products, the language detection API also returns IETF language tags in accordance with the BCP 47 standard.

Name MTE 3-Letter Code IETF Language Tag
Afrikaans afr af
Albanian alb sq
Amharic amh am
Arabic ara ar
Arabic (Arabizi) arz ar-arabizi
Armenian arm hy
Azerbaijani aze az
Basque baq eu
Belarusian bel be
Bengali ben bn
Bihari bih bh
Bulgarian bul bg
Catalan cat ca
Cebuano ceb ceb
Cherokee chr chr
Chinese (Simplified) chi zh-Hans
Chinese (Traditional) cht zh-Hant
Croatian hrv hr
Czech cze cs
Danish dan da
Dari fad prs-AF
Dutch dut nl
English eng en
Estonian est et
Finnish fin fi
French fra fr
Galician glg gl
Ganda lug lg
Georgian geo ka
German ger de
Greek gre el
Gujarati guj gu
Hausa hau ha
Hebrew heb he
Hindi hin hi
Hmong hmn hmn
Hungarian hun hu
Icelandic ice is
Indonesian ind id
Inuktitut iku iu
Irish gle ga
Italian ita it
Japanese jpn ja
Javanese jav jv
Kannada kan kn
Kinyarwanda kin rw
Korean kor ko
Latvian lav lv
Limbu lif lif
Lithuanian lit lt
Macedonian mac mk
Malay may ms
Malayalam mal ml
Maltese mlt mt
Marathi mar mr
Nepali nep ne
Norwegian nor no
Oriya ori or
Ossetian oss os
Pashto pus ps
Persian per fa
Polish pol pl
Portuguese por pt
Portuguese (Brazil) ptb pt-BR
Portuguese (Portugal) ptp pt-PT
Romanian rum ro
Russian rus ru
Serbian srp sr
Slovak slo sk
Slovenian slv sl
Somali som so
Spanish spa es
Sundanese sun su
Swahili swa sw
Swedish swe sv
Syriac syr syr
Tagalog tgl tl
Tajik tgk tg
Tamil tam ta
Telugu tel te
Thai tha th
Turkish tur tr
Ukrainian ukr uk
Urdu urd ur
Uzbek uzb uz
Vietnamese vie vi
Welsh wel cy
Yiddish yid yi

To refer to writing scripts, SDL MTE follows the 4-letter script code system defined by ISO 15924.

Name ISO-15924 Code
Afaka Afak
Ahom Ahom
Anatolian Hieroglyphs Hluw
Arabic Arab
Armenian Armn
Avestan Avst
Balinese Bali
Bamum Bamu
Bassa Vah Bass
Batak Batk
Bengali Beng
Blissymbols Blis
Book Pahlavi Phlv
Bopomofo Bopo
Brahmi Brah
Braille Brai
Buginese Bugi
Buhid Buhd
Canadian Aboriginal Cans
Carian Cari
Caucasian Albanian Aghb
Chakma Cakm
Cham Cham
Cherokee Cher
Cirth Cirt
Code for Unwritten Documents Zxxx
Common Zyyy
Coptic Copt
Cuneiform Xsux
Cypriot Cprt
Cyrillic Cyrl
Cyrillic (Old Church Slavonic) Cyrs
Deseret Dsrt
Devanagari Deva
Duployan Dupl
Egyptian Demotic Egyd
Egyptian Hieratic Egyh
Egyptian Hieroglyphs Egyp
Elbasan Elba
Ethiopic Ethi
Georgian Geok
Georgian Geor
Glagolitic Glag
Gothic Goth
Grantha Gran
Greek Grek
Gujarati Gujr
Gurmukhi Guru
Han Hani
Han (Simplified) Hans
Han (Traditional) Hant
Hangul Hang
Hanunoo Hano
Hatran Hatr
Hebrew Hebr
Hiragana Hira
Imperial Aramaic Armi
Indus (Harappan) Inds
Inherited Zinh
Inscriptional Pahlavi Phli
Inscriptional Parthian Prti
Invalid Qaai
Japanese Jpan
Javanese Java
Jurchen Jurc
Kaithi Kthi
Kannada Knda
Katakana Kana
Kayah Li Kali
Kharoshthi Khar
Khmer Khmr
Khojki Khoj
Khudawadi Sind
Korean Kore
Kpelle Kpel
Lao Laoo
Latin Latn
Latin (Fraktur) Latf
Latin (Gaelic) Latg
Lepcha Lepc
Limbu Limb
Linear A Lina
Linear B Linb
Lisu Lisu
Loma Loma
Lycian Lyci
Lydian Lydi
Mahajani Mahj
Malayalam Mlym
Mandaic Mand
Manichaean Mani
Mathematical Notation Zmth
Mayan Hieroglyphs Maya
Meetei Mayek Mtei
Mende Kikakui Mend
Meroitic Cursive Merc
Meroitic Hieroglyphs Mero
Miao Plrd
Modi Modi
Mongolian Mong
Moon Moon
Mro Mroo
Multani Mult
Myanmar Mymr
Nabataean Nbat
Nakhi Geba Nkgb
New Tai Lue Talu
Nko Nkoo
Nüshu Nshu
Ogham Ogam
Ol Chiki Olck
Old Hungarian Hung
Old Italic Ital
Old North Arabian Narb
Old Permic Perm
Old Persian Xpeo
Old South Arabian Sarb
Old Turkic Orkh
Oriya Orya
Osmanya Osma
Pahawh Hmong Hmng
Palmyrene Palm
Pau Cin Hau Pauc
Phags Pa Phag
Phoenician Phnx
Psalter Pahlavi Phlp
Rejang Rjng
Rongorongo Roro
Runic Runr
Samaritan Samr
Sarati Sara
Saurashtra Saur
Sharada Shrd
Shavian Shaw
Siddham Sidd
SignWriting Sgnw
Sinhala Sinh
Sora Sompeng Sora
Sundanese Sund
Syloti Nagri Sylo
Symbols Zsym
Syriac Syrc
Syriac (Eastern) Syrn
Syriac (Estrangelo) Syre
Syriac (Western) Syrj
Tagalog Tglg
Tagbanwa Tagb
Tai Le Tale
Tai Tham Lana
Tai Viet Tavt
Takri Takr
Tamil Taml
Tangut Tang
Telugu Telu
Tengwar Teng
Thaana Thaa
Thai Thai
Tibetan Tibt
Tifinagh Tfng
Tirhuta Tirh
Ugaritic Ugar
Unknown Zzzz
Vai Vaii
Visible Speech Visp
Warang Citi Wara
Woleai Wole
Yi Yiii

Encodings

SDL MTE supports the following character encodings for source documents:

Encoding
Big5
EUC-JP
EUC-KR
GB18030
IBM420_ltr
IBM420_rtl
IBM424_ltr
IBM424_rtl
ISO-2022-CN
ISO-2022-JP
ISO-2022-KR
ISO-8859-1
ISO-8859-2
ISO-8859-5
ISO-8859-6
ISO-8859-7
ISO-8859-8
ISO-8859-8-I
ISO-8859-9
KOI8-R
Shift_JIS
UTF-16BE
UTF-16LE
UTF-32BE
UTF-32LE
UTF-8
windows-1251
windows-1256

In addition to the encodings above, ‘Auto’ may be specified to allow automatic detection.

Access Tokens

Obtain an access token

Example Request:

curl "https://master-host:8001/api/v2/auth" \
    -X POST \
    --data-urlencode password="mypassword" \
    --data-urlencode username="jsmith@example.com"

Example Response:

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gU21pdGgiLCJhZG1pbiI6dHJ1ZX0.LfFQV0anBnn40BJ-CL3XSDUAcbqQw8Xm7sDKNVHrR9U"

Retrieve a user’s access token that can be used for token authentication, by logging in with username and password. This token is valid for 30 days. Once the token expires, this endpoint will need to be called again to obtain a new access token.

HTTP Request

POST /api/v2/auth

Request Parameters

Name Type Description Default Value
username string Username to authenticate with
password string Password to authenticate with

Returns

Returns a valid access token in JSON Web Token (JWT) format.

Translations

List translations

Example Request:

curl "https://master-host:8001/api/v2/translations" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "translations": [
        {
            "translationId": "051a5d687795d",
            "profile": {
                "username": "jsmith@example.com",
                "title": "example translation",
                "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
                "encoding": "utf-8",
                "inputFormat": "text/html",
                "dictionaryIds": [
                    "dict1_c95c72dd2f138da2a46c872a40616eb1",
                    "dict2_397e8373985929881616bcaa4805844a"
                ],
                "outputFormat": "",
                "highlightDictionary": true,
                "unknownMode": "hide",
                "highlightUnknown": false,
                "generateMetadata": false,
                "translationMethod": "MTE"
            },
            "result": {
                "completedSegments": 64,
                "inputSize": 3613,
                "sourceCharacterCount": 3498,
                "sourceWordCount": 689,
                "targetCharacterCount": 3840,
                "targetWordCount": 766,
                "totalSegments": 64,
                "outputSize": 4006,
                "progress": 100,
                "wordsPerMinute": 52065
            },
            "timestamps": {
                "queued": "2018-06-21 19:03:31.799810031Z",
                "started": "2018-06-21 19:03:32.113048776Z",
                "done": "2018-06-21 19:03:34.872942468Z"
            },
            "errorMessage": "",
            "state": "done",
            "substate": "succeeded"
        }
    ],
    "page": 1,
    "perPage": 25,
    "totalPages": 1,
    "totalItems": 1
}

Return a list of translations. If the caller is an admin user, translations for all users are returned, unless the username field is provided to return only that specific user’s translations. If the caller is a non-admin user, only the caller’s translations are returned.

HTTP Request

GET /api/v2/translations

Request Parameters

Name Type Description Default Value
username (optional) string Show only translations created by this user. This field is ignored for non-admin users.
page (optional) int Page number to return 1
perPage (optional) int Number of translations to return per page 25

Returns

Returns a list of translations as a TranslationList object with the following attributes:

Name Type Description
translations array of objects List of translations as an array of Translation objects
page int Page number returned
perPage int Number of translations returned per page
totalPages int Total number of pages available
totalItems int Total number of translations

Create a translation (asynchronously)

Example Request:

curl "https://master-host:8001/api/v2/translations" \
    -X POST \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d dictionaryIds="dict1,dict2" \
    -d highlightDictionary="true" \
    -d languagePairId="EngFra_Generic_SRV_TNMV_8_4_x_1" \
    -d mode="text" \
    -d outputFormat="application/x-xliff" \
    --data-urlencode input="VGhpcyBpcyBhIHNhbXBsZSBpbnB1dCB0ZXh0Lgo=" \
    --data-urlencode title="example translation"

Example Response:

{
    "translationId": "051a5d687795d"
}

Create an asychronous translation job and receive back its identifier. This identifier can then be used to monitor the job’s status and retrieve the translation results after successful completion.

HTTP Request

POST /api/v2/translations

Request Parameters

Name Type Description Default Value
mode (optional) string Translation mode text text
languagePairId string Identifier of language pair or language pair chain to use for translation; e.g., EngFra_Generic_SRV_PBL_7_4_x_1 or ChiEng_Generic_SRV_PBL_7_4_x_1>>EngFra_Generic_SRV_PBL_7_4_x_1. To automatically detect the source language, use AutXxx, where Xxx is the 3-letter code of the desired target language. The AutXxx pattern cannot be used with language pair chains.
input string Base64-encoded and URL-encoded content to translate
inputFormat (optional) string Format of input document (see table of possible input formats)
outputFormat (optional) string Format of output document (see table of possible output formats)
title (optional) string Title of translation job
encoding (optional) string Encoding of input content (see list of supported character encodings) utf-8
dictionaryIds (optional) string User dictionaries to be used for translation – comma-separated identifiers, in decreasing order of precedence (only available if not using automatic source language detection)
highlightDictionary (optional) bool Whether to highlight dictionary translations in the output. This only applies if dictionaryIds is set to at least one dictionary, and both inputFormat and outputFormat are text/html. false
unknownMode (optional) string How to display unknown words. Choices: hide to omit unknown words from the output, original to include original unknown words as is, transliteration to transliterate unknown words, or transliterationAndOriginal to show both the transliteration and the original (in parentheses). transliteration and transliterationAndOriginal display transliterations if the source language supports transliteration, otherwise the original unknown words are displayed. transliteration
highlightUnknown (optional) bool Whether to highlight unknown words or their transliterations. This only applies if both inputFormat and outputFormat are text/html. false
generateMetadata (optional) bool Generate metadata in addition to the translation (requires more computation) false

Returns

Returns an asynchronous translation job as an AsyncTranslation object with the following attributes:

Name Type Description
translationId string Identifier of newly-created translation job

Input Formats

XML Formats

MIME Type File Extensions Description
text/html .htm, .html, .xhtml HTML
text/xml .xml XML
text/x-sdl-strict-xml .sdlxml XML with strict segmentation after each XML tag
text/x-tmx .tmx Translation Memory eXchange (TMX)
application/x-xliff .xliff XML Localization Interchange File Format (XLIFF)

Text Formats

MIME Type File Extensions Description
text/plain .txt Plain text
text/x-line .xline Plain text, one sentence per line

Image Formats

MIME Type File Extensions Description
image/gif .gif Graphics Interchange Format (GIF)
image/jpeg .jpg, .jpeg JPEG
image/png .png Portable Network Graphics (PNG)
image/tiff .tiff, .tif Tagged Image File Format (TIFF)

Rich Formats

MIME Type File Extensions Description
application/pdf .pdf Adobe Acrobat (PDF)
application/rtf .rtf Rich Text Format (RTF)
application/vnd.openxmlformats-officedocument.wordprocessingml.document .docx, .dotx, .docm, .dotm Microsoft Word (Office Open XML)
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet .xlsx, .xltx, .xlsm, .xltm, .xlam Microsoft Excel (Office Open XML)
application/vnd.openxmlformats-officedocument.presentationml.presentation .pptx, .potx, .ppsx, .ppam, .pptm, .potm, .ppsm Microsoft PowerPoint (Office Open XML)
application/msword .doc, .dot Microsoft Word (97-2003)
application/vnd.ms-excel .xls, .xlt, .xla, .xlsb Microsoft Excel (97-2003)
application/vnd.ms-powerpoint .ppt, .pot, .pps, .ppa Microsoft PowerPoint (97-2003)
application/vnd.oasis.opendocument.text .odt OpenDocument Text
application/vnd.oasis.opendocument.spreadsheet .ods OpenDocument Spreadsheet
application/vnd.oasis.opendocument.presentation .odp OpenDocument Presentation

Output Formats

MIME Type Description
default or empty Default output:
  • For image and audio input formats, output text/plain
  • For application/pdf input, output text/x-line if it is an image-only PDF, otherwise output application/pdf
  • For all other input formats, output the same as the input format
text/plain Plain text
application/x-xliff XML Localization Interchange File Format
text/x-tmx Translation Memory eXchange

Create a quick translation (synchronously)

Example Request:

curl "https://master-host:8001/api/v2/translations/quick" \
    -X POST \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d languagePairId="EngFra_Generic_SRV_TNMV_8_4_x_1" \
    --data-urlencode input="VGhpcyBpcyBhIHNhbXBsZSBpbnB1dCB0ZXh0Lgo="

Example Response:

{
    "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
    "translation": "Qydlc3QgdW4gZXhlbXBsZSBkZSB0ZXh0ZSBkJ2VudHLDqWUuCg=="
}

Create a synchronous translation and receive back the translation in the same call. This method is recommended for small, plain text inputs under 1KB in size, although no constraint is enforced. Only the translation and not a job identifier is returned, so the job cannot be tracked or managed in any way.

HTTP Request

POST /api/v2/translations/quick

Request Parameters

Name Type Description Default Value
languagePairId string Identifier of language pair or language pair chain to use for translation; e.g., EngFra_Generic_SRV_PBL_7_4_x_1 or ChiEng_Generic_SRV_PBL_7_4_x_1>>EngFra_Generic_SRV_PBL_7_4_x_1. To automatically detect the source language, use AutXxx, where Xxx is the 3-letter code of the desired target language. The AutXxx pattern cannot be used with language pair chains.
input string Base64-encoded and URL-encoded content to translate
inputFormat (optional) string Format of input document
title (optional) string Title of translation job
encoding (optional) string Encoding of input content (see list of supported character encodings) utf-8
dictionaryIds (optional) string User dictionaries to be used for translation – comma-separated identifiers, in decreasing order of precedence (only available if not using automatic source language detection)
highlightDictionary (optional) bool Whether to highlight dictionary translations in the output. This only applies if dictionaryIds is set to at least one dictionary, and both inputFormat and outputFormat are text/html. false
unknownMode (optional) string How to display unknown words. Choices: hide to omit unknown words from the output, original to include original unknown words as is, transliteration to transliterate unknown words, or transliterationAndOriginal to show both the transliteration and the original (in parentheses). transliteration and transliterationAndOriginal display transliterations if the source language supports transliteration, otherwise the original unknown words are displayed. transliteration
highlightUnknown (optional) bool Whether to highlight unknown words or their transliterations. This only applies if both inputFormat and outputFormat are text/html. false
generateMetadata (optional) bool Generate metadata in addition to the translation (requires more computation) false

Returns

Returns a synchronous translation as a SyncTranslation object with the following attributes:

Name Type Description
languagePairId string Identifier of language pair used for translation
translation string Base64-encoded output translation
detectedSourceLanguageId string Automatically-detected source language identifier of the input

Retrieve a translation’s status

Example Request:

curl "https://master-host:8001/api/v2/translations/051a5d687795d" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "translationId": "051a5d687795d",
    "profile": {
        "username": "jsmith@example.com",
        "title": "example translation",
        "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
        "encoding": "utf-8",
        "inputFormat": "text/html",
        "dictionaryIds": [
            "dict1_c95c72dd2f138da2a46c872a40616eb1",
            "dict2_397e8373985929881616bcaa4805844a"
        ],
        "outputFormat": "",
        "highlightDictionary": true,
        "unknownMode": "hide",
        "highlightUnknown": false,
        "generateMetadata": false,
        "translationMethod": "MTE"
    },
    "result": {
        "completedSegments": 64,
        "inputSize": 3613,
        "sourceCharacterCount": 3498,
        "sourceWordCount": 689,
        "targetCharacterCount": 3840,
        "targetWordCount": 766,
        "totalSegments": 64,
        "outputSize": 4006,
        "progress": 100,
        "wordsPerMinute": 52065
    },
    "timestamps": {
        "queued": "2018-06-21 19:03:31.799810031Z",
        "started": "2018-06-21 19:03:32.113048776Z",
        "done": "2018-06-21 19:03:34.872942468Z"
    },
    "errorMessage": "",
    "state": "done",
    "substate": "succeeded"
}

Return information about and status of an asychronous translation job.

HTTP Request

GET /api/v2/translations/{translationId}

Path Parameters

Name Type Description
translationId string Identifier of translation job

Returns

Returns the specified translation as a Translation object with the following attributes:

Name Type Description
translationId string Identifier of translation job
profile object Description of translation job in the queue (expanded below)
→ username string Username of user who created translation job
→ title string Title of translation job
→ url string URL of webpage to be translated [not used]
→ languagePairId string Identifier of language pair or language pair chain
→ encoding string Source document encoding
→ inputFormat string Input format
→ dictionaryIds array of strings Dictionaries used for translation
→ outputFormat string Output format
→ highlightDictionary string Whether to highlight dictionary translations in the output
→ unknownMode string How to display unknown words
→ highlightUnknown string Whether to highlight unknown words or their transliterations
→ generateMetadata bool Whether metadata of output will be produced and included in response
→ translationMethod string Method used to translate the job
result object Description of translation job in the queue (expanded below)
→ completedSegments int Number of segments that have successfully been translated
→ detectedSourceLanguageId string Automatically-detected source language identifier of the input
→ detectedEncoding string Automatically-detected script encoding identifier of the input
→ inputSize int Size of the input document in bytes
→ sourceCharacterCount int Number of input characters in the document translated so far
→ sourceWordCount int Number of input words in the document translated so far
→ targetCharacterCount int Number of output characters in the document translated so far
→ targetWordCount int Number of output words in the document translated so far
→ totalSegments int Total number of segments in the input
→ outputSize int Size of the output document in bytes
→ progress int Translation progress (percent completion)
→ wordsPerMinute int Translation rate (words per minute)
timestamps object Timestamps of checkpoints in translation job progress (expanded below) in UTC
→ queued string When the translation job was created before being submitted to a job engine (when state became preparing)
→ started string When the translation job was submitted to a job engine (when state became inProgress)
→ done string When the translation job result was returned from a job engine (when state became done)
errorMessage string Error message if state is done and substate is failed
state string Translation job state (see table below)
substate string Translation job substate (see table below)

Translation Job States and Their Substates

The status of a job is represented by a state and a substate. There are three possible states, and each state has a number of possible substates. The state provides a high-level indication of whether a job has started, is in progress, or has ended, while the substate provides more detailed information about the state.

State Substate Description
preparing job is being prepared for translation
  created job has been created
  dispatching job is being dispatched to a job engine
  transcribing job involves audio input and it is being transcribed.
inProgress job is being processed
  initializing job engine is getting ready to process job
  preprocessing job is being preprocessed
  translating job is being translated
  postprocessing job is being postprocessed
  converting job is being converted for the interactive translation editor
done job has finished
  canceled job has been canceled by user
  succeeded job has completed successfully
  failed job has failed

Download a translation

Example Request:

curl "https://master-host:8001/api/v2/translations/051a5d687795d/download" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

Qydlc3QgdW4gZXhlbXBsZSBkZSB0ZXh0ZSBkJ2VudHLDqWUuCg==

Return the translated output of an asynchronous translation job. The job must have been successfully completed first.

HTTP Request

GET /api/v2/translations/{translationId}/download

Path Parameters

Name Type Description
translationId string Identifier of translation job

Returns

Returns the output of a translation in base64 encoding.

Retrieve metadata of a translation

Example Request:

curl "https://master-host:8001/api/v2/translations/051a5d687795d/metadata" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

ew0KICAgICJhcHBJZCI6ICI4LjAuMCIsDQogICAgImpvYklkIjogNSwNCiAgICAic291cmNlTGFuZ3VhZ2VJZCI6ICJlbmciLA0KICAgICJ0YXJnZXRMYW5ndWFnZUlkIjogImZyYSIsDQogICAgImxhbmd1YWdlUGFpcklkIjogIkVuZ0ZyYV9HZW5lcmljX1NSVl9QQl84XzBfeF8wIiwNCiAgICAic2VnbWVudCI6IHsNCiAgICAgICAgImlkIjogMCwNCiAgICAgICAgInNvdXJjZVRva2VucyI6ICJUaGlzIGlzIGEgc2FtcGxlIGlucHV0IHRleHQgX19MV19BVF9fLiIsDQogICAgICAgICJzb3VyY2VUb2tlbnNMb3dlcmNhc2UiOiAidGhpcyBpcyBhIHNhbXBsZSBpbnB1dCB0ZXh0IF9fTFdfQVRfXy4iLA0KICAgICAgICAidGFyZ2V0VG9rZW5zIjogIkMgX19MV19BVF9fJ19fTFdfQVRfXyBlc3QgdW4gZXhlbXBsZSBkZSB0ZXh0ZSBkIF9fTFdfQVRfXydfX0xXX0FUX18gZW50csOpZSBfX0xXX0FUX18uIiwNCiAgICAgICAgInRhcmdldFRva2Vuc0xvd2VyY2FzZSI6ICJjIF9fTFdfQVRfXydfX0xXX0FUX18gZXN0IHVuIGV4ZW1wbGUgZGUgdGV4dGUgZCBfX0xXX0FUX18nX19MV19BVF9fIGVudHLDqWUgX19MV19BVF9fLiINCiAgICB9DQp9DQo=

Return the metadata of an asynchronous translation job. The translation must have been successfully completed first.

HTTP Request

GET /api/v2/translations/{translationId}/metadata

Path Parameters

Name Type Description
translationId string Identifier of translation job

Returns

Returns the metadata of a translation in JSON format in base64 encoding.

Create a translation via GroupShare

Example Request:

curl "https://master-host:8001/api/v2/translations/group-share" \
    -X POST \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d languagePairId="EngFra_Generic_SRV_TNMV_8_4_x_1" \
    --data-urlencode input="VGhpcyBpcyBhIHNhbXBsZSBpbnB1dCB0ZXh0Lgo=" \
    --data-urlencode title="example translation"

Example Response:

{
    "translationId": "051a5d687795d"
}

Submit input to GroupShare for translation and editing. Output format is the same as input format.

HTTP Request

POST /api/v2/translations/group-share

Request Parameters

Name Type Description Default Value
languagePairId string Identifier of language pair or language pair chain to use for translation; e.g., EngFra_Generic_SRV_PBL_7_4_x_1 or ChiEng_Generic_SRV_PBL_7_4_x_1>>EngFra_Generic_SRV_PBL_7_4_x_1. To automatically detect the source language, use AutXxx, where Xxx is the 3-letter code of the desired target language. The AutXxx pattern cannot be used with language pair chains.
input string Base64-encoded and URL-encoded utf-8 content to translate
inputFormat (optional) string Format of input document (see table of possible input formats)
title (optional) string Title of translation job

Returns

Returns an asynchronous translation job as an AsyncTranslation object with the following attributes:

Name Type Description
translationId string Identifier of newly-created translation job

Retrieve the URL to edit a GroupShare translation

Example Request:

curl "https://master-host:8001/api/v2/translations/group-share/051a5d687795d" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "username": "User",
    "link": "http://groupShareHost:80/#editor/project/075dd207-38d2-4262-a23e-babc751b4751/languageFile/62f74351-217c-42d2-8e22-0f0949d8dfd0",
    "token": "AAIAAFeH8_HfLlPA9Fbp692hLm__XmVhW2V04k294kfxD7LM7ZXSFfw1KpUFcQVw-sH1_iScOCTHfn1XSownycm9q6cXL39pqoSlEvhlTkC2VZNAM9Em6EPK92aanhLkQeP_bKjP-dLPzRejBrKNH0hcwKGs25ue4K2NvkT6Nz5D8PAAzA-qH8zObV20uqjdzAMZRS7ZrhjL79cYGNPXenzI4HG3EhMKz7hbJ1G9qP1KGZEdLUiFHo4sC6Zby_A6HR3a3cXSaIjZ_MrTKWmTWgbC13aq3iJmRU_Z5Z420sbN4rN5l9JsPedRhTYEfwDEtWvZO37tUmbZm-oa03J4c32WsZUippAxxctkQpsWtCuliw5i8wnWE_X7VTudD6JAAK8paWUM6EkjwDIJ6FiZELmWxqpGCX4NWu4ifQcWr6PgU9GC9TMf84CPT-1kNQbR-bhxYD7ggTcQVQSZ39w8QsBX8GN4Vl47r4vCasvx3r_zR6FOghIb96OKR2Ij3SbwLgorgZyTTjTlSHe0t1qFdtcsPj_EQ0WwdIyavCc0CtHY57o4ROuiNDqs1qDaYhRerwmowdVl6jwlpAFWkgnTVaTjZsKNoc-4Wk7T1RJfrMTN3NmF_nsIA7-A3UeOblm0oqJkHFEePj8psAtvpIBoCYRmduNcFreyUwskV5l6LKkc-4_gpAIAAAACAAAHeLpwx0HaoXposaNsJFzYFu5d4kBn8aL8IgKgZ_DDF1dCyfK2NLFIraDU2vUPUAwQbbtMIXiSSoTHAJBpX7_KQvtDmy_mgDAkC8vNdXZHXLJHllAgU7T6bfRToSzeZr0sozmxjddpGNtZgVnwD91rRaXW2Q12arI-KsGWG_nBfZA149jFIrNszoCscVwkZ5tS0IpsyduIsUks_60VVcuTjWbcqW0OCt99SG8fUtQsGNx8H0SAg84EKuVdDvDeCw-3u-qXJApE62s8FSqgHJkWL4g06_"
}

Return the URL to edit a GroupShare translation.

HTTP Request

GET /api/v2/translations/group-share/{translationId}

Path Parameters

Name Type Description
translationId string Identifier of translation job

Returns

Returns information to edit a a GroupShare translation as a GroupShareEditorDetails object with the following attributes:

Name Type Description
username string GroupShare’s username as set in MTE
link string Link to GroupShare’s editor
token string GroupShare’s token

Cancel a translation

Example Request:

curl "https://master-host:8001/api/v2/translations/051a5d687795d/cancel" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "translationId": "051a5d687795d",
    "profile": {
        "username": "jsmith@example.com",
        "title": "example translation",
        "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
        "encoding": "utf-8",
        "inputFormat": "text/html",
        "dictionaryIds": [
            "dict1_c95c72dd2f138da2a46c872a40616eb1",
            "dict2_397e8373985929881616bcaa4805844a"
        ],
        "outputFormat": "",
        "highlightDictionary": true,
        "unknownMode": "hide",
        "highlightUnknown": false,
        "generateMetadata": false,
        "translationMethod": "MTE"
    },
    "result": {
        "completedSegments": 0,
        "inputSize": 0,
        "sourceCharacterCount": 0,
        "sourceWordCount": 0,
        "targetCharacterCount": 0,
        "targetWordCount": 0,
        "totalSegments": 0,
        "outputSize": 0,
        "progress": 0,
        "wordsPerMinute": 0
    },
    "timestamps": {
        "queued": "2018-06-21 19:03:31.799810031Z",
        "started": "",
        "done": ""
    },
    "errorMessage": "",
    "state": "done",
    "substate": "canceled"
}

Cancel an asynchronous translation job. The canceled job remains in the queue.

HTTP Request

PUT /api/v2/translations/{translationId}/cancel

Path Parameters

Name Type Description
translationId string Identifier of translation job

Returns

Returns the canceled translation as a Translation object.

Delete a translation

Example Request:

curl "https://master-host:8001/api/v2/translations/051a5d687795d" \
    -X DELETE \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "translationId": "051a5d687795d",
    "profile": {
        "username": "jsmith@example.com",
        "title": "example translation",
        "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
        "encoding": "utf-8",
        "inputFormat": "text/html",
        "dictionaryIds": [
            "dict1_c95c72dd2f138da2a46c872a40616eb1",
            "dict2_397e8373985929881616bcaa4805844a"
        ],
        "outputFormat": "",
        "highlightDictionary": true,
        "unknownMode": "hide",
        "highlightUnknown": false,
        "generateMetadata": false,
        "translationMethod": "MTE"
    },
    "result": {
        "completedSegments": 64,
        "inputSize": 3613,
        "sourceCharacterCount": 3498,
        "sourceWordCount": 689,
        "targetCharacterCount": 3840,
        "targetWordCount": 766,
        "totalSegments": 64,
        "outputSize": 4006,
        "progress": 100,
        "wordsPerMinute": 52065
    },
    "timestamps": {
        "queued": "2018-06-21 19:03:31.799810031Z",
        "started": "2018-06-21 19:03:32.113048776Z",
        "done": "2018-06-21 19:03:34.872942468Z"
    },
    "errorMessage": "",
    "state": "done",
    "substate": "succeeded"
}

Remove a translation job from the translation queue and history.

HTTP Request

DELETE /api/v2/translations/{translationId}

Path Parameters

Name Type Description
translationId string Identifier of translation job

Returns

Returns the deleted translation as a Translation object.

Dictionaries

List dictionaries

Example Request:

curl "https://master-host:8001/api/v2/dictionaries?sourceLanguageId=eng&targetLanguageId=fra" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "dictionaries": [
        {
            "dictionaryId": "dict1",
            "sourceLanguageId": "eng",
            "targetLanguageId": "fra"
        },
        {
            "dictionaryId": "dict2",
            "sourceLanguageId": "eng",
            "targetLanguageId": "fra"
        }
    ],
    "page": 1,
    "perPage": 25,
    "totalPages": 1,
    "totalItems": 2
}

Return a list of dictionaries.

HTTP Request

GET /api/v2/dictionaries

Request Parameters

Name Type Description Default Value
sourceLanguageId (optional) string Source language (3-letter code), required if target language is specified
targetLanguageId (optional) string Target language (3-letter code), required if source language is specified
page (optional) int Page number to return 1
perPage (optional) int Number of dictionaries to return per page 25

Returns

Returns a list of dictionaries as a DictionaryList object with the following attributes:

Name Type Description
dictionaries array of objects List of dictionaries as an array of Dictionary objects
page int Page number returned
perPage int Number of dictionaries returned per page
totalPages int Total number of pages available
totalItems int Total number of dictionaries

Create a dictionary

Example Request:

curl "https://master-host:8001/api/v2/dictionaries" \
    -X POST \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d dictionaryId="dict1" \
    -d sourceLanguageId="eng" \
    -d targetLanguageId="fra" \
    --data-urlencode content="PGRpY3Rpb25hcnk+PGRpY3QtZW50cmllcz48ZGljdC1lbnRyeT48c3JjLXNlZ21lbnQ+Ym9va21hcms8L3NyYy1zZWdtZW50Pjx0Z3Qtc2VnbWVudD5ib29rbWFyazwvdGd0LXNlZ21lbnQ+PHVzZXItY29tbWVudHM+PC91c2VyLWNvbW1lbnRzPjwvZGljdC1lbnRyeT48ZGljdC1lbnRyeT48c3JjLXNlZ21lbnQ+c29mdHdhcmU8L3NyYy1zZWdtZW50Pjx0Z3Qtc2VnbWVudD5zb2Z0d2FyZTwvdGd0LXNlZ21lbnQ+PHVzZXItY29tbWVudHM+PC91c2VyLWNvbW1lbnRzPjwvZGljdC1lbnRyeT48ZGljdC1lbnRyeT48c3JjLXNlZ21lbnQ+YnJvd3Nlcjwvc3JjLXNlZ21lbnQ+PHRndC1zZWdtZW50Pm5hdmlnYXRldXI8L3RndC1zZWdtZW50Pjx1c2VyLWNvbW1lbnRzPjwvdXNlci1jb21tZW50cz48L2RpY3QtZW50cnk+PC9kaWN0LWVudHJpZXM+PC9kaWN0aW9uYXJ5Pg=="

Example Response:

{
    "dictionaryId": "dict1",
    "sourceLanguageId": "eng",
    "targetLanguageId": "fra"
}

Create a dictionary to be available for use in translation.

HTTP Request

POST /api/v2/dictionaries

Request Parameters

Name Type Description Default Value
dictionaryId string Identifier of dictionary:
  • Must not contain any of the following characters: / " , % +
  • Must not only be . or \
  • Must be unique across all language pairs
sourceLanguageId string Source language (3-letter code)
targetLanguageId string Target language (3-letter code)
content string Base64-encoded and URL-encoded content of the dictionary in XML format (an example before base64-encoding can be found in the example response of Download a dictionary)

Returns

Returns the newly-created dictionary as a Dictionary object.

Update a dictionary

Example Request:

curl "https://master-host:8001/api/v2/dictionaries/dict1" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    --data-urlencode content="PGRpY3Rpb25hcnk+PGRpY3QtZW50cmllcz48ZGljdC1lbnRyeT48c3JjLXNlZ21lbnQ+Ym9va21hcms8L3NyYy1zZWdtZW50Pjx0Z3Qtc2VnbWVudD5ib29rbWFyazwvdGd0LXNlZ21lbnQ+PHVzZXItY29tbWVudHM+PC91c2VyLWNvbW1lbnRzPjwvZGljdC1lbnRyeT48ZGljdC1lbnRyeT48c3JjLXNlZ21lbnQ+YnJvd3Nlcjwvc3JjLXNlZ21lbnQ+PHRndC1zZWdtZW50Pm5hdmlnYXRldXI8L3RndC1zZWdtZW50Pjx1c2VyLWNvbW1lbnRzPjwvdXNlci1jb21tZW50cz48L2RpY3QtZW50cnk+PC9kaWN0LWVudHJpZXM+PC9kaWN0aW9uYXJ5Pgo="

Example Response:

{
    "dictionaryId": "dict1",
    "sourceLanguageId": "eng",
    "targetLanguageId": "fra"
}

Update an existing dictionary.

HTTP Request

PUT /api/v2/dictionaries/{dictionaryId}

Path Parameters

Name Type Description
dictionaryId string Identifier of dictionary

Request Parameters

Name Type Description Default Value
content string Base64-encoded and URL-encoded content of the dictionary in XML format (an example before base64-encoding can be found in the example response of Download a dictionary)

Returns

Returns the updated dictionary Dictionary object.

Retrieve a dictionary

Example Request:

curl "https://master-host:8001/api/v2/dictionaries/dict1?includeContent=true" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "dictionaryId": "dict1",
    "sourceLanguageId": "eng",
    "targetLanguageId": "fra",
    "content": "PGRpY3Rpb25hcnk+PGRpY3QtZW50cmllcz48ZGljdC1lbnRyeT48c3JjLXNlZ21lbnQ+Ym9va21hcms8L3NyYy1zZWdtZW50Pjx0Z3Qtc2VnbWVudD5ib29rbWFyazwvdGd0LXNlZ21lbnQ+PHVzZXItY29tbWVudHM+PC91c2VyLWNvbW1lbnRzPjwvZGljdC1lbnRyeT48ZGljdC1lbnRyeT48c3JjLXNlZ21lbnQ+c29mdHdhcmU8L3NyYy1zZWdtZW50Pjx0Z3Qtc2VnbWVudD5zb2Z0d2FyZTwvdGd0LXNlZ21lbnQ+PHVzZXItY29tbWVudHM+PC91c2VyLWNvbW1lbnRzPjwvZGljdC1lbnRyeT48ZGljdC1lbnRyeT48c3JjLXNlZ21lbnQ+YnJvd3Nlcjwvc3JjLXNlZ21lbnQ+PHRndC1zZWdtZW50Pm5hdmlnYXRldXI8L3RndC1zZWdtZW50Pjx1c2VyLWNvbW1lbnRzPjwvdXNlci1jb21tZW50cz48L2RpY3QtZW50cnk+PC9kaWN0LWVudHJpZXM+PC9kaWN0aW9uYXJ5Pg=="
}

Return the description, and optionally the contents, of a dictionary.

HTTP Request

GET /api/v2/dictionaries/{dictionaryId}

Path Parameters

Name Type Description
dictionaryId string Identifier of dictionary

Request Parameters

Name Type Description Default Value
includeContent (optional) bool Include the base64-encoded contents of the dictionary false

Returns

Returns the specified dictionary as a Dictionary object with the following attributes:

Name Type Description
dictionaryId string Identifier of dictionary
sourceLanguageId string Source language (3-letter code)
targetLanguageId string Target language (3-letter code)
content string Base64-encoded content of the dictionary in XML format; only included when retrieving a dictionary with includeContent set to true

Download a dictionary

Example Request:

curl "https://master-host:8001/api/v2/dictionaries/dict1/download" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

<dictionary>
    <dict-entries>
        <dict-entry>
            <src-segment>bookmark</src-segment>
            <tgt-segment>bookmark</tgt-segment>
            <user-comments></user-comments>
        </dict-entry>
        <dict-entry>
            <src-segment>software</src-segment>
            <tgt-segment>software</tgt-segment>
            <user-comments></user-comments>
        </dict-entry>
        <dict-entry>
            <src-segment>browser</src-segment>
            <tgt-segment>navigateur</tgt-segment>
            <user-comments></user-comments>
        </dict-entry>
    </dict-entries>
</dictionary>

Download a dictionary in XML format.

HTTP Request

GET /api/v2/dictionaries/{dictionaryId}/download

Path Parameters

Name Type Description
dictionaryId string Identifier of dictionary

Returns

Returns the XML contents of a dictionary with MIME type text/xml and filename dictionary.<dictionaryId>.<sourceLanguageId>-<targetLanguageId>.xml, like dictionary.dict1.eng-fra.xml.

Delete a dictionary

Example Request:

curl "https://master-host:8001/api/v2/dictionaries/dict1" \
    -X DELETE \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "dictionaryId": "dict1",
    "sourceLanguageId": "eng",
    "targetLanguageId": "fra"
}

Remove a dictionary so it can no longer be used in translation.

HTTP Request

DELETE /api/v2/dictionaries/{dictionaryId}

Path Parameters

Name Type Description
dictionaryId string Identifier of dictionary

Returns

Returns the deleted dictionary as a Dictionary object.

Language Pairs

List language pairs

Example Request:

curl "https://master-host:8001/api/v2/language-pairs?chains=also" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "languagePairs": [
        {
            "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
            "sourceLanguage": "English",
            "sourceLanguageId": "eng",
            "targetLanguage": "French",
            "targetLanguageId": "fra",
            "domain": "Generic",
            "platform": "SRV",
            "technology": "TNMV",
            "version": "8.4.1"
        },
        {
            "languagePairId": "SpaEng_Generic_SRV_TNMV_8_4_x_2",
            "sourceLanguage": "Spanish",
            "sourceLanguageId": "spa",
            "targetLanguage": "English",
            "targetLanguageId": "eng",
            "domain": "Generic",
            "platform": "SRV",
            "technology": "TNMV",
            "version": "8.4.2"
        },
        {
            "languagePairId": "SpaEng_Generic_SRV_TNMV_8_4_x_2\u003e\u003eEngFra_Generic_SRV_TNMV_8_4_x_1",
            "sourceLanguage": "Spanish",
            "sourceLanguageId": "spa",
            "targetLanguage": "French",
            "targetLanguageId": "fra",
            "domain": "Generic",
            "platform": "SRV",
            "technology": "TNMV",
            "version": "",
            "memberPairs": [
                {
                    "languagePairId": "SpaEng_Generic_SRV_TNMV_8_4_x_2",
                    "sourceLanguage": "Spanish",
                    "sourceLanguageId": "spa",
                    "targetLanguage": "English",
                    "targetLanguageId": "eng",
                    "domain": "Generic",
                    "platform": "SRV",
                    "technology": "TNMV",
                    "version": "8.4.2"
                },
                {
                    "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
                    "sourceLanguage": "English",
                    "sourceLanguageId": "eng",
                    "targetLanguage": "French",
                    "targetLanguageId": "fra",
                    "domain": "Generic",
                    "platform": "SRV",
                    "technology": "TNMV",
                    "version": "8.4.1"
                }
            ],
            "isChain": true
        }
    ]
}

Return the list of language pairs that are currently installed, licensed, or available for translation.

HTTP Request

GET /api/v2/language-pairs

Request Parameters

Name Type Description Default Value
mode (optional) string Query mode, which subset of language pairs to list. Possible choices: translation - language pairs available for translation, installed - installed language pairs, licensed - licensed language pairs, installedAndLicensed - installed and licensed language pairs, adaptable - adaptable language pairs translation
chains (optional) string Include chains, non-chains or all. Valid values: only for just chains, also for single language pairs and chains, or excluded for just single language pairs also

Returns

Returns all language pairs as a LanguagePairList object with the following attributes:

Name Type Description
languagePairs array of objects List of language pairs as an array of LanguagePair objects (expanded below)
→ languagePairId string Identifier of language pair
→ sourceLanguage string Full name of source language
→ sourceLanguageId string 3-letter code of source language
→ targetLanguage string Full name of target language
→ targetLanguageId string 3-letter code of target language
→ domain string Domain of language pair
→ platform string Platform on which language pair runs
→ technology string Technology type of language pair
→ version string Version of the language pair
→ isEdgeCloud bool Whether the language pair is on Edge Cloud. Non-edge-cloud LPs do not have this.
→ adaptable bool Whether the language pair is adaptable. Non-adaptable LPs do not have this.
→ memberPairs array of objects List of single language pairs, represented as LanguagePair objects that comprise the language pair chain. Non-chain LPs do not have this.
→ isChain bool Whether the language pair is a chain. Always true if present. Non-chain LPs do not have this.

Automatically managed chains only exist as long as all of their member language pairs are running in active translation engines, so setting the mode has no effect on which automanaged chains are listed. Effectively it is as if mode were always translation for automanaged chains. However, manually added chains behave like single language pairs with respect to mode.

Language pair chains are never adaptable, however it is possible to use adapted single language pairs as members of a language pair chain.

Translation Chains

List translation chains

Example Request:

curl "https://master-host:8001/api/v2/translation-chains" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "chains": [
        {
            "config": {
                "id": "SpaEng_Generic_SRV_TNMV_8_4_x_2\u003e\u003eEngFra_Generic_SRV_TNMV_8_4_x_1",
                "label": "SpaFra_c3b0",
                "memberPairs": [
                    "SpaEng_Generic_SRV_TNMV_8_4_x_2",
                    "EngFra_Generic_SRV_TNMV_8_4_x_1"
                ],
                "isEdgeCloud": false
            },
            "autoManage": false,
            "isDeleted": false,
            "running": true,
            "expectedRunning": true
        }
    ],
    "options": {
        "includeDeleted": "excluded"
    }
}

Return a list of all defined translation chains

HTTP Request

GET /api/v2/translation-chains

Request Parameters

Name Type Description Default Value
includeDeleted (optional) string Whether to include manually deleted chains. Valid values: only for just deleted chains, also for active and deleted chains, or excluded for just active chains excluded

Returns

Returns a list of translation chains as a TranslationChainsStatus object with the following attributes

Name Type Description
chains array of objects List of translation chains as an array of TranslationChainStatus objects
options object A TranslationChainsStatusOptions object with attribute:
→ includeDeleted string Value of the includeDeleted request parameter

Add a translation chain

Example Request:

curl "https://master-host:8001/api/v2/translation-chains" \
    -X POST \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d chainId="SpaEng_Generic_SRV_TNMV_8_4_x_2>>EngFra_Generic_SRV_TNMV_8_4_x_1"

Example Response:

{
    "config": {
        "id": "SpaEng_Generic_SRV_TNMV_8_4_x_2\u003e\u003eEngFra_Generic_SRV_TNMV_8_4_x_1",
        "label": "SpaFra_c3b0",
        "memberPairs": [
            "SpaEng_Generic_SRV_TNMV_8_4_x_2",
            "EngFra_Generic_SRV_TNMV_8_4_x_1"
        ],
        "isEdgeCloud": false
    },
    "autoManage": false,
    "isDeleted": false,
    "running": true,
    "expectedRunning": true
}

Adds a new translation chain

HTTP Request

POST /api/v2/translation-chains

Request Parameters

Name Type Description Default Value
chainId string Translation chain ID for the translation chain to add consisting of two member language pair IDs joined by the string ’>>’

Returns

Returns the added translation chain as a TranslationChainStatus object with the following attributes

Name Type Description
config object Object describing basic information about the translation chain represented as a TranslationChainConfig object with these attributes:
→ id string The full language pair chain ID, e.g., lpid1>>lpid2
→ label string A short string naming the chain. For UI generation.
→ memberPairs array of strings List of the single language pair IDs that compose the chain.
→ isEdgeCloud boolean True if this chain should be treated as an EdgeCloud chain.
autoManage bool True if this chain is being automatically managed by MTE, false if it is under manual management.
isDeleted bool True if this represents a translation chain that has been manually deleted.
running bool True if this chain and all its resources are running, and it is possible to submit translations to it.
expectedRunning bool True if it is expected that this chain and all of its resources are running, and it should be possible to submit translations to it.

Adding a translation chain also places that chain under manual management. It will always be present even if the underlying resources are not available. To move a chain that has been manually added to automated management use the PUT /api/v2/translation-chains/{id} endpoint and set autoManage to true. Under automated management the translation chain will be present when its underlying resources are available and will be removed while the underlying resources are not available.

Update translation chain

Example Request:

curl "https://master-host:8001/api/v2/translation-chains/SpaEng_Generic_SRV_TNMV_8_4_x_2>>EngFra_Generic_SRV_TNMV_8_4_x_1" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d autoManage="true"

Example Response:

{
    "config": {
        "id": "SpaEng_Generic_SRV_TNMV_8_4_x_2\u003e\u003eEngFra_Generic_SRV_TNMV_8_4_x_1",
        "label": "SpaFra_c3b0",
        "memberPairs": [
            "SpaEng_Generic_SRV_TNMV_8_4_x_2",
            "EngFra_Generic_SRV_TNMV_8_4_x_1"
        ],
        "isEdgeCloud": false
    },
    "autoManage": true,
    "isDeleted": false,
    "running": true,
    "expectedRunning": true
}

Modify translation chain attributes

HTTP Request

PUT /api/v2/translation-chains/{id}

Path Parameters

Name Type Description
id string Translation chain ID to modify

Request Parameters

Name Type Description Default Value
autoManage (optional) bool Whether this chain should be automatically managed (true) or not (false). Does not need to be an active chain. Automatic chain management must be enabled to use this.

Returns

Returns the modified translation chain as a TranslationChainStatus object.

Delete translation chain

Example Request:

curl "https://master-host:8001/api/v2/translation-chains/SpaEng_Generic_SRV_TNMV_8_4_x_2>>EngFra_Generic_SRV_TNMV_8_4_x_1" \
    -X DELETE \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "config": {
        "id": "SpaEng_Generic_SRV_TNMV_8_4_x_2\u003e\u003eEngFra_Generic_SRV_TNMV_8_4_x_1",
        "label": "SpaFra_c3b0",
        "memberPairs": [
            "SpaEng_Generic_SRV_TNMV_8_4_x_2",
            "EngFra_Generic_SRV_TNMV_8_4_x_1"
        ],
        "isEdgeCloud": false
    },
    "autoManage": false,
    "isDeleted": false,
    "running": true,
    "expectedRunning": true
}

Delete a translation chain. Also prevents the chain from being recreated when automated chain management is enabled.

HTTP Request

DELETE /api/v2/translation-chains/{id}

Path Parameters

Name Type Description
id string Translation chain ID to delete

Returns

Returns the deleted translation chain as a TranslationChainStatus object. The value will represent the chain as it was before deletion.

Deleting a translation chain also places that chain under manual management. It will never be present even if the underlying resources are available and it could be used. To move a chain that has been manually deleted to automated management use the PUT /api/v2/translation-chains/{id} endpoint and set autoManage to true. Under automated management the translation chain will be present when its underlying resources are available and will be removed while the underlying resources are not available.

Users

List users

Example Request:

curl "https://master-host:8001/api/v2/users" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "users": [
        {
            "username": "admin@example.com",
            "displayName": "Admin",
            "roles": [
                "admin"
            ]
        },
        {
            "username": "user@example.com",
            "displayName": "User",
            "roles": [
                ""
            ]
        }
    ],
    "page": 1,
    "perPage": 25,
    "totalPages": 1,
    "totalItems": 2
}

Return a list of users.

HTTP Request

GET /api/v2/users

Request Parameters

Name Type Description Default Value
page (optional) int Page number to return 1
perPage (optional) int Number of users to return per page 25

Returns

Returns a list of users a UserList object with the following attributes:

Name Type Description
users array of objects List of users as an array of User objects
page int Page number returned
perPage int Number of users returned per page
totalPages int Total number of pages available
totalItems int Total number of users

Create a user

Example Request:

curl "https://master-host:8001/api/v2/users" \
    -X POST \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    --data-urlencode displayName="User" \
    --data-urlencode username="user@example.com"

Example Response:

{
    "username": "user@example.com",
    "displayName": "User",
    "roles": [
        ""
    ]
}

Create a new user and optionally specify a password.

HTTP Request

POST /api/v2/users

Request Parameters

Name Type Description Default Value
username string Email address of user
displayName string Name of the user to display
roles (optional) string Roles to assign user, separated by commas; only role currently supported is admin or none (for non-admin)
password (optional) string Must be at least 6 characters in length; if not set, an automatically-generated password will be sent to the user’s email address

Returns

Returns the newly-created user as a User object with the following attributes:

Name Type Description
username string Email address of user
displayName string Name of the user to display
roles array of strings Roles assigned to user

Update a user

Example Request:

curl "https://master-host:8001/api/v2/users/user@example.com" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d roles="admin" \
    --data-urlencode displayName="Manager"

Example Response:

{
    "username": "user@example.com",
    "displayName": "Manager",
    "roles": [
        "admin"
    ]
}

Change a user’s display name or role. Usernames cannot be changed.

HTTP Request

PUT /api/v2/users/{username}

Path Parameters

Name Type Description
username string Username (email address) of user

Request Parameters

Name Type Description Default Value
displayName (optional) string New name of the user to display
roles (optional) string Roles to assign user, separated by commas (empty input will remove all current roles for the user)

Returns

Returns the updated user as a User object.

Retrieve a user

Example Request:

curl "https://master-host:8001/api/v2/users/user@example.com" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "username": "user@example.com",
    "displayName": "User",
    "roles": [
        ""
    ]
}

Return information about a user.

HTTP Request

GET /api/v2/users/{id}

Path Parameters

Name Type Description
id string Identifier of user: username or access token, depending on the value of field; if field is username, the special value of me must be used in order to refer to the currently authenticated user

Request Parameters

Name Type Description Default Value
field (optional) string Field by which to look up user (possible choices: username or accessToken) username

Returns

Returns the specified user as a User object.

Create a reset password request by a regular user.

Example Request:

curl "https://master-host:8001/api/v2/users/user@example.com/password/request-reset-self" \
    -X POST

Example Response:

{
    "username": "user@example.com",
    "resetPasswordUrl": "The password reset instructions have been sent to your email",
    "expirationInHours": 24
}

Create a reset password request, and email it to a user’s email address. This call will fail if SMTP is not configured.

HTTP Request

POST /api/v2/users/{username}/password/request-reset-self

Path Parameters

Name Type Description
username string Username (email address) of user

Returns

Returns a ResetPasswordRequest object with the following attributes:

Name Type Description
username string Username and email address of user to which reset password request was sent (if SMTP was enabled)
resetPasswordUrl string A message informing the user to check their email. The secret token is hidden for security reasons
expirationInHours int Hours until reset password URL expires

Create a reset password request by an Administrator

Example Request:

curl "https://master-host:8001/api/v2/users/user@example.com/password/request-reset" \
    -X POST \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    --data-urlencode callbackUrl="https://your-app:7777/reset-password"

Example Response:

{
    "username": "user@example.com",
    "resetPasswordUrl": "https://your-app:7777/reset-password?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ",
    "expirationInHours": 24
}

Create a reset password request, and optionally email it to the user. If SMTP is not configured, no email will be sent. For custom integrations with this API, a webpage will need to be set up where the user can be sent to change their password. In the example to the right, https://your-app:7777/reset-password is the callback URL, and notice that the reset password token is appended as a token query string parameter.

HTTP Request

POST /api/v2/users/{username}/password/request-reset

Path Parameters

Name Type Description
username string Username (email address) of user

Request Parameters

Name Type Description Default Value
callbackUrl (optional) string URL to which a reset token is appended (as the query string parameter token) and which is emailed to the user [private web URL]
suppressEmail (optional) bool If true, do not send an automated email to the user’s email address false

Returns

Returns a ResetPasswordRequest object with the following attributes:

Name Type Description
username string Username and email address of user to which reset password request was sent (if SMTP was enabled)
resetPasswordUrl string URL where user can reset their password; URL included in the reset password request email
expirationInHours int Hours until reset password URL expires

Change a user’s password with the old password

Example Request:

curl "https://master-host:8001/api/v2/users/user@example.com/password" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    --data-urlencode newPassword="atLeast6Char" \
    --data-urlencode oldPassword="noMaxLength"

Example Response:

{
    "username": "user@example.com",
    "displayName": "User",
    "roles": [
        ""
    ]
}

Change a user’s password by providing the old password and requiring it to match the existing password. Admin users can change the password of any user, while non-admin users can only change their own password using the special username value of me.

HTTP Request

PUT /api/v2/users/{username}/password

Path Parameters

Name Type Description
username string Username (email address) of user; the special value of me must be used in order to refer to the currently authenticated user

Request Parameters

Name Type Description Default Value
oldPassword string Old password that must be valid before password can be changed
newPassword string New password that must be at least 6 characters in length

Returns

Returns the updated user (new password not included for security reasons) as a User object.

Change a user’s password with a reset token

Example Request:

curl "https://master-host:8001/api/v2/users/user@example.com/password/reset-token" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    --data-urlencode newPassword="atLeast6Char" \
    --data-urlencode resetToken="<token>"

Example Response:

{
    "username": "user@example.com",
    "displayName": "User",
    "roles": [
        ""
    ]
}

Change a user’s password by providing a valid reset token, which is obtained by first creating a reset password request.

HTTP Request

PUT /api/v2/users/{username}/password/reset-token

Path Parameters

Name Type Description
username string Username (email address) of user

Request Parameters

Name Type Description Default Value
resetToken string Reset token that must be valid before password can be changed
newPassword string New password that must be at least 6 characters in length

Returns

Returns the updated user (new password not included for security reasons) as a User object.

Retrieve API credentials for the current user

Example Request:

curl "https://master-host:8001/api/v2/users/me/credentials" \
    -X GET \
    -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gU21pdGgiLCJpYXQiOjE1MTYyMzkwMjJ9.Q_w2AVguPRU2KskCXwR7ZHl09TQXEntfEA8Jj2_Jyew"

Example Response:

{
    "key": "u_user@example.com_r7eHQ7t9o1Jb"
}

Retrieve the API credentials for the current user. In case you need to recover your API key, you can call this endpoint using token authentication, provided you know your username and password.

HTTP Request

GET /api/v2/users/me/credentials

Returns

Returns the current user’s API credentials as an ApiCredentials object with the following attributes:

Name Type Description
key string Key for accessing SDL MTE REST API as the current user

Change API credentials for the current user

Example Request:

curl "https://master-host:8001/api/v2/users/me/credentials" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    --data-urlencode key="u_user@example.com_bluebird"

Example Response:

{
    "key": "u_user@example.com_bluebird"
}

Change the API credentials for the current user.

HTTP Request

PUT /api/v2/users/me/credentials

Request Parameters

Name Type Description Default Value
key string New API key to change to. It must be of the form u_username_string, where username is the current user’s username, string consists of letters and/or numbers, and the entire key is at most 255 characters long (e.g., u_user@example.com_bluebird).

Returns

Returns the updated API credentials as an ApiCredentials object.

Delete a user

Example Request:

curl "https://master-host:8001/api/v2/users/user@example.com" \
    -X DELETE \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "username": "user@example.com",
    "displayName": "User",
    "roles": [
        ""
    ]
}

Delete a user’s account. No notification will be sent to the user’s email address.

HTTP Request

DELETE /api/v2/users/{username}

Path Parameters

Name Type Description
username string Username (email address) of user

Returns

Returns the deleted user as a User object.

Hosts

List hosts

Example Request:

curl "https://master-host:8001/api/v2/hosts" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "hosts": [
        {
            "hostname": "master-host",
            "hostAgentPort": 4637,
            "hostAgentRunning": true,
            "languagePairs": {
                "EngFra_Generic_SRV_TNMV_8_4_x_1": true,
                "SpaEng_Generic_SRV_TNMV_8_4_x_2": true
            },
            "jobEngines": [
                {
                    "config": {
                        "id": "34a2",
                        "host": "master-host",
                        "hostAgentPort": 4637
                    },
                    "running": true,
                    "expectedRunning": true
                }
            ],
            "translationEngines": [
                {
                    "config": {
                        "id": "a1d8",
                        "host": "master-host",
                        "hostAgentPort": 4637,
                        "languagePair": "EngFra_Generic_SRV_TNMV_8_4_x_1",
                        "isEdgeCloud": false
                    },
                    "running": true,
                    "expectedRunning": true
                },
                {
                    "config": {
                        "id": "onw8",
                        "host": "master-host",
                        "hostAgentPort": 4637,
                        "languagePair": "SpaEng_Generic_SRV_TNMV_8_4_x_2",
                        "isEdgeCloud": false
                    },
                    "running": true,
                    "expectedRunning": true
                }
            ]
        }
    ]
}

Return the list of all hosts.

HTTP Request

GET /api/v2/hosts

Returns

Returns all hosts as a HostList object with the following attributes:

Name Type Description
hosts array of objects List of all hosts as an array of Host objects

Add a host

Example Request:

curl "https://master-host:8001/api/v2/hosts" \
    -X POST \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d hostAgentPort="4637" \
    -d hostname="master-host"

Example Response:

{
    "hostname": "master-host",
    "hostAgentPort": 4637,
    "hostAgentRunning": true,
    "languagePairs": {
        "EngFra_Generic_SRV_TNMV_8_4_x_1": true,
        "SpaEng_Generic_SRV_TNMV_8_4_x_2": true
    }
}

Add a new host, which can serve job engine(s) and/or translation engine(s). This host must already have SDL MTE installed and its Host Agent running. This host can be either a Master host or a Worker host, so long as there is only one Master host in the entire SDL MTE deployment.

HTTP Request

POST /api/v2/hosts

Request Parameters

Name Type Description Default Value
hostname string Name of host
hostAgentPort int Port where Host Agent is running

Returns

Returns the newly-added host as a Host object with the following attributes:

Name Type Description
hostname string Name of host
hostAgentPort int Port where this host’s Host Agent is running
hostAgentRunning bool Whether this host’s Host Agent is running
languagePairs map from string to bool For each language pair installed on this host, the language pair identifier (string) and whether it is licensed on this host (bool)
jobEngines array of objects List of job engines on this host as an array of JobEngine objects
translationEngines array of objects List of translation engines on this host as an array of TranslationEngine objects

Retrieve host profile

Example Request:

curl "https://master-host:8001/api/v2/hosts/master-host/profile" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "gpus": {
        "driverVersion": "396.37",
        "count": 2,
        "gpu": [
            {
                "modelName": "GeForce GTX 1080 Ti",
                "memoryUsage": {
                    "totalInMB": 11178,
                    "freeInMB": 11178,
                    "usedInMB": 0
                },
                "utilization": "0 %",
                "processes": [
                    {
                        "pid": 15724,
                        "processName": "/opt/sdl/ets/bin/ets-engine",
                        "usedMemoryInMB": 674
                    }
                ]
            }
        ]
    },
    "memory": {
        "totalInMB": 32011,
        "freeInMB": 2105,
        "usedInMB": 3713
    },
    "cpu": [
        {
            "modelName": "Intel(R) Xeon(R) CPU X5650 @ 2.67GHz",
            "cores": 2,
            "cacheSizeInMB": 12288,
            "clockSpeedInMHz": 2660,
            "flags": [
                "fpu",
                "vme",
                "de",
                "pse",
                "tsc",
                "msr",
                "pae",
                "mce",
                "cx8",
                "apic",
                "sep",
                "mtrr",
                "pge",
                "mca",
                "cmov",
                "pat",
                "pse36",
                "pn",
                "clflush",
                "dts",
                "acpi",
                "mmx",
                "fxsr",
                "sse",
                "sse2",
                "ss",
                "ht",
                "tm",
                "ia64",
                "pbe"
            ]
        }
    ],
    "disk": [
        {
            "path": "/",
            "totalInMB": 201456,
            "usedInMB": 28325,
            "freeInMB": 162875
        }
    ]
}

Retrieves the system configuration profile of the specified host

HTTP Request

GET /api/v2/hosts/{hostname}/profile

Path Parameters

Name Type Description
hostname string Name of host

Returns

Returns the system configuration profile of a host as a HostSystemProfile object.

Name Type Description
gpus object Profile of GPUs on host (expanded below)
→ driverVersion string Version of the GPU driver being used
→ count int Number of GPUs available on host
gpu array of objects List of profiles of GPUs on host (expanded below)
→ → modelName string Model name of GPU
→ → memoryUsage object Memory usage of the GPU (expanded below)
→ → → totalInMB int Total amount of frame buffer memory available on GPU
→ → → freeInMB int Amount of memory on GPU not being used
→ → → usedInMB int Amount of memory being used on GPU
→ → utilization string Percentage of GPU being used
→ → processes array of objects List of processes using the GPU (expanded below)
→ → → pid int ID of process
→ → → processName string Name of process
→ → → usedMemoryInMB int Amount of memory being used by process on GPU
memory object Profile of memory on host
→ totalInMB int Total amount of memory available
→ freeInMB int Amount of memory not being used
→ usedInMB int Amount of memory being used
cpu array of objects List of profiles of CPUs on host
→ modelName string Model name of CPU
→ cores int Number of CPU cores
→ cacheSizeInMB string Cache size of CPU
→ clockSpeedInMHz int Clock speed of CPU
→ flags array of strings Flags of CPU
disk array of objects List of profiles of disks and disk space on host
→ path string Path to mountpoint of disk
→ totalInMB int Total amount of memory available on disk
→ freeInMB int Amount of memory not being used on disk
→ usedInMB int Amount of memory being used on disk

Delete a host

Example Request:

curl "https://master-host:8001/api/v2/hosts/master-host" \
    -X DELETE \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "hostname": "master-host",
    "hostAgentPort": 4637,
    "hostAgentRunning": true,
    "languagePairs": {
        "EngFra_Generic_SRV_TNMV_8_4_x_1": true,
        "SpaEng_Generic_SRV_TNMV_8_4_x_2": true
    }
}

Delete a host so it can no longer be used to serve job engines or translation engines. This will also delete all the job engines and translation engines that were previously added to the host.

HTTP Request

DELETE /api/v2/hosts/{hostname}

Path Parameters

Name Type Description
hostname string Name of host

Returns

Returns the deleted host as a Host object.

Add a job engine

Example Request:

curl "https://master-host:8001/api/v2/hosts/master-host/job-engines" \
    -X POST \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d id="34a2"

Example Response:

{
    "config": {
        "id": "34a2",
        "host": "master-host",
        "hostAgentPort": 4637
    },
    "running": false,
    "expectedRunning": false
}

Add a job engine to a host.

HTTP Request

POST /api/v2/hosts/{hostname}/job-engines

Path Parameters

Name Type Description
hostname string Name of host

Request Parameters

Name Type Description Default Value
id (optional) string Identifier to name job engine; must be unique, no more than 20 characters, and contain only alphanumeric characters or an underscore; if not specified, a random identifier will be generated

Returns

Returns the newly-added job engine as a JobEngine object with the following attributes:

Name Type Description
config object Configuration of job engine (expanded below)
→ id string Identifier of job engine
→ host string Name of host on which job engine is running
→ hostAgentPort string Host Agent port
running bool Whether this job engine is actually running
expectedRunning bool Whether this job engine is expected to be running

Start a job engine

Example Request:

curl "https://master-host:8001/api/v2/hosts/master-host/job-engines/34a2/start" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "config": {
        "id": "34a2",
        "host": "master-host",
        "hostAgentPort": 4637
    },
    "running": false,
    "expectedRunning": true
}

Start an existing job engine so it is available for translation requests.

HTTP Request

PUT /api/v2/hosts/{hostname}/job-engines/{engineId}/start

Path Parameters

Name Type Description
hostname string Name of host
engineId string Identifier of job engine

Returns

Returns the started job engine as a JobEngine object.

Stop a job engine

Example Request:

curl "https://master-host:8001/api/v2/hosts/master-host/job-engines/34a2/stop" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "config": {
        "id": "34a2",
        "host": "master-host",
        "hostAgentPort": 4637
    },
    "running": true,
    "expectedRunning": false
}

Stop an existing job engine so it is no longer available for translation requests. Some in progress translation jobs may be lost, so it is recommended to wait for all jobs to complete before proceeding.

HTTP Request

PUT /api/v2/hosts/{hostname}/job-engines/{engineId}/stop

Path Parameters

Name Type Description
hostname string Name of host
engineId string Identifier of job engine

Returns

Returns the stopped job engine as a JobEngine object.

Delete a job engine

Example Request:

curl "https://master-host:8001/api/v2/hosts/master-host/job-engines/34a2" \
    -X DELETE \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "config": {
        "id": "34a2",
        "host": "master-host",
        "hostAgentPort": 4637
    },
    "running": true,
    "expectedRunning": true
}

Delete a job engine from a host. Some in progress translation jobs may be lost, so it is recommended to wait for all jobs to complete before proceeding.

HTTP Request

DELETE /api/v2/hosts/{hostname}/job-engines/{engineId}

Path Parameters

Name Type Description
hostname string Name of host
engineId string Identifier of job engine

Returns

Returns the deleted job engine as a JobEngine object.

Add a translation engine

Example Request:

curl "https://master-host:8001/api/v2/hosts/master-host/translation-engines" \
    -X POST \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d desiredProcessingUnits="2" \
    -d id="a1d8" \
    -d languagePair="EngFra_Generic_SRV_TNMV_8_4_x_1"

Example Response:

{
    "config": {
        "id": "a1d8",
        "host": "master-host",
        "hostAgentPort": 4637,
        "languagePair": "EngFra_Generic_SRV_TNMV_8_4_x_1",
        "isEdgeCloud": false,
        "desiredProcessingUnits": 2
    },
    "running": false,
    "expectedRunning": false
}

Add a translation engine with a specific language pair to a host.

HTTP Request

POST /api/v2/hosts/{hostname}/translation-engines

Path Parameters

Name Type Description
hostname string Name of host

Request Parameters

Name Type Description Default Value
languagePair string Language pair to serve – must be a language pair already installed and licensed on this host
desiredProcessingUnits (optional) int Number of processing units desired to assign to this translation engine 1
id (optional) string Identifier to name translation engine; must be unique, no more than 20 characters, and contain only alphanumeric characters or an underscore; if not specified, a random identifier will be generated
mode (optional) string Translation engine mode that is available only for NMT language pairs (either gpu - optimized for quality, gpuSpeed - optimized for speed, cpu - optimized for quality, cpuSpeed - optimized for speed, or left blank for auto-detect)

Returns

Returns the newly-added translation engine as a TranslationEngine object with the following attributes:

Name Type Description
config object Configuration of translation engine (expanded below)
→ id string Identifier of translation engine
→ host string Name of host on which translation engine is running
→ languagePair string Language pair configured for translation on this translation engine
→ hostAgentPort string Host Agent port
→ isEdgeCloud bool Whether language pair is on Edge Cloud
→ desiredProcessingUnits int Number of processing units desired to assign to this translation engine
→ mode string Translation engine mode
running bool Whether this translation engine is actually running
expectedRunning bool Whether this translation engine is expected to be running

Start a translation engine

Example Request:

curl "https://master-host:8001/api/v2/hosts/master-host/translation-engines/a1d8/start" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "config": {
        "id": "a1d8",
        "host": "master-host",
        "hostAgentPort": 4637,
        "languagePair": "EngFra_Generic_SRV_TNMV_8_4_x_1",
        "isEdgeCloud": false
    },
    "running": false,
    "expectedRunning": true
}

Start an existing translation engine so it is available to produce translations. Some in progress translation jobs may be lost, so it is recommended to wait for all jobs to complete before proceeding.

HTTP Request

PUT /api/v2/hosts/{hostname}/translation-engines/{engineId}/start

Path Parameters

Name Type Description
hostname string Name of host
engineId string Identifier of translation engine

Returns

Returns the started translation engine as a TranslationEngine object.

Stop a translation engine

Example Request:

curl "https://master-host:8001/api/v2/hosts/master-host/translation-engines/a1d8/stop" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "config": {
        "id": "a1d8",
        "host": "master-host",
        "hostAgentPort": 4637,
        "languagePair": "EngFra_Generic_SRV_TNMV_8_4_x_1",
        "isEdgeCloud": false
    },
    "running": true,
    "expectedRunning": false
}

Stop an existing translation engine so it is no longer available to produce translations. Some in progress translation jobs may be lost, so it is recommended to wait for all jobs to complete before proceeding.

HTTP Request

PUT /api/v2/hosts/{hostname}/translation-engines/{engineId}/stop

Path Parameters

Name Type Description
hostname string Name of host
engineId string Identifier of translation engine

Returns

Returns the stopped translation engine as a TranslationEngine object.

Delete a translation engine

Example Request:

curl "https://master-host:8001/api/v2/hosts/master-host/translation-engines/a1d8" \
    -X DELETE \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "config": {
        "id": "a1d8",
        "host": "master-host",
        "hostAgentPort": 4637,
        "languagePair": "EngFra_Generic_SRV_TNMV_8_4_x_1",
        "isEdgeCloud": false
    },
    "running": true,
    "expectedRunning": true
}

Delete a translation engine from a host. This operation will cause all job engines to be stopped, and restarted if they were previously running.

HTTP Request

DELETE /api/v2/hosts/{hostname}/translation-engines/{engineId}

Path Parameters

Name Type Description
hostname string Name of host
engineId string Identifier of translation engine

Returns

Returns the deleted translation engine as a TranslationEngine object.

Add a training engine

Example Request:

curl "https://master-host:8001/api/v2/hosts/master-host/training-engines" \
    -X POST \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d id="d9s4"

Example Response:

{
    "config": {
        "id": "d9s4",
        "host": "master-host",
        "hostAgentPort": 4637
    },
    "running": false,
    "expectedRunning": false
}

Add a training engine to a host.

HTTP Request

POST /api/v2/hosts/{hostname}/training-engines

Path Parameters

Name Type Description
hostname string Name of host

Request Parameters

Name Type Description Default Value
id (optional) string Identifier to name training engine; must be unique, no more than 20 characters, and contain only alphanumeric characters or an underscore; if not specified, a random identifier will be generated

Returns

Returns the newly-added training engine as a TrainingEngine object with the following attributes:

Name Type Description
config object Configuration of training engine (expanded below)
→ id string Identifier of training engine
→ host string Name of host on which training engine is running
→ hostAgentPort string Host Agent port
running bool Whether this training engine is actually running
expectedRunning bool Whether this training engine is expected to be running

Start a training engine

Example Request:

curl "https://master-host:8001/api/v2/hosts/master-host/training-engines/d9s4/start" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "config": {
        "id": "d9s4",
        "host": "master-host",
        "hostAgentPort": 4637
    },
    "running": false,
    "expectedRunning": true
}

Start an existing training engine so it is available for training requests.

HTTP Request

PUT /api/v2/hosts/{hostname}/training-engines/{engineId}/start

Path Parameters

Name Type Description
hostname string Name of host
engineId string Identifier of training engine

Returns

Returns the started training engine as a TrainingEngine object.

Stop a training engine

Example Request:

curl "https://master-host:8001/api/v2/hosts/master-host/training-engines/d9s4/stop" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "config": {
        "id": "d9s4",
        "host": "master-host",
        "hostAgentPort": 4637
    },
    "running": true,
    "expectedRunning": false
}

Stop an existing training engine so it is no longer available for training requests. Some in progress training jobs may be lost, so it is recommended to wait for all jobs to complete before proceeding.

HTTP Request

PUT /api/v2/hosts/{hostname}/training-engines/{engineId}/stop

Path Parameters

Name Type Description
hostname string Name of host
engineId string Identifier of training engine

Returns

Returns the stopped training engine as a TrainingEngine object.

Delete a training engine

Example Request:

curl "https://master-host:8001/api/v2/hosts/master-host/training-engines/d9s4" \
    -X DELETE \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "config": {
        "id": "d9s4",
        "host": "master-host",
        "hostAgentPort": 4637
    },
    "running": true,
    "expectedRunning": true
}

Delete a training engine from a host. Some in progress training jobs may be lost, so it is recommended to wait for all jobs to complete before proceeding.

HTTP Request

DELETE /api/v2/hosts/{hostname}/training-engines/{engineId}

Path Parameters

Name Type Description
hostname string Name of host
engineId string Identifier of training engine

Returns

Returns the deleted training engine as a TrainingEngine object.

Entitlements

Retrieve entitlements

Example Request:

curl "https://master-host:8001/api/v2/entitlements" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "processingUnits": {
        "desired": [
            {
                "translationEngineId": "a1d8",
                "count": 2
            },
            {
                "translationEngineId": "onw8",
                "count": 0
            }
        ],
        "filled": [
            {
                "translationEngineId": "a1d8",
                "count": 1
            },
            {
                "translationEngineId": "onw8",
                "count": 0
            }
        ],
        "total": 1
    }
}

Retrieve the current entitlements configuration.

HTTP Request

GET /api/v2/entitlements

Returns

Returns the entitlements configuration as an EntitlementsStatus object with the following attributes:

Name Type Description
processingUnits object Processing units configuration
→ desired array of objects List of desired assignments of processing units to translation engines
→ → translationEngineId string Identifier of translation engine
→ → processingUnits int Number of processing units desired to be assigned to the translation engine
→ filled array of objects List of processing units actually filled by translation engines
→ → translationEngineId string Identifier of translation engine
→ → processingUnits int Number of processing units actually filled by the translation engine
→ total int Total number of processing units available in license

Update entitlements

Example Request:

curl "https://master-host:8001/api/v2/entitlements" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -H "Content-Type: application/json" \
    -d '{"processingUnits":{"desired":[{"translationEngineId":"a1d8","count":3},{"translationEngineId":"onw8","count":2}]}}'

Change the entitlements configuration. This operation is asynchronous so the change should be made eventually.

HTTP Request

PUT /api/v2/entitlements

Request Body

Entitlements to update, as an EntitlementsRequest object in JSON format, with the following attributes:

Name Type Description Default Value
processingUnits object Processing units configuration
→ desired (optional) array of objects List of desired assignments of processing units to translation engines
→ → translationEngineId (optional) string Identifier of translation engine
→ → processingUnits (optional) int Number of processing units desired to be assigned to the translation engine

Update license file

Example Request:

curl "https://master-host:8001/api/v2/entitlements/license" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    --data-urlencode file="<file>"

Change the currently-active SDL MTE license file.

HTTP Request

PUT /api/v2/entitlements/license

Download the entitlements profile

Example Request:

curl "https://master-host:8001/api/v2/entitlements/profile" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Download the entitlements profile from the installation directory of the host

HTTP Request

GET /api/v2/entitlements/profile

Returns

Returns the entitlements profile used when requesting a license from SDL

Language Pair Adaptation

Retrieve adapted language pairs

Example Request:

curl "https://master-host:8001/api/v2/adapted-language-pairs" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "languagePairs": [
        {
            "trainingId": "05222d9f261ef",
            "languagePairId": "EngFra_Adapted-myAdaptedLP_SRV_PB_8_0_x_0",
            "profile": {
                "sourceLanguageId": "eng",
                "targetLanguageId": "fra",
                "baselineLanguagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
                "comments": "",
                "username": "jsmith@example.com",
                "trainingHost": "master-host"
            },
            "input": {
                "training": {
                    "characters": {
                        "source": 127303,
                        "target": 118796
                    },
                    "words": {
                        "source": 23685,
                        "target": 22621
                    },
                    "translationUnits": 1306
                },
                "test": {
                    "characters": {
                        "source": 98330,
                        "target": 91968
                    },
                    "words": {
                        "source": 18386,
                        "target": 17559
                    },
                    "translationUnits": 1000,
                    "autoExtracted": true
                }
            },
            "bleu": {
                "baseline": 25.3,
                "adapted": 25.3
            },
            "timestamps": {
                "queued": "2019-02-05 13:52:50.98704786Z",
                "trainingStart": "",
                "completed": ""
            },
            "errorMessage": "",
            "state": "training",
            "progress": 54
        }
    ],
    "options": {
        "sourceLanguageId": "",
        "targetLanguageId": "",
        "state": "",
        "sortBy": ""
    },
    "page": 1,
    "perPage": 10,
    "totalPages": 1,
    "totalItems": 1
}

Retrieve the list of adapted language pairs

HTTP Request

GET /api/v2/adapted-language-pairs

Request Parameters

Name Type Description Default Value
sourceLanguageId (optional) string Filters adapted language pairs to those that share the same source language ID
targetLanguageId (optional) string Filters adapted language pairs to those that share the same target language ID
state (optional) string Filters adapted language pairs to those that share the same state
sortBy (optional) string Sorts the returning list by either startDate (descending by queued time) or languagePairId languagePairId

Returns

Returns a list of all adapted language pairs filtered by the given parameters

Name Type Description
languagePairs array of objects List of adapted language pairs as an array of AdaptedLanguagePair objects
page int Page number returned
perPage int Number of adapted language pairs returned per page
totalPages int Total number of pages available
totalItems int Total number of adapted language pairs

Training Job States

The status of a job is represented by a state. There are twelve possible states.

State Description
dispatching job is being dispatched to a training engine
initializing job is beginning training
training job is being trained
computingBleu job is having its bleu score computed
readyToDeploy job has finished training and can be deployed
deploying job is being deployed to a host
deployed job has been deployed to at least one host
undeploying job is being undeployed
deleting job is being deleted
deleted job has been deleted
canceled job has been canceled
failed job has failed

Create an adapted language pair

Example Request:

curl "https://master-host:8001/api/v2/adapted-language-pairs" \
    -X POST \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -H "Content-Type: multipart/form-data" \
    -F baselineLanguagePairId="EngFra_Generic_SRV_TNMV_8_4_x_1"
    -F comments="This is my adapted LP."
    -F hostname="master-host"
    -F name="myAdaptedLP"
    -F testData="@<file>"
    -F trainingData="@<file>"

Example Response:

{
    "trainingId": "05222d9f261ef",
    "languagePairId": "EngFra_Adapted-myAdaptedLP_SRV_PB_8_0_x_0",
    "profile": {
        "sourceLanguageId": "eng",
        "targetLanguageId": "fra",
        "baselineLanguagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
        "comments": "",
        "username": "jsmith@example.com",
        "trainingHost": "master-host"
    },
    "input": {
        "training": {
            "characters": {
                "source": 127303,
                "target": 118796
            },
            "words": {
                "source": 23685,
                "target": 22621
            },
            "translationUnits": 1306
        },
        "test": {
            "characters": {
                "source": 98330,
                "target": 91968
            },
            "words": {
                "source": 18386,
                "target": 17559
            },
            "translationUnits": 1000,
            "autoExtracted": true
        }
    },
    "bleu": {
        "baseline": 25.3,
        "adapted": 25.3
    },
    "timestamps": {
        "queued": "2019-02-05 13:52:50.98704786Z",
        "trainingStart": "",
        "completed": ""
    },
    "errorMessage": "",
    "state": "dispatching"
}

Begin training a language-pair for adaptation

HTTP Request

POST /api/v2/adapted-language-pairs

Request Parameters

Name Type Description Default Value
name string Alphanumeric, unique name of adapted language pair
baselineLanguagePairId string Language pair being adapted
trainingData file A single TMX document or a zip file containing multiple TMX documents to use during training
testData (optional) file TMX document to use when testing the baseline and adapted LPs to measure the BLEU scores
hostname string Name of host to train the language pair on. Host must have the baseline languague pair on it.
comments (optional) string Optional comments to add to the adapted LP

Returns

Returns information on the adapted language pair as an AdaptedLanguagePair object

Name Type Description
trainingId string Identifier of training job
languagePairId string ID of adapted
profile object Description of training job in the queue (expanded below)
→ sourceLanguageId string 3-letter code of the source language of the adapted LP
→ targetLanguageId string 3-letter code of the target language of the adapted LP
→ baselineLanguagePairId string Language pair being adapted
→ comments string Optional comments added to the adapted LP
→ username string username of the creator of the adapted LP
→ trainingHost string host the language pair is trained on
input object Statistics of the data used to train the language pair (expanded below)
→ training object Statistics of the training data
→ → characters object Character count statistics
→ → → source int Character totals of source segments
→ → → target int Character totals of target segments
→ → words object Word count statistics
→ → → source int Word totals of source segments
→ → → target int Word totals of target segments
→ → translationUnits int Number of translation units used for training data
→ test object Statistics of the test data
→ → characters object Character count statistics
→ → → source int Character totals of source segments
→ → → target int Character totals of target segments
→ → words object Word count statistics
→ → → source int Word totals of source segments
→ → → target int Word totals of target segments
→ → translationUnits int Number of translation units used for test data
→ → autoExtracted bool True if the test data was automatically extracted from the input training data. If false, test data was supplied.
bleu object The bleu score results of the adapted language pair versus the baseline language pair’s result (expanded below)
→ baseline float The bleu score of the baseline language pair
→ adapted float The bleu score of the adapted language pair
timestamps object Timestamps of checkpoints in training job progress (expanded below) in UTC
→ queued string When the training job was created before being submitted to a training engine (when state became dispatching)
→ trainingStart string When the training job was submitted to a training engine (when state became initializing)
→ completed string When the training job result was returned from a training engine (when state first became readyToDeploy)
errorMessage string Error message if state is failed
state string Training job state (see table)

Analyze training input data

Example Request:

curl "https://master-host:8001/api/v2/adapted-language-pairs/analyze" \
    -X POST \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -H "Content-Type: multipart/form-data" \
    -F baselineLanguagePairId="EngFra_Generic_SRV_TNMV_8_4_x_1"
    -F name="myAdaptedLP"
    -F testData="@<file>"
    -F trainingData="@<file>"

Example Response:

{
    "processorErrors": [
        "Error processing TMX file /opt/sdl/ets/data/training-queue/EngGer_Adapted-test_SRV_TNM_8_4_x_1/training-set-2.tmx: XML syntax error on line 141: unexpected EOF"
    ],
    "input": {
        "training": {
            "characters": {
                "source": 127303,
                "target": 118796
            },
            "words": {
                "source": 23685,
                "target": 22621
            },
            "translationUnits": 1306
        },
        "test": {
            "characters": {
                "source": 98330,
                "target": 91968
            },
            "words": {
                "source": 18386,
                "target": 17559
            },
            "translationUnits": 1000,
            "autoExtracted": true
        }
    }
}

Analyze training input data for language-pair adaptation

HTTP Request

POST /api/v2/adapted-language-pairs/analyze

Request Parameters

Name Type Description Default Value
name string Alphanumeric, unique name of adapted language pair
baselineLanguagePairId string Language pair being adapted
trainingData file A single TMX document or a zip file containing multiple TMX documents to use during training
testData (optional) file TMX document to use when testing the baseline and adapted LPs to measure the BLEU scores

Returns

Returns anlaysis on the input data as an AdaptedAnalysisResults object

Name Type Description
processorErrors array of objects List of errors the training data processor encountered during analysis
input object Statistics of the data used to train the language pair (expanded below)
→ training object Statistics of the training data
→ → characters object Character count statistics
→ → → source int Character totals of source segments
→ → → target int Character totals of target segments
→ → words object Word count statistics
→ → → source int Word totals of source segments
→ → → target int Word totals of target segments
→ → translationUnits int Number of translation units used for training data
→ test object Statistics of the test data
→ → characters object Character count statistics
→ → → source int Character totals of source segments
→ → → target int Character totals of target segments
→ → words object Word count statistics
→ → → source int Word totals of source segments
→ → → target int Word totals of target segments
→ → translationUnits int Number of translation units used for test data
→ → autoExtracted bool True if the test data was automatically extracted from the input training data. If false, test data was supplied.

Retrieve information on adapted language pairs

Example Request:

curl "https://master-host:8001/api/v2/adapted-language-pairs/EngFra_Adapted-myAdaptedLP_SRV_PB_8_0_x_0" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "trainingId": "05222d9f261ef",
    "languagePairId": "EngFra_Adapted-myAdaptedLP_SRV_PB_8_0_x_0",
    "profile": {
        "sourceLanguageId": "eng",
        "targetLanguageId": "fra",
        "baselineLanguagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
        "comments": "",
        "username": "jsmith@example.com",
        "trainingHost": "master-host"
    },
    "input": {
        "training": {
            "characters": {
                "source": 127303,
                "target": 118796
            },
            "words": {
                "source": 23685,
                "target": 22621
            },
            "translationUnits": 1306
        },
        "test": {
            "characters": {
                "source": 98330,
                "target": 91968
            },
            "words": {
                "source": 18386,
                "target": 17559
            },
            "translationUnits": 1000,
            "autoExtracted": true
        }
    },
    "bleu": {
        "baseline": 25.3,
        "adapted": 25.3
    },
    "timestamps": {
        "queued": "2019-02-05 13:52:50.98704786Z",
        "trainingStart": "",
        "completed": ""
    },
    "errorMessage": "",
    "state": "training",
    "progress": 54
}

Retrieve information on a given adapted language pair

HTTP Request

GET /api/v2/adapted-language-pairs/{languagePairId}

Path Parameters

Name Type Description
languagePairId string ID of adapted language pair

Request Parameters

Name Type Description Default Value
includeTestData (optional) bool Whether to include test data in the response false
includeTrainingData (optional) bool Whether to include training data in the response false

Returns

Returns information on the adapted language pair as an AdaptedLanguagePair object

Update a language pair adaptation

Example Request:

curl "https://master-host:8001/api/v2/adapted-language-pairs/EngFra_Adapted-myAdaptedLP_SRV_PB_8_0_x_0" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d comments="This is my new adapted LP comment."

Example Response:

{
    "trainingId": "05222d9f261ef",
    "languagePairId": "EngFra_Adapted-myAdaptedLP_SRV_PB_8_0_x_0",
    "profile": {
        "sourceLanguageId": "eng",
        "targetLanguageId": "fra",
        "baselineLanguagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
        "comments": "",
        "username": "jsmith@example.com",
        "trainingHost": "master-host"
    },
    "input": {
        "training": {
            "characters": {
                "source": 127303,
                "target": 118796
            },
            "words": {
                "source": 23685,
                "target": 22621
            },
            "translationUnits": 1306
        },
        "test": {
            "characters": {
                "source": 98330,
                "target": 91968
            },
            "words": {
                "source": 18386,
                "target": 17559
            },
            "translationUnits": 1000,
            "autoExtracted": true
        }
    },
    "bleu": {
        "baseline": 0,
        "adapted": 0
    },
    "timestamps": {
        "queued": "2019-02-05 13:52:50.98704786Z",
        "trainingStart": "",
        "completed": ""
    },
    "errorMessage": "",
    "state": "readyToDeploy"
}

Update a given adapted language pair

HTTP Request

PUT /api/v2/adapted-language-pairs/{languagePairId}

Path Parameters

Name Type Description
languagePairId string ID of adapted language pair

Request Parameters

Name Type Description Default Value
comment string The new comment on the given adapted language pair

Returns

Returns information on the adapted language pair as an AdaptedLanguagePair object

Cancel a language pair adaptation

Example Request:

curl "https://master-host:8001/api/v2/adapted-language-pairs/EngFra_Adapted-myAdaptedLP_SRV_PB_8_0_x_0/cancel" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "trainingId": "05222d9f261ef",
    "languagePairId": "EngFra_Adapted-myAdaptedLP_SRV_PB_8_0_x_0",
    "profile": {
        "sourceLanguageId": "eng",
        "targetLanguageId": "fra",
        "baselineLanguagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
        "comments": "",
        "username": "jsmith@example.com",
        "trainingHost": "master-host"
    },
    "input": {
        "training": {
            "characters": {
                "source": 127303,
                "target": 118796
            },
            "words": {
                "source": 23685,
                "target": 22621
            },
            "translationUnits": 1306
        },
        "test": {
            "characters": {
                "source": 98330,
                "target": 91968
            },
            "words": {
                "source": 18386,
                "target": 17559
            },
            "translationUnits": 1000,
            "autoExtracted": true
        }
    },
    "bleu": {
        "baseline": 25.3,
        "adapted": 25.3
    },
    "timestamps": {
        "queued": "2019-02-05 13:52:50.98704786Z",
        "trainingStart": "",
        "completed": ""
    },
    "errorMessage": "",
    "state": "canceled"
}

Cancel the adaptation of a language pair

HTTP Request

PUT /api/v2/adapted-language-pairs/{languagePairId}/cancel

Path Parameters

Name Type Description
languagePairId string ID of adapted language pair

Returns

Returns information on the adapted language pair as an AdaptedLanguagePair object

Deploy an adapted language pair

Example Request:

curl "https://master-host:8001/api/v2/adapted-language-pairs/EngFra_Adapted-myAdaptedLP_SRV_PB_8_0_x_0/deploy" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d hostname="master-host"

Example Response:

{
    "trainingId": "05222d9f261ef",
    "languagePairId": "EngFra_Adapted-myAdaptedLP_SRV_PB_8_0_x_0",
    "profile": {
        "sourceLanguageId": "eng",
        "targetLanguageId": "fra",
        "baselineLanguagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
        "comments": "",
        "username": "jsmith@example.com",
        "trainingHost": "master-host"
    },
    "input": {
        "training": {
            "characters": {
                "source": 127303,
                "target": 118796
            },
            "words": {
                "source": 23685,
                "target": 22621
            },
            "translationUnits": 1306
        },
        "test": {
            "characters": {
                "source": 98330,
                "target": 91968
            },
            "words": {
                "source": 18386,
                "target": 17559
            },
            "translationUnits": 1000,
            "autoExtracted": true
        }
    },
    "bleu": {
        "baseline": 0,
        "adapted": 0
    },
    "timestamps": {
        "queued": "2019-02-05 13:52:50.98704786Z",
        "trainingStart": "",
        "completed": ""
    },
    "errorMessage": "",
    "state": "deployed",
    "hostsDeployedTo": [
        "master-host"
    ]
}

Deploys an adapted language pair to a given host

HTTP Request

PUT /api/v2/adapted-language-pairs/{languagePairId}/deploy

Path Parameters

Name Type Description
languagePairId string ID of adapted language pair

Request Parameters

Name Type Description Default Value
hostname string Name of host

Returns

Returns information on the adapted language pair as an AdaptedLanguagePair object

Undeploy an adapted language pair

Example Request:

curl "https://master-host:8001/api/v2/adapted-language-pairs/EngFra_Adapted-myAdaptedLP_SRV_PB_8_0_x_0/undeploy" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d hostname="master-host"

Example Response:

{
    "trainingId": "05222d9f261ef",
    "languagePairId": "EngFra_Adapted-myAdaptedLP_SRV_PB_8_0_x_0",
    "profile": {
        "sourceLanguageId": "eng",
        "targetLanguageId": "fra",
        "baselineLanguagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
        "comments": "",
        "username": "jsmith@example.com",
        "trainingHost": "master-host"
    },
    "input": {
        "training": {
            "characters": {
                "source": 127303,
                "target": 118796
            },
            "words": {
                "source": 23685,
                "target": 22621
            },
            "translationUnits": 1306
        },
        "test": {
            "characters": {
                "source": 98330,
                "target": 91968
            },
            "words": {
                "source": 18386,
                "target": 17559
            },
            "translationUnits": 1000,
            "autoExtracted": true
        }
    },
    "bleu": {
        "baseline": 0,
        "adapted": 0
    },
    "timestamps": {
        "queued": "2019-02-05 13:52:50.98704786Z",
        "trainingStart": "",
        "completed": ""
    },
    "errorMessage": "",
    "state": "readyToDeploy"
}

Undeploys an adapted language pair from a given host

HTTP Request

PUT /api/v2/adapted-language-pairs/{languagePairId}/undeploy

Path Parameters

Name Type Description
languagePairId string ID of adapted language pair

Request Parameters

Name Type Description Default Value
hostname string Name of host

Returns

Returns information on the adapted language pair as an AdaptedLanguagePair object

Delete an adapted language pair

Example Request:

curl "https://master-host:8001/api/v2/adapted-language-pairs/EngFra_Adapted-myAdaptedLP_SRV_PB_8_0_x_0" \
    -X DELETE \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "trainingId": "05222d9f261ef",
    "languagePairId": "EngFra_Adapted-myAdaptedLP_SRV_PB_8_0_x_0",
    "profile": {
        "sourceLanguageId": "eng",
        "targetLanguageId": "fra",
        "baselineLanguagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
        "comments": "",
        "username": "jsmith@example.com",
        "trainingHost": "master-host"
    },
    "input": {
        "training": {
            "characters": {
                "source": 127303,
                "target": 118796
            },
            "words": {
                "source": 23685,
                "target": 22621
            },
            "translationUnits": 1306
        },
        "test": {
            "characters": {
                "source": 98330,
                "target": 91968
            },
            "words": {
                "source": 18386,
                "target": 17559
            },
            "translationUnits": 1000,
            "autoExtracted": true
        }
    },
    "bleu": {
        "baseline": 25.3,
        "adapted": 25.3
    },
    "timestamps": {
        "queued": "2019-02-05 13:52:50.98704786Z",
        "trainingStart": "",
        "completed": ""
    },
    "errorMessage": "",
    "state": "deleted"
}

Delete a language pair adaptation

HTTP Request

DELETE /api/v2/adapted-language-pairs/{languagePairId}

Path Parameters

Name Type Description
languagePairId string ID of adapted language pair

Returns

Returns information on the adapted language pair as an AdaptedLanguagePair object

System

Retrieve MTE installation information

Example Request:

curl "https://master-host:8001/api/v2/system/info" \
    -X GET

Example Response:

{
    "etsVersion": "8.0.0",
    "etsBuild": "15e651c0fe0021f45dd058d82fbe4366e9083cd4",
    "features": {
        "autoChainManagement": "enabled",
        "edgeCloud": "disabled",
        "groupShare": "enabled"
    }
}

Retrieve information about the currently installed version of MTE

HTTP Request

GET /api/v2/system/info

Returns

Returns system information about the currently installed version of MTE as a MTEInfo object with the following attributes:

Name Type Description
etsVersion string The version of the currently installed version MTE
etsBuild string The build GUID of the currently installed version of MTE
features map of strings list of optional features and whether they are enabled with the following attributes
→ edgeCloud string ‘enabled’ if EdgeCloud support is turned on, 'disabled’ otherwise.
→ groupShare string 'enabled’ if GroupShare support is turned on, 'disabled’ otherwise.
→ autoChainManagement string 'enabled’ if automatic translation chain management is turned on, 'disabled’ otherwise.

Retrieve SMTP settings

Example Request:

curl "https://master-host:8001/api/v2/system/smtp" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "host": "smtp.example.com",
    "port": 486,
    "username": "admin",
    "enabled": false
}

Retrieve the current SMTP server configuration used to send emails to SDL MTE users. For security reasons, the password will not be displayed.

HTTP Request

GET /api/v2/system/smtp

Returns

Returns SMTP settings as an SmtpSettings object with the following attributes:

Name Type Description
host string Host of SMTP server
port int Port of SMTP server
username string Username to login to SMTP server
enabled bool Whether SMTP is enabled in SDL MTE

Test SMTP settings

Example Request:

curl "https://master-host:8001/api/v2/system/smtp/test" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d host="smtp.example.com" \
    -d port="587" \
    --data-urlencode destinationEmail="jsmith@example.com" \
    --data-urlencode password="password" \
    --data-urlencode username="admin"

Example Response:

{
    "success": true
}

Test the current SMTP server configuration by sending a test email to a designated email address.

HTTP Request

PUT /api/v2/system/smtp/test

Request Parameters

Name Type Description Default Value
host string Host of SMTP server
port string Port of SMTP server
username (optional) string Username to login to SMTP server
password (optional) string Password to login to SMTP server
destinationEmail string Email address to which to send test email

Returns

Returns the result of the SMTP test as a TestResult object with the following attributes:

Name Type Description
success bool Whether or not the test was successful

Update SMTP settings

Example Request:

curl "https://master-host:8001/api/v2/system/smtp" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d enabled="true" \
    -d host="smtp.example.com" \
    -d port="587" \
    --data-urlencode password="password" \
    --data-urlencode username="admin"

Example Response:

{
    "host": "smtp.example.com",
    "port": 587,
    "username": "admin",
    "enabled": true
}

Change the SMTP server configuration used to send emails to SDL MTE users.

HTTP Request

PUT /api/v2/system/smtp

Request Parameters

Name Type Description Default Value
host string Host of SMTP server
port string Port of SMTP server
username (optional) string Username to login to SMTP server
password (optional) string Password to login to SMTP server
enabled (optional) bool Whether SMTP is enabled in SDL MTE

Returns

Returns the updated SMTP settings as an SmtpSettings object.

Retrieve LDAP settings

Example Request:

curl "https://master-host:8001/api/v2/system/ldap" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "connection": {
        "host": "ldap01",
        "port": 636,
        "tls": true,
        "insecureSkipVerify": true
    },
    "bind": {
        "user": ""
    },
    "search": {
        "base": "DC=global,DC=example,DC=com",
        "loginParser": "(.*)",
        "loginToLdap": "$1",
        "userFinder": "(userPrincipalName=$1)",
        "loginGroups": null,
        "adminGroups": null,
        "attributes": {
            "name": "cn",
            "email": "mail"
        }
    },
    "syncIntervalInSecs": 3600,
    "enabled": false
}

Retrieve the current LDAP configuration used for authenticating SDL MTE users.

HTTP Request

GET /api/v2/system/ldap

Returns

Returns LDAP settings as an LdapSettings object with the following attributes:

Name Type Description
connection object Connection to LDAP server (expanded below)
→ host string Host of LDAP server
→ port int Port of LDAP server
→ tls bool Whether LDAP server uses TLS
→ insecureSkipVerify bool Whether to skip verification of the LDAP server’s certificate chain and hostname
bind object Bind user for LDAP searches (expanded below)
→ user string LDAP user to bind when performing user search
→ password string LDAP password for bind user; required if bind.user is specified; specify __PRESERVE__ to preserve the existing password – for security reasons, the password will not be displayed
search object LDAP user search (expanded below)
→ base string Base for LDAP search (e.g., dc=global,dc=example,dc=com)
→ loginParser string Regular expression used to parse user logins; capture groups can be used in filters (e.g., (.)@(.) means that with a login of someone@example.com, $1 will resolve to someone and $2 to example.com)
→ loginToLdap string Transformation of a user login into a value acceptable for LDAP binding (e.g., $0 or $1@example.com)
→ userFinder string Transformation of a user login into an LDAP query for finding the user (e.g., (userPrincipalName=$0) or (sAMAccountName=$1))
→ loginGroups array of strings In order to log into SDL MTE, the user must be a member of one of these groups (if empty, any user is allowed to log in if the password matches)
→ adminGroups array of strings In order to be an admin user in SDL MTE, the user must be a member of one of these groups (if empty, no LDAP users will be admin users)
attributes object How to extract user name, email and a unique user ID from LDAP search (the default values should work for most LDAP installations) (expanded below)
→ → name string The user name attribute in LDAP (default: name)
→ → email string The email attribute in LDAP (default: mail)
syncIntervalInSecs int Interval used to set how often SDL MTE contacts the LDAP server to verify user is still active
enabled bool Whether LDAP is enabled in SDL MTE

Test LDAP settings

Example Request:

curl "https://master-host:8001/api/v2/system/ldap/test" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -H "Content-Type: application/json" \
    -d '{"ldapConfig":{"connection":{"host":"ldap02","port":636,"tls":true,"insecureSkipVerify":true},"bind":{"user":""},"search":{"base":"DC=global,DC=example,DC=com","loginParser":"(.*)","loginToLdap":"$1","userFinder":"(userPrincipalName=$1)","loginGroups":["CN=etsuser.group,OU=acme,DC=example,DC=com"],"adminGroups":["CN=etsadmin.group,OU=acme,DC=example,DC=com"],"attributes":{"name":"cn","email":"mail"}},"syncIntervalInSecs":3600,"enabled":true},"username":"jsmith@example.com","password":"abcd1234"}'

Example Response:

{
    "validations": [
        {
            "code": "connect",
            "description": "LDAP server connection",
            "status": "pass",
            "message": ""
        },
        {
            "code": "bind",
            "description": "binding of bind user",
            "status": "skip",
            "message": "no bind username or password provided"
        },
        {
            "code": "password",
            "description": "test user authentication",
            "status": "pass",
            "message": ""
        },
        {
            "code": "login.allowed",
            "description": "full login: login group membership",
            "status": "pass",
            "message": "user can login (name: jsmith@example.com, email: jsmith@example.com)"
        },
        {
            "code": "login.admin",
            "description": "full login: admin group membershipn",
            "status": "pass",
            "message": "user is an admin user"
        }
    ]
}

Test an LDAP configuration by running a series of validation checks.

HTTP Request

PUT /api/v2/system/ldap/test

Request Body

LDAP settings to test, as an LdapSettingsToTest object in JSON format, with the following attributes:

Name Type Description Default Value
ldapConfig object LDAP settings as an LdapSettings object
username (optional) string Username of test user
password (optional) string Password of test user

Returns

Returns the results of the LDAP validation checks as a ValidationResults object with the following attributes:

Name Type Description
validations array of objects List of validation results as an array of ValidationResult objects (expanded below)
→ code string Code of validation test
→ description string Human-friendly description of validation test
→ status string Status after validation test was attempted: pass, fail, or skip
→ message string Optional message further explaining status

Update LDAP settings

Example Request:

curl "https://master-host:8001/api/v2/system/ldap" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -H "Content-Type: application/json" \
    -d '{"ldapConfig":{"connection":{"host":"ldap02","port":636,"tls":true,"insecureSkipVerify":true},"bind":{"user":""},"search":{"base":"DC=global,DC=example,DC=com","loginParser":"(.*)","loginToLdap":"$1","userFinder":"(userPrincipalName=$1)","loginGroups":["CN=etsuser.group,OU=acme,DC=example,DC=com"],"adminGroups":["CN=etsadmin.group,OU=acme,DC=example,DC=com"],"attributes":{"name":"cn","email":"mail"}},"syncIntervalInSecs":3600,"enabled":true},"username":"jsmith@example.com","password":"abcd1234"}'

Example Response:

{
    "connection": {
        "host": "ldap02",
        "port": 636,
        "tls": true,
        "insecureSkipVerify": true
    },
    "bind": {
        "user": ""
    },
    "search": {
        "base": "DC=global,DC=example,DC=com",
        "loginParser": "(.*)",
        "loginToLdap": "$1",
        "userFinder": "(userPrincipalName=$1)",
        "loginGroups": [
            "CN=etsuser.group,OU=acme,DC=example,DC=com"
        ],
        "adminGroups": [
            "CN=etsadmin.group,OU=acme,DC=example,DC=com"
        ],
        "attributes": {
            "name": "cn",
            "email": "mail"
        }
    },
    "syncIntervalInSecs": 3600,
    "enabled": true
}

Change the LDAP configuration used for authenticating SDL MTE users.

HTTP Request

PUT /api/v2/system/ldap

Request Body

LDAP settings to save, as an LdapSettings object in JSON format.

Returns

Returns the updated LDAP settings as an LdapSettings object.

Check if SAML (Single Sign-on) authentication is available

Example Request:

curl "https://master-host:8001/api/v2/system/saml/available" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "available": true
}

Check if SAML (Single Sign-on) authentication is available, without requiring Administrator-level access

HTTP Request

GET /api/v2/system/saml/available

Returns

Returns an object with the following attributes:

Name Type Description
available bool Whether SAML available (i.e. configured and enabled)

Retrieve SAML settings

Example Request:

curl "https://master-host:8001/api/v2/system/saml" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "enabled": true,
    "identityProvider": {
        "metadataUrl": "https://login.microsoftonline.com/df02c2f8-e418-484f-8bd6-c7f2e154f300/federationmetadata/2007-06/federationmetadata.xml",
        "insecureSkipVerify": false,
        "azure": {
            "applicationId": "1234-1234-1234-9999"
        },
        "forceAuthentication": false
    },
    "loginGroups": [
        "some-group-id"
    ],
    "adminGroups": null,
    "loginRoles": null,
    "adminRoles": null
}

Retrieve the current SAML configuration used for Single Sign-on.

HTTP Request

GET /api/v2/system/saml

Returns

Returns SAML settings as an object with the following attributes:

Name Type Description
enabled bool Whether SAML is enabled in SDL MTE
identityProvider object Identity Provider configuration (expanded below)
→ metadataUrl string URL used to retrieve the Identity Provider metadata
→ insecureSkipVerify bool If true, SDL MTE will skip the verification of the certifiate supplied by the Identity Provider
azure object Azure specific configuration (expanded below)
→ → applicationId string Azure only: The Application ID on the Azure side
→ forceAuthentication bool Ask the Identity Provider to always require authentication (i.e. prompt the user for a password), even if the session is still available
→ loginGroups array of strings If not empty, the user is required to be a member of one of these groups in order to log in. The Identity Provider must be configured to send the group membership as claims

Update SAML settings

Example Request:

curl "https://master-host:8001/api/v2/system/saml" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d enabled="true" \
    -d identityProvider.azure.applicationId="1234-1234-1234-9999" \
    -d identityProvider.forceAuthentication="false" \
    -d identityProvider.metadataUrl="https://login.microsoftonline.com/df02c2f8-e418-484f-8bd6-c7f2e154f300/federationmetadata/2007-06/federationmetadata.xml" \
    -d loginGroup="some-group-id"

Example Response:

{
    "enabled": true,
    "identityProvider": {
        "metadataUrl": "https://login.microsoftonline.com/df02c2f8-e418-484f-8bd6-c7f2e154f300/federationmetadata/2007-06/federationmetadata.xml",
        "insecureSkipVerify": false,
        "azure": {
            "applicationId": "1234-1234-1234-9999"
        },
        "forceAuthentication": false
    },
    "loginGroups": [
        "some-group-id"
    ],
    "adminGroups": null,
    "loginRoles": null,
    "adminRoles": null
}

Change the SAML configuration used for Single Sign-on

HTTP Request

PUT /api/v2/system/saml

Request Parameters

Name Type Description Default Value
enabled (optional) bool Whether SAML is enabled
identityProvider.azure.applicationId (optional) string Azure only: Application ID on the Azure side
identityProvider.metadataUrl (optional) string URL used to retrieve Identity Provider metadata
identityProvider.insecureSkipVerify (optional) bool If true, SDL MTE will skip the verification of the certifiate supplied by the Identity Provider
identityProvider.forceAuthentication (optional) bool If true, the Identity Provider will always ask for the user password, even if the user still has a valid session on the Identity Provider side
loginGroup (optional) string If not empty, the user is required to be a member of one of these groups in order to log in. The Identity Provider must be configured to send the group membership as claims. This parameter can be repeated if there is more than one group.

Returns

Returns the updated SAML settings as an object.

Retrieve proxy settings

Example Request:

curl "https://master-host:8001/api/v2/system/proxy" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "host": "proxy.example.com",
    "port": 8080,
    "username": "admin",
    "enabled": false
}

Retrieve the proxy configuration through which Edge Cloud connections are made. For security reasons, the password will not be displayed.

HTTP Request

GET /api/v2/system/proxy

Returns

Returns proxy settings as a ProxySettings object with the following attributes:

Name Type Description
host string Host of proxy server
port int Port of proxy server
username string Username to login to proxy server
enabled bool Whether proxy is enabled in SDL MTE

Update proxy settings

Example Request:

curl "https://master-host:8001/api/v2/system/proxy" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d enabled="true" \
    -d host="proxy2.example.com" \
    -d port="567" \
    --data-urlencode password="password" \
    --data-urlencode username="admin"

Example Response:

{
    "host": "proxy2.example.com",
    "port": 567,
    "username": "admin",
    "enabled": true
}

Change the proxy configuration through which Edge Cloud connections are made.

HTTP Request

PUT /api/v2/system/proxy

Request Parameters

Name Type Description Default Value
host string Host of proxy server
port string Port of proxy server
username (optional) string Username to login to proxy server
password (optional) string Password to login to proxy server
enabled (optional) bool Whether proxy is enabled in SDL MTE

Returns

Returns the updated proxy settings as a ProxySettings object.

Retrieve TLS settings

Example Request:

curl "https://master-host:8001/api/v2/system/tls" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "enabled": false,
    "certificatePath": "/opt/sdl/ets/auth/tls/default/cert.pem",
    "privateKeyPath": "/opt/sdl/ets/auth/tls/default/key.pem"
}

Retrieve the TLS configuration through which MTE services are served.

HTTP Request

GET /api/v2/system/tls

Returns

Returns TLS settings as a TlsSettings object with the following attributes:

Name Type Description
enabled bool Whether TLS is enabled in SDL MTE
certificatePath string Path to TLS certificate
privateKeyPath string Path to TLS private key

Update TLS settings

Example Request:

curl "https://master-host:8001/api/v2/system/tls" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d enabled="true" \
    --data-urlencode privateKeyPassword="foobar" \
    --data-urlencode privateKeyPath="/opt/sdl/ets/auth/tls/default/key-new.pem"

Example Response:

{
    "enabled": true,
    "certificatePath": "/opt/sdl/ets/auth/tls/default/cert.pem",
    "privateKeyPath": "/opt/sdl/ets/auth/tls/default/key-new.pem"
}

Change the TLS configuration through which MTE services are served. Note: You must manually restart SDL MTE Manager on the Master host for these changes to take effect.

HTTP Request

PUT /api/v2/system/tls

Request Parameters

Name Type Description Default Value
enabled (optional) bool Whether TLS is enabled in SDL MTE
certificatePath (optional) string Path to TLS certificate
privateKeyPath (optional) string Path to TLS private key
privateKeyPassword (optional) string Password to access private key

Returns

Returns the updated TLS settings as a TlsSettings object.

Retrieve Edge Cloud settings

Example Request:

curl "https://master-host:8001/api/v2/system/edge-cloud" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "host": "api.sdlbeglobal.com",
    "port": 443,
    "clientId": "7A30s2",
    "enabled": true
}

Retrieve the current Edge Cloud configuration used to connect to a MT Cloud server.

HTTP Request

GET /api/v2/system/edge-cloud

Returns

Returns Edge Cloud settings as an EdgeCloudConfig object with the following attributes:

Name Type Description
host string Host of MT Cloud server
port int Port of MT Cloud server
clientId string Client ID to login to MT Cloud server
enabled bool Whether Edge Cloud is enabled in SDL MTE

Test Edge Cloud settings

Example Request:

curl "https://master-host:8001/api/v2/system/edge-cloud/test" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d host="api.sdlbeglobal.com" \
    -d port="443" \
    --data-urlencode clientId="7A30s2" \
    --data-urlencode clientSecret="AbC_123"

Example Response:

{
    "success": true
}

Test the Edge Cloud configuration by running a series of validation checks.

HTTP Request

PUT /api/v2/system/edge-cloud/test

Request Parameters

Name Type Description Default Value
host (optional) string Host of MT Cloud server
port (optional) string Port of MT Cloud server
clientId (optional) string Client ID to login to MT Cloud server
clientSecret (optional) string Client secret to login to MT Cloud server

Returns

Returns the updated Edge Cloud settings as an EdgeCloudConfig object.

Update Edge Cloud settings

Example Request:

curl "https://master-host:8001/api/v2/system/edge-cloud" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d enabled="true" \
    -d host="api.sdlbeglobal.com" \
    -d port="443" \
    --data-urlencode clientId="7A30s2" \
    --data-urlencode clientSecret="AbC_123"

Example Response:

{
    "host": "api.sdlbeglobal.com",
    "port": 443,
    "clientId": "7A30s2",
    "enabled": true
}

Change the Edge Cloud configuration used to connect to a MT Cloud server.

HTTP Request

PUT /api/v2/system/edge-cloud

Request Parameters

Name Type Description Default Value
host (optional) string Host of MT Cloud server
port (optional) string Port of MT Cloud server
clientId (optional) string Client ID to login to MT Cloud server
clientSecret (optional) string Client secret to login to MT Cloud server
enabled (optional) bool Whether Edge Cloud is enabled in SDL MTE false

Returns

Returns the updated Edge Cloud settings as an EdgeCloudConfig object.

Retrieve GroupShare settings

Example Request:

curl "https://master-host:8001/api/v2/system/group-share" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "host": "http://groupShareHost",
    "port": 80,
    "username": "User",
    "enabled": true
}

Retrieve the current GroupShare configuration used to connect to a GroupShare server.

HTTP Request

GET /api/v2/system/group-share

Returns

Returns GroupShare settings as an GroupShareConfig object with the following attributes:

Name Type Description
host string Host of GroupShare server
port int Port of GroupShare server
username string Username to login to GroupShare server
enabled bool Whether GroupShare is enabled in SDL MTE

Test GroupShare settings

Example Request:

curl "https://master-host:8001/api/v2/system/group-share/test" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d host="http://groupShareHost" \
    -d password="password" \
    -d port="80" \
    -d username="User"

Example Response:

{
    "success": true
}

Test the GroupShare configuration by running a series of validation checks.

HTTP Request

PUT /api/v2/system/group-share/test

Request Parameters

Name Type Description Default Value
host (optional) string Host of GroupShare server
port (optional) int Port of GroupShare server
username (optional) string Username to login to GroupShare server
password (optional) string Password to login to GroupShare server

Returns

Returns the updated GroupShare settings as an GroupShareConfig object.

Update GroupShare settings

Example Request:

curl "https://master-host:8001/api/v2/system/group-share" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d enabled="true" \
    -d host="http://groupShareHost" \
    -d password="password" \
    -d port="80" \
    -d username="User"

Example Response:

{
    "host": "http://groupShareHost",
    "port": 80,
    "username": "User",
    "enabled": true
}

Change the GroupShare configuration used to connect to a GroupShare server.

HTTP Request

PUT /api/v2/system/group-share

Request Parameters

Name Type Description Default Value
host (optional) string Host of GroupShare server
port (optional) int Port of GroupShare server
username (optional) string Username to login to GroupShare server
password (optional) string Password to login to GroupShare server
enabled (optional) bool Whether GroupShare is enabled in SDL MTE false

Returns

Returns the updated GroupShare settings as an GroupShareConfig object.

Retrieve reports settings

Example Request:

curl "https://master-host:8001/api/v2/system/reports" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "translations": {
        "enabled": true,
        "maxAgeInSecs": 8640000
    }
}

Retrieve the reports configuration.

HTTP Request

GET /api/v2/system/reports

Returns

Returns the reports configuration object with the database path excluded.

Update translation reports settings

Example Request:

curl "https://master-host:8001/api/v2/system/reports/translations" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d enabled="true" \
    -d maxAgeInSecs="8640000"

Example Response:

{
    "enabled": true,
    "maxAgeInSecs": 8640000
}

Change the translation reports configuration.

HTTP Request

PUT /api/v2/system/reports/translations

Request Parameters

Name Type Description Default Value
enabled (optional) bool Whether translations will have their translation metrics recorded false
maxAgeInSecs (optional) int Maximum age of translation metrics kept during daily purges 8640000

Returns

Returns the updated translation report configuration object with the database path excluded.

Retrieve Public URL settings

Example Request:

curl "https://master-host:8001/api/v2/system/public-url" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "publicUrl": "https://public-host:8001",
    "privateApiUrl": "https://master-host:8001",
    "privateWebUrl": "https://master-host:8000"
}

Retrieve the Public URL settings.

HTTP Request

GET /api/v2/system/public-url

Returns

Returns the public URL settings as a URLSettings object with the following attributes:

Name Type Description
publicUrl string The API and web URL that is used to access this MTE instance from external networks. This can be set to a reverse proxy’s address.
privateApiUrl string The API URL that is used to access this MTE instance from internal networks.
privateWebUrl string The web URL that is used to access this MTE instance from internal networks.

Update Public URL settings

Example Request:

curl "https://master-host:8001/api/v2/system/public-url" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d publicUrl="https://public-host:8001"

Example Response:

{
    "publicUrl": "https://public-host:8001",
    "privateApiUrl": "https://master-host:8001",
    "privateWebUrl": "https://master-host:8000"
}

Change the Public URL settings.

HTTP Request

PUT /api/v2/system/public-url

Request Parameters

Name Type Description Default Value
publicUrl string The public URL to prepend URLs with.

Returns

Returns the updated public URL as a URLSettings object.

Retrieve asynchronous translation purge configuration

Example Request:

curl "https://master-host:8001/api/v2/system/translations/purge" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "maxAgeInSecs": 0,
    "enabled": false
}

Retrieve the asynchronous translation purge configuration.

HTTP Request

GET /api/v2/system/translations/purge

Returns

Returns the translation purge configuration as a TranslationPurgeConfig object with the following attributes:

Name Type Description
maxAgeInSecs int Maximum age a translation is kept before being purged. The age begins when the translation is completed. Specified age must be at least one second.
enabled bool Whether translations will have their records regularly purged after they exceed their maximum age.

Update asynchronous translation purge configuration

Example Request:

curl "https://master-host:8001/api/v2/system/translations/purge" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d enabled="false" \
    -d maxAgeInSecs="8640000"

Example Response:

{
    "maxAgeInSecs": 8640000,
    "enabled": false
}

Change the asynchronous translation purge configuration.

HTTP Request

PUT /api/v2/system/translations/purge

Request Parameters

Name Type Description Default Value
maxAgeInSecs (optional) int Maximum age a translation is kept before being purged. The age begins when the translation is completed. 8640000
enabled (optional) bool Whether translations will have their records regularly purged after they exceed their maximum age. false

Returns

Returns the updated translation configuration as a TranslationPurgeConfig object.

Retrieve translation chain settings

Example Request:

curl "https://master-host:8001/api/v2/system/translation-chains" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "autoManage": true,
    "enabled": true
}

Retrieve the current status of system-wide translation chain features.

HTTP Request

GET /api/v2/system/translation-chains

Returns

Returns the current settings as a ChainManagementSettings object with the following attributes

Name Type Description
autoManage bool Whether the system automatically creates and disposes of translation chains as the necessary resources become available/unavailable.
enabled bool Whether translation chains are enabled on the system.

Update translation chain settings

Example Request:

curl "https://master-host:8001/api/v2/system/translation-chains" \
    -X PUT \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d autoManage="true" \
    -d enabled="true"

Example Response:

{
    "autoManage": true,
    "enabled": true
}

Update system-wide settings for translation chains

HTTP Request

PUT /api/v2/system/translation-chains

Request Parameters

Name Type Description Default Value
autoManage (optional) bool Whether the system automatically creates and disposes of translation chains as the necessary resources become available/unavailable.
enabled (optional) bool Whether translation chains are enabled on the system.

Returns

Returns the current settings as a ChainManagementSettings object.

Language Detections

Create a language detection

Example Request:

curl "https://master-host:8001/api/v2/language-detections" \
    -X POST \
    -u u_jsmith@example.com_u0VmztKJrwqf: \
    -d inputFormat="text/plain" \
    --data-urlencode input="VGhpcyBpcyBlbmdsaXNoIHRleHQgZm9sbG93ZWQgYnkgc29tZSBzcGFuaXNoIHRleHQuCkFzIGh1bmRyZWRzIG9mIHRob3VzYW5kcyBvZiBwZW9wbGUgcG90ZW50aWFsbHkgaW4gdGhlIHBhdGggb2YgSHVycmljYW5lIE1hdHRoZXcgZmxlZCBpbmxhbmQgV2VkbmVzZGF5LCBub3QgZXZlcnlvbmUgd2FzIGV2YWN1YXRpbmcuCgpJbiBDaGFybGVzdG9uLCBTb3V0aCBDYXJvbGluYSwgd2hpY2ggbGlrZWx5IHdpbGwgc2VlIHRoZSBwb3dlcmZ1bCBzdG9ybSdzIGltcGFjdCB0aGlzIHdlZWtlbmQsIHNvbWUgcGVvcGxlIHdlcmUgYm9hcmRpbmcgdXAgYnVzaW5lc3Nlcy4KQ2hlcnlsIFF1aW5uIHRvbGQgQ05OJ3MgU3RlcGhhbmllIEVsYW0gc2hlIGlzIHBsYW5uaW5nIHRvIGh1bmtlciBkb3duLgoKQ29uIHVuIHRvdGFsIGRlIG3DoXMgZGUgc2lldGUgbWludXRvcyBkZSBkdXJhY2nDs24sIGZ1ZSBlbiBzdSB0aWVtcG8gbGEgY2FuY2nDs24gbcOhcyBsYXJnYSBkZSBsYSBoaXN0b3JpYSBlbiBlc3RhciBlbiBlbCB0b3AgMTAgZGUgbGFzIGxpc3RhcyBicml0w6FuaWNhcyBkZSBzZW5jaWxsb3MuIFRhbWJpw6luIHBhc8OzIG51ZXZlIHNlbWFuYXMgY29tbyBuLgoK"

Example Response:

{
    "encoding": "UTF-8",
    "languages": [
        {
            "code": "eng",
            "languageTag": "en",
            "name": "English",
            "score": 0.6
        },
        {
            "code": "spa",
            "languageTag": "es",
            "name": "Spanish",
            "score": 0.39
        }
    ],
    "scripts": [
        {
            "code": "Latn",
            "name": "Latin",
            "percent": 80.1
        },
        {
            "code": "Zyyy",
            "name": "Common",
            "percent": 19.9
        }
    ]
}

Create a synchronous job that attempts to detect the language(s) and script(s) of an input string.

HTTP Request

POST /api/v2/language-detections

Request Parameters

Name Type Description Default Value
input string Base64-encoded and URL-encoded content to submit for language detection
inputFormat string Format of input document (see table of possible input formats)
encoding (optional) string Encoding of source content (see list of supported character encodings) UTF-8

Returns

Returns the detected language(s) and script(s) as a LanguageDetection object with the following attributes:

Name Type Description
encoding string Source content encoding
languages array of objects List of up to 3 detected languages as an array of DetectedLanguage objects (expanded below)
→ code string MTE code of detected language (see language codes table)
→ languageTag string IETF language tag of detected language (see language codes table)
→ name string Full name of detected language
→ score float A value between 0 and 1; the closer the value is to 1, the greater the association between the detected language and source content
scripts array of objects List of all detected scripts as an array of DetectedScript objects (expanded below)
→ code string ISO-15924 code of detected script (see script codes table)
→ name string Name of detected script
→ percent float Percentage of source content using specific script

Reports

Retrieve translation reports

Example Request:

curl "https://master-host:8001/api/v2/reports/translations?fromTimestamp=2019-01-01_11:26:45.158516672" \
    -X GET \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "translations": [
        {
            "type": "sync",
            "translationRecord": {
                "translationId": "051a5d687795d",
                "profile": {
                    "username": "jsmith@example.com",
                    "title": "example translation",
                    "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
                    "encoding": "utf-8",
                    "inputFormat": "text/html",
                    "dictionaryIds": [
                        "dict1_c95c72dd2f138da2a46c872a40616eb1",
                        "dict2_397e8373985929881616bcaa4805844a"
                    ],
                    "outputFormat": "",
                    "highlightDictionary": true,
                    "unknownMode": "hide",
                    "highlightUnknown": false,
                    "generateMetadata": false,
                    "translationMethod": "MTE"
                },
                "result": {
                    "completedSegments": 64,
                    "inputSize": 3613,
                    "sourceCharacterCount": 3498,
                    "sourceWordCount": 689,
                    "targetCharacterCount": 3840,
                    "targetWordCount": 766,
                    "totalSegments": 64,
                    "outputSize": 4006,
                    "progress": 100,
                    "wordsPerMinute": 52065
                },
                "timestamps": {
                    "queued": "2018-06-21 19:03:31.799810031Z",
                    "started": "2018-06-21 19:03:32.113048776Z",
                    "done": "2018-06-21 19:03:34.872942468Z"
                },
                "errorMessage": "",
                "state": "done",
                "substate": "succeeded"
            },
            "username": "",
            "languagePairId": "",
            "substate": "",
            "timeStarted": ""
        }
    ],
    "options": {
        "username": "",
        "languagePairId": "",
        "translationType": "",
        "substate": "",
        "fromTimestamp": "2019-01-01 11:26:45.158516672Z",
        "toTimestamp": ""
    },
    "page": 1,
    "perPage": 25,
    "totalPages": 1,
    "totalItems": 1
}

Retrieve translation reports filtered by given parameters.

HTTP Request

GET /api/v2/reports/translations

Request Parameters

Name Type Description Default Value
username (optional) string Username to filter results by
languagePairId (optional) string Language Pair to filter results by
translationType (optional) string Translation types to filter results by
substate (optional) string Substate to filter results by
fromTimestamp (optional) string Beginning timestamp (in UTC) to filter results by
toTimestamp (optional) string End timestamp (in UTC) to filter results by
page (optional) int Page number to return 1
perPage (optional) int Number of translations to return per page 25

Returns

Returns the translation records and statistics occurred, filtered by the given timestamps and other provided parameters.

Name Type Description
translations array of objects List of Translation objects
options object Fields the returned translations are filtered by (expanded below)
→ username string Username the results are filtered by
→ languagePairId string Language pair the results are filtered by
→ translationType string Type of translation the results are filtered by
→ substate string Subtype of translation the results are filtered by
→ fromTimestamp string Beginning timestamp (in UTC) the results are filtered by
→ toTimestamp string Ending timestamp (in UTC) the results are filtered by
page int Page number returned
perPage int Number of translations returned per page
totalPages int Total number of pages available
totalItems int Total number of translations

Translation Types

There are two translation types. They are as follows:

Type Description
async Translation was submitted asynchronously
sync Translation was submitted synchronously

Delete translation metrics

Example Request:

curl "https://master-host:8001/api/v2/reports/translations" \
    -X DELETE \
    -u u_jsmith@example.com_u0VmztKJrwqf:

Example Response:

{
    "maxAgeInSecs": 8640000
}

Delete all translation metrics beyond a given maximum age in seconds.

HTTP Request

DELETE /api/v2/reports/translations

Request Parameters

Name Type Description Default Value
maxAgeInSecs int Translations at this age and older will be deleted.

Returns

Returns the maximum age of the translation records not deleted.

Name Type Description
maxAgeInSecs int maximum age in seconds of translation metrics not deleted