Introduction

Language Weaver Edge (formerly known as SDL Machine Translation Edge) 8 features a REST API that exposes the functionality of Edge 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 controller host at its own port. To find out the API server host and port, log in to the Language Weaver Edge 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 controller-host and port 8001, with HTTPS enabled, so the base URL for the REST API will be:

https://controller-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 Language Weaver Edge, 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. Edge 8.0 ships with v2 of the API, while Edge 7.x ships with v1 of the API. The API version is hardcoded into the URL:

https://controller-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://controller-host:8001/api/v2/dictionaries/{dictionaryId}

Authentication

Every request sent to the Language Weaver Edge 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

API Key Authentication Example

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

One method of authenticating API requests is by supplying a valid Username and API key. Each user has a unique API key. To obtain your API key, log in to the Language Weaver Edge Web GUI and navigate to [User Full Name] > My Account, where the Username and API key are displayed. You can easily change your API key on that page as well.

The API uses HTTP Basic Authentication for API key authentication.

Legacy API Key Authentication Example (deprecated)

The old API Key authentication, where only the API Key is provided is now deprecated.

# Legacy API key authentication (deprecated). Replace <api-key> with a valid API key
curl -u <api-key>: "https://controller-host:8001/api/v2/translations"

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

Token authentication

# login with username and password
curl -X POST https://controller-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://controller-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

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

curl -u <api-key>: "https://controller-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 Language Weaver Edge 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:

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

{
    "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, Language Weaver Edge 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	Edge 3-Letter Code	IETF Language Tag
Albanian	`alb`	`sq`
Amharic	`amh`	`am`
Arabic	`ara`	`ar`
Arabic (Arabizi)	`are`	`ar-x-arabizi`
Armenian	`arm`	`hy`
Azerbaijani	`aze`	`az`
Bengali	`ben`	`bn`
Bosnian	`bos`	`bs`
Bulgarian	`bul`	`bg`
Burmese	`bur`	`my`
Catalan	`cat`	`ca`
Central Khmer	`khm`	`km`
Chinese (Simplified)	`chi`	`zh`
Chinese (Traditional)	`cht`	`zh-Hant`
Croatian	`hrv`	`hr`
Czech	`cze`	`cs`
Danish	`dan`	`da`
Dari	`fad`	`prs-AF`
Dutch	`dut`	`nl`
English	`eng`	`en`
English (United Kingdom)	`ene`	`en-GB`
Estonian	`est`	`et`
Finnish	`fin`	`fi`
Flemish	`nlf`	`nl-BE`
French	`fra`	`fr`
French (Canada)	`frc`	`fr-CA`
Georgian	`geo`	`ka`
German	`ger`	`de`
Greek	`gre`	`el`
Hausa	`hau`	`ha`
Hebrew	`heb`	`he`
Hindi	`hin`	`hi`
Hungarian	`hun`	`hu`
Icelandic	`ice`	`is`
Indonesian	`ind`	`id`
Irish	`gle`	`ga`
Italian	`ita`	`it`
Japanese	`jpn`	`ja`
Javanese	`jav`	`jv`
Korean	`kor`	`ko`
Kurdish	`kur`	`ku`
Latvian	`lav`	`lv`
Lithuanian	`lit`	`lt`
Macedonian	`mac`	`mk`
Malay	`may`	`ms`
Maltese	`mlt`	`mt`
Norwegian	`nor`	`no`
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`
Sinhala	`sin`	`si`
Slovak	`slo`	`sk`
Slovenian	`slv`	`sl`
Somali	`som`	`so`
Spanish	`spa`	`es`
Spanish (Latin America)	`esl`	`es-419`
Swahili	`swa`	`sw`
Swedish	`swe`	`sv`
Tagalog	`tgl`	`tl`
Tamil	`tam`	`ta`
Telugu	`tel`	`te`
Thai	`tha`	`th`
Turkish	`tur`	`tr`
Ukrainian	`ukr`	`uk`
Urdu	`urd`	`ur`
Uzbek	`uzb`	`uz`
Vietnamese	`vie`	`vi`

To refer to writing scripts, Language Weaver Edge 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

Language Weaver Edge 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-1255
windows-1256

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

Access Tokens

Obtain token using username / password

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

"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 a configurable duration (default 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.

Obtain token using SAML (Step 1)

curl "https://controller-host:8001/api/v2/auth/auth/saml/gen-secret" \
    -X GET

"eyJhbGciOiJ...75TOc0CXKW"

This is the first step when performing SAML authentication via the REST API. It returns a temporary secret token (called SECRET below), which is used to complete SAML authentication via the REST API.

About SAML Authentication

When SAML authentication is enabled in MT Edge, this flow will allow a REST API Client to log in on behalf of an end-user. Please note that the login credentials never flow through MT Edge server. They are handled by the trusted SAML Identity Provider Web site (e.g Azure).

Authentication Flow

The authentication flow consists of three steps:

Step 1: The client calls the REST API endpoint /api/v2/auth/saml/gen-secret to generate a temporary secret, called SECRET below.
Step 2: The client opens the following URL in a Web browser: /api/v2/auth/saml/init?secret=SECRET.
Step 3: The client calls /api/v2/auth/saml/wait?secret=SECRET. When the end-user completes the authentication started at step B, this call will return the authentication token.
This authentication token can be used the same way as the token returned by /api/v2/auth.

Please note the difference between calls:

Step 1 and Step 3 are regular REST API calls. They return values.
Step 2 consists of opening a URL in a Web browser allowing the user to log in. It indirectly causes Step 3 to return upon success, but it does not return a value itself.

Note regarding order of the calls:

Step 2 and Step 3 can be performed in any order. If Step 3 is performed first, the API client would have to be multi-threaded, as the call blocks until Step 2 completes the login in the browser. It is generally easier to perform Step 2 first, as Step 2 returns immediately, allowing the API client to call Step 3 right away.

HTTP Request

GET /api/v2/auth/auth/saml/gen-secret

Returns

Returns a temporary secret token used in Step 2 and Step 3 of authentication.

Obtain token using SAML (Step 2)

curl "https://controller-host:8001/api/v2/auth/auth/saml/init?secret=eyJhbGciOiJ...75TOc0CXKW" \
    -X GET

This is the second step when performing SAML authentication via the REST API.

The Client uses the secret token obtained at Step 1 above to open a web page in the Web browser. This web page will allow the end-user to complete the SAML login on the SAML Identity Provider web site.

For a complete description of the workflow, please see Step 1 (/api/v2/auth/saml/gen-secret) above.

HTTP Request

GET /api/v2/auth/auth/saml/init

Request Parameters

Name	Type	Description	Default Value
`secret`	string	Secret token previously obtained in Step 1 by calling /api/v2/auth/saml/gen-secret

Returns

Returns a temporary secret token used in Step 2 and Step 3 of authentication.

Obtain token using SAML (Step 3)

curl "https://controller-host:8001/api/v2/auth/auth/saml/wait?secret=eyJhbGciOiJ...75TOc0CXKW" \
    -X GET

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gU21pdGgiLCJhZG1pbiI6dHJ1ZX0.LfFQV0anBnn40BJ-CL3XSDUAcbqQw8Xm7sDKNVHrR9U"

Retrieves an access token used for authentication in API calls. The end user first logs in via SAML using a Web browser. A successful SAML login will produce an authentication token used for API calls. This token is valid for a configurable duration (default 12 hours). Once the token expires, this endpoint will need to be called again to obtain a new access token.

For a complete description of the workflow, please see Step 1 (/api/v2/auth/saml/gen-secret) above.

HTTP Request

GET /api/v2/auth/auth/saml/wait

Request Parameters

Name	Type	Description	Default Value
`secret`	string	Secret token previously obtained in Step 1 by calling /api/v2/auth/saml/gen-secret

Returns

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

Translations

List translations

curl "https://controller-host:8001/api/v2/translations?reverse=1&startTimeQueued=2019-01-01+11%3A26%3A45.158516672Z" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "translations": [
        {
            "translationId": "bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd",
            "profile": {
                "username": "jsmith@example.com",
                "title": "example translation",
                "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
                "encoding": "utf-8",
                "inputFormat": "text/html",
                "pdfConverter": "",
                "pdfPageCount": 0,
                "imageConverter": "",
                "dictionaryIds": [
                    "dict1_c95c72dd2f138da2a46c872a40616eb1",
                    "dict2_397e8373985929881616bcaa4805844a"
                ],
                "outputFormat": "",
                "highlightDictionary": true,
                "highlightBrand": true,
                "highlightFeedback": true,
                "unknownMode": "transliteration",
                "highlightUnknown": false,
                "markSegments": true,
                "sourceRequested": false,
                "generateMetadata": false,
                "translationMethod": "MTE",
                "labels": [
                    {
                        "id": 4,
                        "name": "Legal"
                    },
                    {
                        "id": 28,
                        "name": "Medical"
                    }
                ],
                "includeEditorInput": false,
                "includeTextContent": false,
                "includeSegmentPairs": false
            },
            "result": {
                "completedSegments": 64,
                "inputSize": 3613,
                "sourceCharacterCount": 3498,
                "sourceWordCount": 689,
                "targetCharacterCount": 3840,
                "targetWordCount": 766,
                "totalSegments": 64,
                "outputSize": 4006,
                "progress": 100,
                "wordsPerMinute": 52065,
                "qualityEstimation": {
                    "good": 73.333336,
                    "adequate": 10.123456,
                    "poor": 16.543211
                }
            },
            "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.
`statuses` (optional)	string	Show only translations with the given comma-separated states. (see table of possible states)
`labels` (optional)	string	Show only translations with the given comma-separated labels.
`startTimeQueued` (optional)	string	Show only translations that were queued on or after the given timestamp. (see timestamps for formatting guidelines)
`endTimeQueued` (optional)	string	Show only translations that were queued on or before the given timestamp. (see timestamps for formatting)
`translationMethod` (optional)	string	Show only translations with the given translationMethod. (see list of supported translation methods)
`title` (optional)	string	Show only translations with the given title as a substring.
`sourceLanguageId` (optional)	string	Show only translations with the given sourceLanguageId (3-letter code).
`targetLanguageId` (optional)	string	Show only translations with the given targetLanguageId (3-letter code).
`languagePairId` (optional)	string	Show only translations with the given languagePairId. If this is set, it will override any values set for sourceLanguageId and targetLanguageId.
`reverse` (optional)	boolean	Return translations in reverse order (oldest first)	`0`
`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)

curl "https://controller-host:8001/api/v2/translations" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d base64="1" \
    -d highlightBrand="true" \
    -d highlightDictionary="true" \
    -d highlightFeedback="true" \
    -d labels="Health" \
    -d languagePairId="EngFra_Generic_SRV_TNMV_8_4_x_1" \
    -d qualityEstimationOption="Enabled" \
    --data-urlencode dictionaryIds="dict1,dict2" \
    --data-urlencode input="VGhpcyBpcyBhIHNhbXBsZSBpbnB1dCB0ZXh0Lgo=" \
    --data-urlencode linguisticOptions="Formality:Formal" \
    --data-urlencode outputFormat="application/x-xliff" \
    --data-urlencode title="example translation"

{
    "translationId": "bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd"
}

Create an asynchronous 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
`base64` (optional)	string	When this parameter is set to 0 (the default is 1), the input does not need to be Base64-encoded	`1`
`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 (unless base64 parameter above is set to 0)
`inputFormat` (optional)	string	Format of input document (see table of possible input formats)	`text/plain`
`pdfConverter` (optional)	string	Converter to use for PDF conversions. Choices: `Standard` to use standard conversion and `Abbyy` to use ABBYY FineReader for enhanced conversion. If empty, Edge (licensed with ABBYY) will automatically use ABBYY when the source file is a scanned PDF, or if the source language is right-to-left (RTL) script or one of the following: Chinese (Simplified and Traditional), Japanese, Korean, Vietnamese, Thai, Hindi or Burmese; Edge will use standard conversion for all other source languages when the source file is not a scanned PDF.
`imageConverter` (optional)	string	Converter to use for image to text conversions. Choices: `Standard` to use standard conversion and `Abbyy` to use ABBYY FineReader when licensed.	`Standard`
`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
`highlightDictionary` (optional)	boolean	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`
`highlightBrand` (optional)	boolean	Whether to highlight brand translations in the output. This only applies to non-search pattern brand matches, and both `inputFormat` and `outputFormat` are `text/html`.	`false`
`highlightFeedback` (optional)	boolean	Whether to highlight feedback translations in the output. This only applies to feedback matches, and both `inputFormat` and `outputFormat` are `text/html`.	`false`
`markSegments` (optional)	boolean	Whether to mark source and target segments in the output. This only applies if `inputFormat` and `outputFormat` are `text/html`.	`false`
`generateMetadata` (optional)	boolean	Generate metadata in addition to the translation (requires more computation)	`false`
`labels` (optional)	string	Labels for translation to be associated with – comma-separated identifiers
`includeTextContent` (optional)	boolean	Generate a separate translation output in `text/plain` format. This only applies if outputFormat is not already `text/plain`	`false`
`includeSegmentPairs` (optional)	boolean	Generate a separate output in `application/json` format that list all segments as source segment and target segment pairs	`false`
`generateAlternatives` (optional)	boolean	Generate a number of alternative translations. This only applies if outputFormat is either `text/html` or `application/x-xliff`	`false`
`linguisticOptions` (optional)	array of key:value strings	Linguistic options to use for translation; (see list language-pairs) to display available linguistic options.
`qualityEstimationOption` (optional)	string	Whether quality estimation is computed for supported language pairs. Available options: `Enabled` or `Disabled`	`Enabled`

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 v1.x (XLIFF)
`application/xliff`	`.xliff`	XML Localization Interchange File Format v2.x (XLIFF)
`text/sgml`	`.sgml`, `.sgm`	SGML

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/bmp`	`.bmp`	Windows OS/2 Bitmap Graphics (BMP)
`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)

Email Formats

MIME Type	File Extensions	Description
`application/vnd.ms-outlook`	`.msg`	Microsoft Outlook Email Message
`message/rfc822`	`.eml`	Message (RFC 822)

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
`application/x-wps-writer`	`.wps`	WPS Writer
`application/x-wps-spreadsheet`	`.et`	WPS Spreadsheet
`application/x-wps-presentation`	`.dps`	WPS Presentation
`application/x-mimearchive`	`.mhtml`, `.mht`	MHTML

Audio Formats

MIME Type	File Extensions	Description
`audio/wav`	`.wav`	Waveform Audio File Format (WAV)
`audio/mpeg`	`.mp3`	MPEG Audio Layer 3 (MP3)
`audio/mp4`	`.mp4`	MPEG-4 Part 14 (MP4)
`audio/m4a`	`.m4a`	MPEG-4 Audio

Video Formats

MIME Type	File Extensions	Description
`video/mp4`	`.mp4`	MPEG-4 Part 14 (MP4)

Timed Text Formats

MIME Type	File Extensions	Description
`text/vtt`	`.vtt`	Web Video Text Track file
`application/x-subrip`	`.srt`	SubRip Subtitle file

Output Formats

MIME Type	Description
`default` or empty	Default output: For image, audio and email input formats, output `text/plain` For `application/pdf` input, output `text/plain` if it is an image-only PDF, otherwise output `application/vnd.openxmlformats-officedocument.wordprocessingml.document` For all other input formats, output the same as the input format
`text/plain`	Plain text
`application/x-xliff`	XML Localization Interchange File Format (v1.2)
`application/xliff`	XML Localization Interchange File Format (v2.1)
`text/x-tmx`	Translation Memory eXchange

Translation Methods

Method	Description
`MTE`	Edge (default)

Timestamps

Unless otherwise stated, timestamps adhere to yyyy-MM-dd HH:mm:ss.SSS (example: 2006-01-02 15:04:05.999999999Z).

Create a quick translation (synchronously)

curl "https://controller-host:8001/api/v2/translations/quick" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d base64="1" \
    -d highlightBrand="true" \
    -d highlightDictionary="true" \
    -d highlightFeedback="true" \
    -d jsonOutput="1" \
    -d languagePairId="EngFra_Generic_SRV_TNMV_8_4_x_1" \
    --data-urlencode input="VGhpcyBpcyBhIHNhbXBsZSBpbnB1dCB0ZXh0Lgo=" \
    --data-urlencode linguisticOptions="Formality:Formal"

{
    "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. Hint: In order to translate a file without the need to encode it to Base64, use the following request parameters: base64=0 and jsonOutput=0

HTTP Request

POST /api/v2/translations/quick

Request Parameters

Name	Type	Description	Default Value
`base64` (optional)	string	When this parameter is set to 0 (the default is 1), the input does not need to be Base64-encoded	`1`
`jsonOutput` (optional)	string	When this parameter is set to 0 (the default is 1), the output will be the translation itself, instead of JSON format	`1`
`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 (unless base64 parameter above is explicitly set to 0) and URL-encoded content to translate
`inputFormat` (optional)	string	Format of input document (see table of possible input formats)	`text/plain`
`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
`highlightDictionary` (optional)	boolean	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`
`highlightBrand` (optional)	boolean	Whether to highlight brand translations in the output. This only applies to non-search pattern brand matches, and both `inputFormat` and `outputFormat` are `text/html`.	`false`
`highlightFeedback` (optional)	boolean	Whether to highlight feedback translations in the output. This only applies to feedback matches, and both `inputFormat` and `outputFormat` are `text/html`.	`false`
`markSegments` (optional)	boolean	Whether to mark source and target segments in the output. This only applies if `inputFormat` and `outputFormat` are `text/html`.	`false`
`generateMetadata` (optional)	boolean	Generate metadata in addition to the translation (requires more computation)	`false`
`generateAlternatives` (optional)	boolean	Generate a number of alternative translations. This only applies if outputFormat is either `text/html` or `application/x-xliff`	`false`
`linguisticOptions` (optional)	array of key:value strings	Linguistic options to use for translation; (see list language-pairs) to display available linguistic options.

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

curl "https://controller-host:8001/api/v2/translations/bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "translationId": "bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd",
    "profile": {
        "username": "jsmith@example.com",
        "title": "example translation",
        "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
        "encoding": "utf-8",
        "inputFormat": "text/html",
        "pdfConverter": "",
        "pdfPageCount": 0,
        "imageConverter": "",
        "dictionaryIds": [
            "dict1_c95c72dd2f138da2a46c872a40616eb1",
            "dict2_397e8373985929881616bcaa4805844a"
        ],
        "outputFormat": "",
        "highlightDictionary": true,
        "highlightBrand": true,
        "highlightFeedback": true,
        "unknownMode": "transliteration",
        "highlightUnknown": false,
        "markSegments": true,
        "sourceRequested": false,
        "generateMetadata": false,
        "translationMethod": "MTE",
        "labels": [
            {
                "id": 4,
                "name": "Legal"
            },
            {
                "id": 28,
                "name": "Medical"
            }
        ],
        "includeEditorInput": false,
        "includeTextContent": false,
        "includeSegmentPairs": false
    },
    "result": {
        "completedSegments": 64,
        "inputSize": 3613,
        "sourceCharacterCount": 3498,
        "sourceWordCount": 689,
        "targetCharacterCount": 3840,
        "targetWordCount": 766,
        "totalSegments": 64,
        "outputSize": 4006,
        "progress": 100,
        "wordsPerMinute": 52065,
        "qualityEstimation": {
            "good": 73.333336,
            "adequate": 10.123456,
            "poor": 16.543211
        }
    },
    "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 asynchronous 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	Format of input document (see table of possible input formats)
`→ dictionaryIds`	array of strings	Dictionaries used for translation
`→ outputFormat`	string	Format of output document (see table of possible output formats)
`→ highlightDictionary`	string	Whether to highlight dictionary translations in the output
`→ highlightBrand`	string	Whether to highlight brand translations in the output
`→ highlightFeedback`	string	Whether to highlight feedback translations in the output
`→ unknownMode`	string	How to display unknown words
`→ highlightUnknown`	string	Whether to highlight unknown words or their transliterations
`→ markSegments`	string	Whether to mark source and target segments in the output.
`→ generateMetadata`	boolean	Whether metadata of output will be produced and included in response
`→ translationMethod`	string	Method used to translate the job
`→ labels`	array of labels	Labels associated with this translation
`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
	`transcribing`	job involves audio input and it is being transcribed
	`scheduled`	job has been scheduled for dispatch
	`dispatching`	job is being dispatched to a job engine
`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
	`failed`	job has failed
	`succeeded`	job has completed successfully

Download a translation

curl "https://controller-host:8001/api/v2/translations/bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd/download?base64=1" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

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

Request Parameters

Name	Type	Description	Default Value
`format` (optional)	string	The file format of the translation job to download. Choices: `default` to download the original output format of the translation job result, `text/plain` to download the plain text format of the translation job result, `segment-pairs` to download the segment pairs content of the translation job result, The `text/plain` option is only available if the translation job was performed with `includeTextContent` set to `true`. The `segment-pairs` option is only available if the translation job was performed with `includeSegmentPairs` set to `true`.	`default`
`base64` (optional)	string	When this parameter is set to 0 (the default is 1), the output will not be Base64-encoded

Returns

Returns the output of a translation in base64 encoding. If you want the output to not be encoded, please specify base64=0 as the input parameter.

Download translation(s) in a zip file

curl "https://controller-host:8001/api/v2/translations/download-archive?startTimeQueued=2019-01-01+11%3A26%3A45.158516672Z&translationIds=bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd%2C6f0985dd-e6b0-490a-8cec-27a45bc922c0" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

application/zip

Return the translated output(s) of completed asynchronous translation job(s) in a zip file.

HTTP Request

GET /api/v2/translations/download-archive

Request Parameters

Name	Type	Description
`translationIds` (optional)	string	Comma-separated identifier of translation job(s) Total output size of translations limited to 1GB
`username` (optional)	string	Download only translations created by this user. This field is ignored for non-super admin users.
`labels` (optional)	string	Download only translations with the given comma-separated labels.
`startTimeQueued` (optional)	string	Download only translations that were queued on or after the given timestamp. (see timestamps for formatting guidelines)
`endTimeQueued` (optional)	string	Download only translations that were queued on or before the given timestamp. (see timestamps for formatting)
`translationMethod` (optional)	string	Download only translations with the given translationMethod. (see list of supported translation methods)
`title` (optional)	string	Download only translations with the given title as a substring.
`sourceLanguageId` (optional)	string	Download only translations with the given sourceLanguageId (3-letter code).
`targetLanguageId` (optional)	string	Download only translations with the given targetLanguageId (3-letter code).
`languagePairId` (optional)	string	Download only translations with the given languagePairId. Cannot be used in combination with sourceLanguageId or targetLanguageId.

Returns

Returns the output(s) of translation(s) in a zip file.

Retrieve metadata of a translation

curl "https://controller-host:8001/api/v2/translations/bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd/metadata?base64=1" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

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

Request Parameters

Name	Type	Description	Default Value
`base64` (optional)	string	When this parameter is set to 0 (the default is 1), the output will not be Base64-encoded	`1`

Returns

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

Transcribe an audio file

curl "https://controller-host:8001/api/v2/translations/transcribe" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d input="@<file>" \
    -d sourceLanguageId="eng" \
    -d timeoutInSeconds="300" \
    -d title="audioFile"

{
    "translationId": "",
    "profile": {
        "username": "jsmith@example.com",
        "title": "audioFile",
        "languagePairId": "engeng",
        "encoding": "",
        "inputFormat": "audio/wav",
        "pdfConverter": "",
        "pdfPageCount": 0,
        "imageConverter": "",
        "dictionaryIds": [],
        "outputFormat": "",
        "highlightDictionary": false,
        "highlightBrand": false,
        "highlightFeedback": false,
        "unknownMode": "",
        "highlightUnknown": false,
        "markSegments": false,
        "sourceRequested": false,
        "generateMetadata": false,
        "includeEditorInput": false,
        "includeTextContent": false,
        "includeSegmentPairs": false,
        "transcriptionOnly": true
    },
    "result": {
        "completedSegments": 0,
        "inputSize": 0,
        "sourceCharacterCount": 0,
        "sourceWordCount": 0,
        "targetCharacterCount": 0,
        "targetWordCount": 0,
        "totalSegments": 0,
        "outputSize": 0,
        "progress": 0,
        "wordsPerMinute": 0,
        "qualityEstimation": {}
    },
    "timestamps": {
        "queued": "2018-06-21 19:03:31.799810031Z",
        "started": "",
        "done": ""
    },
    "errorMessage": "",
    "state": "preparing",
    "substate": "scheduled"
}

Transcribe an audio file

HTTP Request

POST /api/v2/translations/transcribe

Request Parameters

Name	Type	Description
`input`	file	Audio file to transcribe
`timeoutInSeconds` (optional)	int	Deadline to transcribe before timing out
`title` (optional)	string	Title of the transcription file
`sourceLanguageId` (optional)	string	3-letter code for the source language of the source audio
`inputFormat` (optional)	string	Format of input document (see table of possible input formats)

Returns

Returns a record of the transcription as a Translation object.

Retrieve content insights of a translation

curl "https://controller-host:8001/api/v2/translations/bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd/content-insights" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "title": "example translation",
    "summary": [
        {
            "segment": "This is an example of a summarized segment",
            "score": 0.7950247
        },
        {
            "segment": "Here is another summarized segment.",
            "score": 0.89506936
        },
        {
            "segment": "This is the last summarized segment in the group.",
            "score": 0.8836193
        }
    ]
}

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

HTTP Request

GET /api/v2/translations/{translationId}/content-insights

Path Parameters

Name	Type	Description
`translationId`	string	Identifier of translation job

Returns

Returns the content insights of a translation in JSON format in base64 encoding.

Name	Type	Description
`title`	string	Title of the translation document
`summary`	array of objects	Summarized segments of the document
`→ segment`	string	Segment of the summarization entry
`→ score`	float	Score rating the importance of the segment in the summary. 0 is minimum, 1 is maximum.

Cancel a translation

curl "https://controller-host:8001/api/v2/translations/bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd/cancel" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "translationId": "bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd",
    "profile": {
        "username": "jsmith@example.com",
        "title": "example translation",
        "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
        "encoding": "utf-8",
        "inputFormat": "text/html",
        "pdfConverter": "",
        "pdfPageCount": 0,
        "imageConverter": "",
        "dictionaryIds": [
            "dict1_c95c72dd2f138da2a46c872a40616eb1",
            "dict2_397e8373985929881616bcaa4805844a"
        ],
        "outputFormat": "",
        "highlightDictionary": true,
        "highlightBrand": true,
        "highlightFeedback": true,
        "unknownMode": "transliteration",
        "highlightUnknown": false,
        "markSegments": true,
        "sourceRequested": false,
        "generateMetadata": false,
        "translationMethod": "MTE",
        "labels": [
            {
                "id": 4,
                "name": "Legal"
            },
            {
                "id": 28,
                "name": "Medical"
            }
        ],
        "includeEditorInput": false,
        "includeTextContent": false,
        "includeSegmentPairs": false
    },
    "result": {
        "completedSegments": 0,
        "inputSize": 0,
        "sourceCharacterCount": 0,
        "sourceWordCount": 0,
        "targetCharacterCount": 0,
        "targetWordCount": 0,
        "totalSegments": 0,
        "outputSize": 0,
        "progress": 0,
        "wordsPerMinute": 0,
        "qualityEstimation": {}
    },
    "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.

Update a translation

curl "https://controller-host:8001/api/v2/translations/bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    --data-urlencode labels="Medical, Legal"

{
    "translationId": "bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd",
    "profile": {
        "username": "jsmith@example.com",
        "title": "example translation",
        "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
        "encoding": "utf-8",
        "inputFormat": "text/html",
        "pdfConverter": "",
        "pdfPageCount": 0,
        "imageConverter": "",
        "dictionaryIds": [
            "dict1_c95c72dd2f138da2a46c872a40616eb1",
            "dict2_397e8373985929881616bcaa4805844a"
        ],
        "outputFormat": "",
        "highlightDictionary": true,
        "highlightBrand": true,
        "highlightFeedback": true,
        "unknownMode": "transliteration",
        "highlightUnknown": false,
        "markSegments": true,
        "sourceRequested": false,
        "generateMetadata": false,
        "translationMethod": "MTE",
        "labels": [
            {
                "id": 4,
                "name": "Legal"
            },
            {
                "id": 28,
                "name": "Medical"
            }
        ],
        "includeEditorInput": false,
        "includeTextContent": false,
        "includeSegmentPairs": false
    },
    "result": {
        "completedSegments": 64,
        "inputSize": 3613,
        "sourceCharacterCount": 3498,
        "sourceWordCount": 689,
        "targetCharacterCount": 3840,
        "targetWordCount": 766,
        "totalSegments": 64,
        "outputSize": 4006,
        "progress": 100,
        "wordsPerMinute": 52065,
        "qualityEstimation": {
            "good": 73.333336,
            "adequate": 10.123456,
            "poor": 16.543211
        }
    },
    "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"
}

Update an asynchronous translation job’s details

HTTP Request

PUT /api/v2/translations/{translationId}

Path Parameters

Name	Type	Description
`translationId`	string	Identifier of translation job

Request Parameters

Name	Type	Description	Default Value
`labels` (optional)	array of string	Labels to update the translation job with

Returns

Returns the updated translation as a Translation object.

Delete a translation

curl "https://controller-host:8001/api/v2/translations/bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "translationId": "bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd",
    "profile": {
        "username": "jsmith@example.com",
        "title": "example translation",
        "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
        "encoding": "utf-8",
        "inputFormat": "text/html",
        "pdfConverter": "",
        "pdfPageCount": 0,
        "imageConverter": "",
        "dictionaryIds": [
            "dict1_c95c72dd2f138da2a46c872a40616eb1",
            "dict2_397e8373985929881616bcaa4805844a"
        ],
        "outputFormat": "",
        "highlightDictionary": true,
        "highlightBrand": true,
        "highlightFeedback": true,
        "unknownMode": "transliteration",
        "highlightUnknown": false,
        "markSegments": true,
        "sourceRequested": false,
        "generateMetadata": false,
        "translationMethod": "MTE",
        "labels": [
            {
                "id": 4,
                "name": "Legal"
            },
            {
                "id": 28,
                "name": "Medical"
            }
        ],
        "includeEditorInput": false,
        "includeTextContent": false,
        "includeSegmentPairs": false
    },
    "result": {
        "completedSegments": 64,
        "inputSize": 3613,
        "sourceCharacterCount": 3498,
        "sourceWordCount": 689,
        "targetCharacterCount": 3840,
        "targetWordCount": 766,
        "totalSegments": 64,
        "outputSize": 4006,
        "progress": 100,
        "wordsPerMinute": 52065,
        "qualityEstimation": {
            "good": 73.333336,
            "adequate": 10.123456,
            "poor": 16.543211
        }
    },
    "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.

Delete translations

curl "https://controller-host:8001/api/v2/translations/batch-delete" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf \
    -H "Content-Type: multipart/form-data" \
    -F startTimeQueued="2019-01-01 11:26:45.158516672Z"
    -F translationIds="bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd,6f0985dd-e6b0-490a-8cec-27a45bc922c0"

Remove translation jobs from the translation queue and history.

HTTP Request

DELETE /api/v2/translations/batch-delete

Request Parameters

Name	Type	Description
`translationIds` (optional)	string	Comma-separated identifier of translation job(s)
`username` (optional)	string	Delete only translations created by this user. This field is ignored for non-admin users.
`statuses` (optional)	string	Delete only translations with the given comma-separated states. (see table of possible states)
`labels` (optional)	string	Delete only translations with the given comma-separated labels.
`startTimeQueued` (optional)	string	Delete only translations that were queued on or after the given timestamp. (see timestamps for formatting guidelines)
`endTimeQueued` (optional)	string	Delete only translations that were queued on or before the given timestamp. (see timestamps for formatting)
`translationMethod` (optional)	string	Delete only translations with the given translationMethod. (see list of supported translation methods)
`title` (optional)	string	Delete only translations with the given title as a substring.
`sourceLanguageId` (optional)	string	Delete only translations with the given sourceLanguageId (3-letter code).
`targetLanguageId` (optional)	string	Delete only translations with the given targetLanguageId (3-letter code).
`languagePairId` (optional)	string	Delete only translations with the given languagePairId. Cannot be used in combination with sourceLanguageId or targetLanguageId.

Returns

Returns the number of deleted translations.

Labels

List labels

curl "https://controller-host:8001/api/v2/labels" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "labels": [
        {
            "id": 4,
            "name": "Legal"
        },
        {
            "id": 28,
            "name": "Medical"
        }
    ],
    "page": 1,
    "perPage": 25,
    "totalPages": 1,
    "totalItems": 1
}

Return a list of labels.

HTTP Request

GET /api/v2/labels

Request Parameters

Name	Type	Description	Default Value
`names` (optional)	string	Show only labels with the given names as a comma-separated list of substrings
`sortBy` (optional)	string	Sort the returning list by either ID or name	`id`

Returns

Returns a list of labels as a LabelList object with the following attributes:

Name	Type	Description
`labels`	array of labels	List of labels as an array of labels (expanded below)
`→ id`	int	Id of the label
`→ name`	string	Name of the label
`page`	int	Page number returned
`perPage`	int	Number of labels returned per page
`totalPages`	int	Total number of pages available
`totalItems`	int	Total number of labels

Create a label

curl "https://controller-host:8001/api/v2/labels" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d name="Health"

{
    "id": 28,
    "name": "Health"
}

Create a label.

HTTP Request

POST /api/v2/labels

Request Parameters

Name	Type	Description	Default Value
`name` (optional)	string	Name of the label to be created

Returns

Returns the created label.

Update a label

curl "https://controller-host:8001/api/v2/labels/28" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d name="NewHealth"

{
    "id": 28,
    "name": "NewHealth"
}

Update a label to a new name.

HTTP Request

PUT /api/v2/labels/{labelId}

Path Parameters

Name	Type	Description
`labelId`	int	Id of the label to be updated

Request Parameters

Name	Type	Description	Default Value
`name` (optional)	string	Name of the label to be updated to

Returns

Returns the updated label.

Delete a label

curl "https://controller-host:8001/api/v2/labels/28" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "id": 28,
    "name": "Medical"
}

Delete a label.

HTTP Request

DELETE /api/v2/labels/{labelId}

Path Parameters

Name	Type	Description
`labelId`	int	Identifier of the label to be deleted

Returns

Returns the deleted label.

Delete labels

curl "https://controller-host:8001/api/v2/labels/batch-delete" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf \
    -H "Content-Type: multipart/form-data" \
    -F labelIds="28"

{
    "id": 28,
    "name": "Medical"
}

Delete labels.

HTTP Request

DELETE /api/v2/labels/batch-delete

Request Parameters

Name	Type	Description	Default Value
`labelIds` (optional)	int	Comma-separated identifiers of labels to be deleted
`names` (optional)	string	Delete only labels with the given names as a comma-separated list of substrings

Returns

Returns the number of deleted labels.

Dictionaries

List dictionaries

curl "https://controller-host:8001/api/v2/dictionaries?sourceLanguageId=eng&targetLanguageId=fra" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "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
`dictionaryIds` (optional)		Comma-separated case-insensitive partial match of the dictionary IDs
`sourceLanguageId` (optional)	string	Source language (3-letter code)
`targetLanguageId` (optional)	string	Target language (3-letter code)
`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

curl "https://controller-host:8001/api/v2/dictionaries" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d base64="1" \
    -d dictionaryId="dict1" \
    -d sourceLanguageId="eng" \
    -d targetLanguageId="fra" \
    --data-urlencode content="PGRpY3Rpb25hcnk+PGRpY3QtZW50cmllcz48ZGljdC1lbnRyeT48c3JjLXNlZ21lbnQ+Ym9va21hcms8L3NyYy1zZWdtZW50Pjx0Z3Qtc2VnbWVudD5ib29rbWFyazwvdGd0LXNlZ21lbnQ+PHVzZXItY29tbWVudHM+PC91c2VyLWNvbW1lbnRzPjwvZGljdC1lbnRyeT48ZGljdC1lbnRyeT48c3JjLXNlZ21lbnQ+c29mdHdhcmU8L3NyYy1zZWdtZW50Pjx0Z3Qtc2VnbWVudD5zb2Z0d2FyZTwvdGd0LXNlZ21lbnQ+PHVzZXItY29tbWVudHM+PC91c2VyLWNvbW1lbnRzPjwvZGljdC1lbnRyeT48ZGljdC1lbnRyeT48c3JjLXNlZ21lbnQ+YnJvd3Nlcjwvc3JjLXNlZ21lbnQ+PHRndC1zZWdtZW50Pm5hdmlnYXRldXI8L3RndC1zZWdtZW50Pjx1c2VyLWNvbW1lbnRzPjwvdXNlci1jb21tZW50cz48L2RpY3QtZW50cnk+PC9kaWN0LWVudHJpZXM+PC9kaWN0aW9uYXJ5Pg==" \
    --data-urlencode importFormat="text/xml"

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

Create a dictionary to be available for use in translation.

HTTP Request

POST /api/v2/dictionaries

Request Parameters

Name	Type	Description	Default Value
`base64` (optional)	string	When this parameter is set to 0 (the default is 1), the “content” parameter below does not need to be Base64-encoded	`1`
`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` (optional)	string	Base64-encoded (unless base64 parameter above is explicity set to 0) and URL-encoded content of the dictionary in XML or Excel format (an example before base64-encoding can be found in the example response of Download a dictionary)
`importFormat` (optional)	string	Format type of import: text/xml or application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.	`text/xml`

Returns

Returns the newly-created dictionary as a Dictionary object.

Update a dictionary

curl "https://controller-host:8001/api/v2/dictionaries/dict1" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d base64="1" \
    --data-urlencode content="PGRpY3Rpb25hcnk+PGRpY3QtZW50cmllcz48ZGljdC1lbnRyeT48c3JjLXNlZ21lbnQ+Ym9va21hcms8L3NyYy1zZWdtZW50Pjx0Z3Qtc2VnbWVudD5ib29rbWFyazwvdGd0LXNlZ21lbnQ+PHVzZXItY29tbWVudHM+PC91c2VyLWNvbW1lbnRzPjwvZGljdC1lbnRyeT48ZGljdC1lbnRyeT48c3JjLXNlZ21lbnQ+YnJvd3Nlcjwvc3JjLXNlZ21lbnQ+PHRndC1zZWdtZW50Pm5hdmlnYXRldXI8L3RndC1zZWdtZW50Pjx1c2VyLWNvbW1lbnRzPjwvdXNlci1jb21tZW50cz48L2RpY3QtZW50cnk+PC9kaWN0LWVudHJpZXM+PC9kaWN0aW9uYXJ5Pgo=" \
    --data-urlencode importFormat="text/xml"

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

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
`base64` (optional)	string	When this parameter is set to 0 (the default is 1), the “content” parameter below does not need to be Base64-encoded	`1`
`content`	string	Base64-encoded (unless base64 parameter above is explicitly set to 0) and URL-encoded content of the dictionary in XML or Excel format (an example before base64-encoding can be found in the example response of Download a dictionary)
`importFormat` (optional)	string	Format type of import: text/xml or application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.	`text/xml`

Returns

Returns the updated dictionary Dictionary object.

Retrieve a dictionary

curl "https://controller-host:8001/api/v2/dictionaries/dict1?includeContent=true" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "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)	boolean	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

curl "https://controller-host:8001/api/v2/dictionaries/dict1/download?exportFormat=text%2Fxml" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

<dictionary>
    <dict-entries>
        <dict-entry is-hard-constraint="false" case-sensitive-match="false">
            <src-segment>bookmark</src-segment>
            <tgt-segment>bookmark</tgt-segment>
            <user-comments></user-comments>
        </dict-entry>
        <dict-entry is-hard-constraint="false" case-sensitive-match="false">
            <src-segment>software</src-segment>
            <tgt-segment>software</tgt-segment>
            <user-comments></user-comments>
        </dict-entry>
        <dict-entry is-hard-constraint="false" case-sensitive-match="false">
            <src-segment>browser</src-segment>
            <tgt-segment>navigateur</tgt-segment>
            <user-comments></user-comments>
        </dict-entry>
    </dict-entries>
</dictionary>

Download a dictionary as an XML or spreadhsheet file.

HTTP Request

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

Path Parameters

Name	Type	Description
`dictionaryId`	string	Identifier of dictionary

Request Parameters

Name	Type	Description	Default Value
`exportFormat` (optional)	string	File format for downloaded dictionary (supports `text/xml` or `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`)	`text/xml`

Returns

Returns the dictionary as XML or Excel.

Download dictionaries in a zip file

curl "https://controller-host:8001/api/v2/dictionaries/download-archive?dictionaryIds=dict1" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

application/zip

Download dictionaries as XML or spreadsheet files and archive in a zip.

HTTP Request

GET /api/v2/dictionaries/download-archive

Request Parameters

Name	Type	Description	Default Value
`dictionaryIds` (optional)	string	Comma-separated case-insensitive partial match of dictionary IDs Total output size of dictionaries limited to 1GB
`sourceLanguageId` (optional)	string	Download only dictionaries with the given sourceLanguageId (3-letter code).
`targetLanguageId` (optional)	string	Download only dictionaries with the given targetLanguageId (3-letter code).
`exportFormat` (optional)	string	File format for downloaded dictionaries in the zip file (supports `text/xml` or `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`)	`text/xml`

Returns

Returns the contents of the dictionaries with the specified MIME type (text/xml or application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.

Delete a dictionary

curl "https://controller-host:8001/api/v2/dictionaries/dict1" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "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.

Delete dictionaries

curl "https://controller-host:8001/api/v2/dictionaries/batch-delete" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf \
    -H "Content-Type: multipart/form-data" \
    -F dictionaryIds="dict1"

Remove dictionaries so they can no longer be used in translation.

HTTP Request

DELETE /api/v2/dictionaries/batch-delete

Request Parameters

Name	Type	Description
`dictionaryIds` (optional)	string	Comma-separated case-insensitive partial match of dictionary IDs
`sourceLanguageId` (optional)	string	Delete only dictionaries with the given sourceLanguageId (3-letter code).
`targetLanguageId` (optional)	string	Delete only dictionaries with the given targetLanguageId (3-letter code).

Returns

Returns the number of deleted dictionaries.

List dictionary terms

curl "https://controller-host:8001/api/v2/dictionaries/dict1/term?caseSensitiveMatch=false&comment=greeting&isFluentTerminology=true&source=hello&target=bonjour" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "dictionaryId": "dict1",
    "terms": [
        {
            "source": "hello",
            "target": "bonjour",
            "comment": "greeting",
            "isFluentTerminology": true,
            "caseSensitiveMatch": false
        },
        {
            "source": "bye",
            "target": "au revoir",
            "comment": "farewell",
            "isFluentTerminology": true,
            "caseSensitiveMatch": false
        }
    ],
    "termFilter": {
        "source": "",
        "target": "",
        "comment": "",
        "isFluentTerminology": "",
        "caseSensitiveMatch": ""
    },
    "page": 1,
    "perPage": 25,
    "totalPages": 1,
    "totalTerms": 2
}

List the terms from an existing dictionary.

HTTP Request

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

Path Parameters

Name	Type	Description
`dictionaryId`	string	Identifier of dictionary

Request Parameters

Name	Type	Description	Default Value
`source` (optional)	string	Filter list by given source text
`target` (optional)	string	Filter list by given target text
`comment` (optional)	string	Filter list by given comment text
`isFluentTerminology` (optional)	boolean	Filter list by given fluent terminology status
`caseSensitiveMatch` (optional)	boolean	Filter list by given case sensitivity status
`page` (optional)	int	Page number to return	`1`
`perPage` (optional)	int	Number of terms to return per page	`25`

Returns

Returns the list of dictionary terms as a TermList object.

Import terms to a dictionary

curl "https://controller-host:8001/api/v2/dictionaries/dict1/term/import" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d base64="1" \
    --data-urlencode content="PGRpY3Rpb25hcnk+PGRpY3QtZW50cmllcz48ZGljdC1lbnRyeT48c3JjLXNlZ21lbnQ+Ym9va21hcms8L3NyYy1zZWdtZW50Pjx0Z3Qtc2VnbWVudD5ib29rbWFyazwvdGd0LXNlZ21lbnQ+PHVzZXItY29tbWVudHM+PC91c2VyLWNvbW1lbnRzPjwvZGljdC1lbnRyeT48ZGljdC1lbnRyeT48c3JjLXNlZ21lbnQ+c29mdHdhcmU8L3NyYy1zZWdtZW50Pjx0Z3Qtc2VnbWVudD5zb2Z0d2FyZTwvdGd0LXNlZ21lbnQ+PHVzZXItY29tbWVudHM+PC91c2VyLWNvbW1lbnRzPjwvZGljdC1lbnRyeT48ZGljdC1lbnRyeT48c3JjLXNlZ21lbnQ+YnJvd3Nlcjwvc3JjLXNlZ21lbnQ+PHRndC1zZWdtZW50Pm5hdmlnYXRldXI8L3RndC1zZWdtZW50Pjx1c2VyLWNvbW1lbnRzPjwvdXNlci1jb21tZW50cz48L2RpY3QtZW50cnk+PC9kaWN0LWVudHJpZXM+PC9kaWN0aW9uYXJ5Pg==" \
    --data-urlencode importFormat="text/xml"

{
    "dictionaryId": "dict1",
    "sourceLanguageId": "eng",
    "targetLanguageId": "fra",
    "totalEntries": 3,
    "updatedEntries": 3
}

Import terms to an existing dictionary.

HTTP Request

POST /api/v2/dictionaries/{dictionaryId}/term/import

Path Parameters

Name	Type	Description
`dictionaryId`	string	Identifier of dictionary

Request Parameters

Name	Type	Description	Default Value
`base64` (optional)	string	When this parameter is set to 0 (the default is 1), the “content” parameter below does not need to be Base64-encoded	`1`
`content`	string	Base64-encoded (unless base64 parameter above is explicitly set to 0) and URL-encoded content of the dictionary in XML or Excel format (an example before base64-encoding can be found in the example response of Download a dictionary)
`importFormat` (optional)	string	Format type of import: text/xml or application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.	`text/xml`

Returns

Returns the dictionary as a Dictionary object.

Create a dictionary term

curl "https://controller-host:8001/api/v2/dictionaries/dict1/term" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d caseSensitiveMatch="false" \
    -d comment="greeting" \
    -d isFluentTerminology="true" \
    -d source="hello" \
    -d target="bonjour"

{
    "source": "hello",
    "target": "bonjour",
    "comment": "greeting",
    "isFluentTerminology": false,
    "caseSensitiveMatch": false
}

Create a term within an existing dictionary to be available for use in translation.

HTTP Request

POST /api/v2/dictionaries/{dictionaryId}/term

Path Parameters

Name	Type	Description
`dictionaryId`	string	Identifier of dictionary

Request Parameters

Name	Type	Description
`source`	string	Source text of term
`target`	string	Target text of term
`comment` (optional)	string	Comment text of term
`isFluentTerminology` (optional)	boolean	Whether the term should be considered Fluent Terminology
`caseSensitiveMatch` (optional)	boolean	Whether the term should match only when the casing of each character is the same

Returns

Returns the newly-created dictionary term as a Term object.

Update a dictionary term

curl "https://controller-host:8001/api/v2/dictionaries/dict1/term" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d caseSensitiveMatch="false" \
    -d comment="greeting" \
    -d isFluentTerminology="true" \
    -d originalSource="hello" \
    -d source="hello" \
    -d target="salut"

{
    "source": "hello",
    "target": "salut",
    "comment": "greeting",
    "isFluentTerminology": false,
    "caseSensitiveMatch": false
}

Update a term within an existing dictionary.

HTTP Request

PUT /api/v2/dictionaries/{dictionaryId}/term

Path Parameters

Name	Type	Description
`dictionaryId`	string	Identifier of dictionary

Request Parameters

Name	Type	Description
`originalSource`	string	Source text of existing term to be updated
`source`	string	Updated source text of term
`target`	string	Updated target text of term
`comment` (optional)	string	Updated comment text of term
`isFluentTerminology` (optional)	boolean	Whether the term should be considered Fluent Terminology
`caseSensitiveMatch` (optional)	boolean	Whether the term should match only when the casing of each character is the same

Returns

Returns the updated dictionary term as a Term object.

Delete a dictionary term

curl "https://controller-host:8001/api/v2/dictionaries/dict1/term" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf \
    -H "Content-Type: multipart/form-data" \
    -F source="test"

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

HTTP Request

DELETE /api/v2/dictionaries/{dictionaryId}/term

Path Parameters

Name	Type	Description
`dictionaryId`	string	Identifier of dictionary

Request Parameters

Name	Type	Description	Default Value
`source`	string	Source text of term to delete. This parameter can be repeated to delete multiple terms.

Returns

Returns the number of deleted terms.

Language Pairs

List language pairs

curl "https://controller-host:8001/api/v2/language-pairs?chains=also&domain=Generic&platform=SRV&sourceLanguageId=eng&targetLanguageId=fra&technology=TNMV" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "languagePairs": [
        {
            "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
            "sourceLanguage": "English",
            "sourceLanguageId": "eng",
            "sourceLanguageTag": "en",
            "targetLanguage": "French",
            "targetLanguageId": "fra",
            "targetLanguageTag": "fr",
            "domain": "Generic",
            "model": "Generic",
            "platform": "SRV",
            "technology": "TNMV",
            "version": "8.4.1",
            "linguisticOptions": [
                {
                    "id": "Formality",
                    "values": [
                        "Informal",
                        "Formal",
                        "Polite"
                    ],
                    "systemDefault": "Informal"
                }
            ]
        },
        {
            "languagePairId": "SpaEng_Generic_SRV_TNMV_8_4_x_2",
            "sourceLanguage": "Spanish",
            "sourceLanguageId": "spa",
            "sourceLanguageTag": "es",
            "targetLanguage": "English",
            "targetLanguageId": "eng",
            "targetLanguageTag": "en",
            "domain": "Generic",
            "model": "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",
            "sourceLanguageTag": "es",
            "targetLanguage": "French",
            "targetLanguageId": "fra",
            "targetLanguageTag": "fr",
            "domain": "Generic",
            "model": "Generic",
            "platform": "SRV",
            "technology": "TNMV",
            "version": "",
            "memberPairs": [
                {
                    "languagePairId": "SpaEng_Generic_SRV_TNMV_8_4_x_2",
                    "sourceLanguage": "Spanish",
                    "sourceLanguageId": "spa",
                    "sourceLanguageTag": "es",
                    "targetLanguage": "English",
                    "targetLanguageId": "eng",
                    "targetLanguageTag": "en",
                    "domain": "Generic",
                    "model": "Generic",
                    "platform": "SRV",
                    "technology": "TNMV",
                    "version": "8.4.2"
                },
                {
                    "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
                    "sourceLanguage": "English",
                    "sourceLanguageId": "eng",
                    "sourceLanguageTag": "en",
                    "targetLanguage": "French",
                    "targetLanguageId": "fra",
                    "targetLanguageTag": "fr",
                    "domain": "Generic",
                    "model": "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`
`sourceLanguageId` (optional)	string	Filter results to only show those with this source language ID
`targetLanguageId` (optional)	string	Filter results to only show those with this target language ID
`domain` (optional)	string	Filter results to only show those with this domain
`platform` (optional)	string	Filter results to only show those with this platform
`technology` (optional)	string	Filter results to only show those with this technology

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
`→ sourceLanguageTag`	string	IETF BCP 47 language tag for the source language
`→ targetLanguage`	string	Full name of target language
`→ targetLanguageId`	string	3-letter code of target language
`→ targetLanguageTag`	string	IETF BCP 47 language tag for the target language
`→ domain`	string	Domain of language pair
`→ model`	model	Model 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`	boolean	Whether the language pair is on Edge Cloud. Non-edge-cloud LPs do not have this.
`→ adaptable`	boolean	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`	boolean	Whether the language pair is a chain. Always true if present. Non-chain LPs do not have this.
`→ autoAdaptationEnabled`	boolean	Whether the language pair is enabled to auto adapt periodically using supplied data.
`→ linguisticOptions`	array of objects	List of available linguistic options as an array.

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

curl "https://controller-host:8001/api/v2/translation-chains" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "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

curl "https://controller-host:8001/api/v2/translation-chains" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    --data-urlencode chainId="SpaEng_Generic_SRV_TNMV_8_4_x_2>>EngFra_Generic_SRV_TNMV_8_4_x_1"

{
    "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`	boolean	True if this chain is being automatically managed by Edge, false if it is under manual management.
`isDeleted`	boolean	True if this represents a translation chain that has been manually deleted.
`running`	boolean	True if this chain and all its resources are running, and it is possible to submit translations to it.
`expectedRunning`	boolean	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

curl "https://controller-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 jsmith@example.com:u0VmztKJrwqf \
    -d autoManage="true"

{
    "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)	boolean	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

curl "https://controller-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 jsmith@example.com:u0VmztKJrwqf

{
    "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.

Feedback

List feedback entries

curl "https://controller-host:8001/api/v2/feedback" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "feedback": [
        {
            "feedbackId": "1",
            "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
            "username": "jsmith@example.com",
            "sourceText": "This is a sample input text.",
            "machineTranslation": "C'est un exemple de texte d'entrée.",
            "suggestedTranslation": "Ceci est un exemple de texte d'entrée.",
            "comment": "This is a sample feedback entry for documentation.",
            "approvalState": "awaitingApproval",
            "reviewer": "",
            "timestamps": {
                "reviewed": "",
                "created": "2021-05-25 00:14:01.363221018Z",
                "modified": "2021-05-25 00:14:01.363221018Z"
            }
        }
    ],
    "page": 1,
    "perPage": 25,
    "totalPages": 1,
    "totalItems": 1
}

Return a list of feedback entries.

HTTP Request

GET /api/v2/feedback

Request Parameters

Name	Type	Description	Default Value
`languagePairId` (optional)	string	Show only feedback with the given languagePairId. Cannot be used in combination with sourceLanguageId or targetLanguageId
`sourceLanguageId` (optional)	string	Show only feedback with the given sourceLanguageId
`targetLanguageId` (optional)	string	Show only feedback with the given targetLanguageId
`username` (optional)	string	Show only feedback created by the given user. This field is ignored for non-admin users
`sourceText` (optional)	string	Show only feedback when its source text contains the given sourceText
`machineTranslation` (optional)	string	Show only feedback when its machine translation contains the given machineTranslation
`suggestedTranslation` (optional)	string	Show only feedback when its suggested translation contains the given suggestedTranslation
`comment` (optional)	string	Show only feedback when its comment contains the given comment
`approvalStates` (optional)	string	Show only feedback with the given list of approvalStates, separated by commas (see list of valid approvalStates)
`reviewer` (optional)	string	Show only feedback reviewed by the given user
`startTimeCreated` (optional)	string	Show only feedback that were created on or after the given timestamp (see timestamps for formatting)
`endTimeCreated` (optional)	string	Show only feedback that were created on or before the given timestamp (see timestamps for formatting)
`page` (optional)	int	Page number to return	`1`
`perPage` (optional)	int	Number of feedback to return per page	`25`

Returns

Returns a list of feedback as a FeedbackList object with the following attributes:

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

Create a feedback entry

curl "https://controller-host:8001/api/v2/feedback" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d languagePairId="EngFra_Generic_SRV_TNMV_8_4_x_1" \
    --data-urlencode machineTranslation="C'est un exemple de texte d'entrée." \
    --data-urlencode sourceText="This is a sample input text." \
    --data-urlencode suggestedTranslation="Ceci est un exemple de texte d'entrée."

{
    "feedbackId": "1",
    "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
    "username": "jsmith@example.com",
    "sourceText": "This is a sample input text.",
    "machineTranslation": "C'est un exemple de texte d'entrée.",
    "suggestedTranslation": "Ceci est un exemple de texte d'entrée.",
    "comment": "This is a sample feedback entry for documentation.",
    "approvalState": "awaitingApproval",
    "reviewer": "",
    "timestamps": {
        "reviewed": "",
        "created": "2021-05-25 00:14:01.363221018Z",
        "modified": "2021-05-25 00:14:01.363221018Z"
    }
}

Create a feedback entry for the specific language pair, source text, and machine translation combination.

HTTP Request

POST /api/v2/feedback

Request Parameters

Name	Type	Description	Default Value
`languagePairId`	string	Identifier of the language pair
`sourceText`	string	Text that was originally submitted for translation
`machineTranslation` (optional)	string	Result of the translation of the source text
`suggestedTranslation`	string	Suggested improvement for the translation of the source text. It cannot be the same as the supplied machine translation
`approvalState` (optional)	string	Whether to approve or reject the feedback entry, by default only available for admin and linguist users (see list of valid approval states)	`awaitingApproval`
`comment` (optional)	string	Notes to keep for this feedback entry

Returns

Returns the created feedback as a Feedback object with the following attributes:

Name	Type	Description
`feedbackId`	string	Identifier for the feedback entry
`languagePairId`	string	Identifier of language pair
`username`	string	Username of user who created translation job
`sourceText`	string	Text that was originally submitted for translation
`machineTranslation`	string	Result of the translation of the source text
`suggestedTranslation`	string	Suggested improvement for the translation of the source text
`comment`	string	Notes to keep for this feedback entry
`approvalState`	string	Whether the feedback entry has been approved or rejected. (see list of valid approval states)
`reviewer`	string	Username of the user who approved or rejected this feedback entry
`timestamps`	object	Timestamps of checkpoints in the life of the feedback
`→ reviewed`	string	When the feedback was approved or rejected (see timestamps for formatting)
`→ created`	string	When the feedback was created (see timestamps for formatting)
`→ modified`	string	When any part of the feedback was modified (see timestamps for formatting)

Approval States

Method	Description
`awaitingApproval`	feedback has not been reviewed by an admin user
`approved`	feedback has been reviewed and approved by an admin user
`rejected`	feedback has been reviewed and rejected by an admin user

Retrieve a feedback entry

curl "https://controller-host:8001/api/v2/feedback/1" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "feedbackId": "1",
    "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
    "username": "jsmith@example.com",
    "sourceText": "This is a sample input text.",
    "machineTranslation": "C'est un exemple de texte d'entrée.",
    "suggestedTranslation": "Ceci est un exemple de texte d'entrée.",
    "comment": "This is a sample feedback entry for documentation.",
    "approvalState": "awaitingApproval",
    "reviewer": "",
    "timestamps": {
        "reviewed": "",
        "created": "2021-05-25 00:14:01.363221018Z",
        "modified": "2021-05-25 00:14:01.363221018Z"
    }
}

Return a feedback entry with the specific feedback ID.

HTTP Request

GET /api/v2/feedback/{feedbackId}

Path Parameters

Name	Type	Description
`feedbackId`	int	Feedback ID of the entry to return

Returns

Returns the specified feedback as a Feedback object.

Update a feedback entry

curl "https://controller-host:8001/api/v2/feedback/1" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d approvalState="approved" \
    --data-urlencode suggestedTranslation="Ceci est un exemple de texte d'entrée."

{
    "feedbackId": "1",
    "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
    "username": "jsmith@example.com",
    "sourceText": "This is a sample input text.",
    "machineTranslation": "C'est un exemple de texte d'entrée.",
    "suggestedTranslation": "Ceci est un exemple de texte d'entrée.",
    "comment": "",
    "approvalState": "awaitingApproval",
    "reviewer": "jsmith@example.com",
    "timestamps": {
        "reviewed": "2021-05-25 03:14:01.363221018Z",
        "created": "2021-05-25 00:14:01.363221018Z",
        "modified": "2021-05-25 03:14:01.363221018Z"
    }
}

Update a feedback entry with the specific feedback ID.

HTTP Request

PUT /api/v2/feedback/{feedbackId}

Path Parameters

Name	Type	Description
`feedbackId`	int	Feedback ID of the entry to update

Request Parameters

Name	Type	Description	Default Value
`suggestedTranslation` (optional)	string	Suggested improvement for the translation of the source text. If an empty string is provided, the suggested translation in effect will be an empty string
`approvalState` (optional)	string	Whether to approve or reject the feedback entry, by default only available for admin and linguist users (see list of valid approvalStates)	`awaitingApproval`
`comment` (optional)	string	Notes to keep for this feedback entry. If an empty string is provided, the previous comment will be removed

Returns

Returns the updated feedback as a Feedback object.

Export feedback entries

curl "https://controller-host:8001/api/v2/feedback/export?exportFormat=text%2Fx-tmx" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

<tmx version="1.4">
    <header creationtool="Language Weaver Edge" creationtoolversion="8.4.1" segtype="sentence" o-tmf="" adminlang="en-us" srclang="en" datatype="plaintext"></header>
    <body>
        <tu srclang="en">
            <tuv xml:lang="en">
                <seg>hello world</seg>
            </tuv>
            <tuv xml:lang="es">
                <seg>hola mundo</seg>
            </tuv>
            <tuv creationid="MT!" xml:lang="es">
                <seg>hola tierra</seg>
            </tuv>
            <note>example comment</note>
            <prop type="language_pair_id">EngSpa_Generic_SRV_TNMV_8_5_x_6</prop>
            <prop type="username">admin@localhost</prop>
            <prop type="approval_state">approved</prop>
            <prop type="reviewer">admin@localhost</prop>
            <prop type="review_date">2021-08-11 21:06:57.242039142Z</prop>
            <prop type="creation_date">2021-08-11 21:06:47.393801674Z</prop>
            <prop type="last_modification_date">2021-08-11 21:06:47.393801674Z</prop>
        </tu>
    </body>
</tmx>

Retrieve an export of feedback entries in TMX or Excel format.

HTTP Request

GET /api/v2/feedback/export

Request Parameters

Name	Type	Description	Default Value
`exportFormat` (optional)	string	File format for downloaded feedback entries (supports `text/x-tmx` or `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`)	`text/x-tmx`
`feedbackIds` (optional)	string	List of feedback identifiers, separated by commas, to export
`languagePairId` (optional)	string	LP to export feedback for (if unspecified, feedback for all LPs will be exported). Cannot be used in combination with sourceLanguageId or targetLanguageId
`sourceLanguageId` (optional)	string	Identifier of source language to export feedback for
`targetLanguageId` (optional)	string	Identifier of target language to export feedback for
`username` (optional)		Export only feedback created by the given user. This field is ignored for non-admin users
`sourceText` (optional)	string	Export only feedback when its source text contains the given sourceText
`machineTranslation` (optional)	string	Export only feedback when its machine translation contains the given machineTranslation
`suggestedTranslation` (optional)	string	Export only feedback when its suggested translation contains the given suggestedTranslation
`approvalStates` (optional)	string	Export only feedback with the given list of approval states, separated by commas (see list of valid approvalStates)
`reviewer` (optional)	string	Export only feedback reviewed by the given user
`startTimeCreated` (optional)	string	Export only feedback that were created on or after the given timestamp (see timestamps for formatting)
`endTimeCreated` (optional)	string	Export only feedback that were created on or before the given timestamp (see timestamps for formatting)

Returns

Returns the TMX contents of feedback entries with MIME type text/x-tmx.

Import feedback entries

curl "https://controller-host:8001/api/v2/feedback/import" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -H "Content-Type: multipart/form-data" \
    -F file="@<file>"
    -F importFormat="text/x-tmx"

{
    "successful": 10,
    "duplicate": 2,
    "invalid": 1,
    "warnings": [
        "no valid language pairs could be determined"
    ]
}

Import a file of feedback entries that is in TMX or Excel format.

HTTP Request

POST /api/v2/feedback/import

Request Parameters

Name	Type	Description	Default Value
`applyAll` (optional)	boolean	Apply all imported feedback entries to all installed language pairs that have the same matching source and target language	`false`
`approveAll` (optional)	boolean	Approve all imported feedback entries if no other feedback entry with matching language pair and source text has already been approved	`false`
`file`	file	File of feedback entries that is in TMX or Excel format
`importFormat` (optional)	string	Format type of import (supports text/x-tmx or application/vnd.openxmlformats-officedocument.spreadsheetml.sheet). Edge will assume the format type is TMX if none is provided.

Returns

Returns the imported feedback as an ImportFeedbackResponse object with the following attributes:

Name	Type	Description
`successful`	int	The number of feedback entries that were imported
`duplicate`	int	The number of feedback entries that were not imported due to another existing feedback with matching language pair, source text, and suggested translation
`invalid`	int	The number of feedback entries that were not imported due to an error
`warnings`	array of strings	List of warnings encountered when importing invalid feedback (up to a maximum of 10 warnings listed)

Delete a feedback entry

curl "https://controller-host:8001/api/v2/feedback/1" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "feedbackId": "1",
    "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
    "username": "jsmith@example.com",
    "sourceText": "This is a sample input text.",
    "machineTranslation": "C'est un exemple de texte d'entrée.",
    "suggestedTranslation": "Ceci est un exemple de texte d'entrée.",
    "comment": "",
    "approvalState": "rejected",
    "reviewer": "jsmith@example.com",
    "timestamps": {
        "reviewed": "2021-05-25 03:20:01.363221018Z",
        "created": "2021-05-25 00:14:01.363221018Z",
        "modified": "2021-05-25 03:20:01.363221018Z"
    }
}

Delete a feedback entry with the specific feedback ID.

HTTP Request

DELETE /api/v2/feedback/{feedbackId}

Path Parameters

Name	Type	Description
`feedbackId`	int	Feedback ID of the entry to delete

Returns

Returns the deleted feedback as a Feedback object.

Delete feedback entries

curl "https://controller-host:8001/api/v2/feedback/batch-delete" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf \
    -H "Content-Type: multipart/form-data" \
    -F feedbackIds="1"

Delete feedback entries.

HTTP Request

DELETE /api/v2/feedback/batch-delete

Request Parameters

Name	Type	Description
`feedbackIds` (optional)	int	Comma-separated identifiers of feedback entries to delete
`languagePairId` (optional)	string	Delete only feedback with the given languagePairId. Cannot be used in combination with sourceLanguageId or targetLanguageId
`sourceLanguageId` (optional)	string	Delete only feedback with the given sourceLanguageId
`targetLanguageId` (optional)	string	Delete only feedback with the given targetLanguageId
`username` (optional)	string	Delete only feedback created by the given user. This field is ignored for non-admin users
`sourceText` (optional)	string	Delete only feedback when its source text contains the given sourceText
`machineTranslation` (optional)	string	Delete only feedback when its machine translation contains the given machineTranslation
`suggestedTranslation` (optional)	string	Delete only feedback when its suggested translation contains the given suggestedTranslation
`comment` (optional)	string	Delete only feedback when its comment contains the given comment
`approvalStates` (optional)	string	Delete only feedback with the given list of approvalStates, separated by commas (see list of valid approvalStates)
`reviewer` (optional)	string	Delete only feedback reviewed by the given user
`startTimeCreated` (optional)	string	Delete only feedback that were created on or after the given timestamp (see timestamps for formatting)
`endTimeCreated` (optional)	string	Delete only feedback that were created on or before the given timestamp (see timestamps for formatting)

Returns

Returns the number of deleted feedback entries.

Users

List users

curl "https://controller-host:8001/api/v2/users" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "users": [
        {
            "username": "admin@example.com",
            "displayName": "Admin",
            "roles": [
                "admin"
            ],
            "manualRoleManagement": false,
            "disabled": false
        },
        {
            "username": "user@example.com",
            "displayName": "User",
            "roles": [
                ""
            ],
            "manualRoleManagement": false,
            "disabled": false
        }
    ],
    "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
`username` (optional)	string	Username substring to filter by
`displayName` (optional)	string	Display name substring to filter by
`roles` (optional)	string	Comma-separated list of user roles to filter by
`authenticationTypes` (optional)	string	Comma-separated list of authentication types to filter by
`manualRoleManagement` (optional)	boolean	If this user is SAML/LDAP, preserve the user roles upon login, even when SAML/LDAP configuration would normally change it
`disabled` (optional)	boolean	Whether the users are disabled or not
`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 in 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

curl "https://controller-host:8001/api/v2/users" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d displayName="User" \
    --data-urlencode username="user@example.com"

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

Create a new user and optionally specify a password.

HTTP Request

POST /api/v2/users

Request Parameters

Name	Type	Description
`username`	string	Email address of user
`displayName`	string	Name of the user to display
`roles` (optional)	string	Roles to assign user; only one role should be specified in the list
`password` (optional)	string	Must be at least 8 characters in length and have at least 3 of the following: lowercase character, uppercase character, number, and symbol; if not set, an automatically-generated password will be sent to the user’s email address
`manualRoleManagement` (optional)	boolean	If this user is SAML/LDAP, preserve the user roles upon login, even when SAML/LDAP configuration would normally change it
`disabled` (optional)	boolean	Whether the user is disabled

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`	string	Role assigned to user
`authenticationType`	string	How the user is authenticated
`manualRoleManagement`	boolean	If this user is SAML/LDAP, preserve the user roles upon login, even when SAML/LDAP configuration would normally change it
`disabled`	boolean	Whether the user has been disabled
`createdByUsername`	string	Email address of the user that created the listed user
`createdTime`	string	Timestamp of user creation
`lastLoginTime`	string	Timestamp of user’s last login
`lastModifiedByUsername`	string	Email address of the user that last modified the listed user
`lastModifiedTime`	string	Timestamp of last user modification
`lastTranslationTime`	string	Timestamp of user’s last translation

Roles

There are five possible roles that a user can be assigned as.

Role
`Super Admin`
`Admin`
`Linguist`
`Translator`
`Observer`

Update a user

curl "https://controller-host:8001/api/v2/users/user@example.com" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d displayName="Manager" \
    -d roles="admin"

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

Change a user’s display name, role or disabled status. 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
`displayName` (optional)	string	New name of the user to display
`roles` (optional)	string	Roles to assign user; only one role should be specified in the list
`manualRoleManagement` (optional)	boolean	If this user is SAML/LDAP, preserve the user roles upon login, even when SAML/LDAP configuration would normally change it
`disabled` (optional)	boolean	Whether the user is disabled

Returns

Returns the updated user as a User object.

Retrieve a user

curl "https://controller-host:8001/api/v2/users/user@example.com" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

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

Return information about a user.

This endpoint is restricted by default to users with the following roles only (except when specifying the current user with the special value of me): admin, super admin.

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.

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

{
    "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

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

{
    "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)	boolean	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

curl "https://controller-host:8001/api/v2/users/user@example.com/password" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d newPassword="newPassword" \
    -d oldPassword="noMaxLength"

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

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.

This endpoint is restricted by default to users with the following roles only (except when specifying the current user with the special value of me): admin, super admin.

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 8 characters in length and have at least 3 of the following: lowercase character, uppercase character, number, and symbol

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

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

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

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 8 characters in length and have at least 3 of the following: lowercase character, uppercase character, number, and symbol

Returns

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

Retrieve API credentials for the current user

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

{
    "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 Language Weaver Edge REST API as the current user

Change API credentials for the current user

curl "https://controller-host:8001/api/v2/users/me/credentials" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    --data-urlencode key="u_user@example.com_bluebird"

{
    "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

curl "https://controller-host:8001/api/v2/users/user@example.com" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf

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

Delete a user’s account and all of their translations. 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.

Delete users

curl "https://controller-host:8001/api/v2/users/batch-delete" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf \
    -H "Content-Type: multipart/form-data" \
    -F usernames="user1"

Delete users’ account and all of their translations. No notification will be sent to the users’ email addresses.

HTTP Request

DELETE /api/v2/users/batch-delete

Request Parameters

Name	Type	Description
`usernames` (optional)	string	Comma-separated username substrings to filter by
`displayName` (optional)	string	Display name substring to filter by
`roles` (optional)	string	Comma-separated list of user roles to filter by
`authenticationTypes` (optional)	string	Comma-separated list of authentication types to filter by
`disabled` (optional)	boolean	Whether the users are disabled or not

Returns

Returns the number of deleted users.

List all permissions

curl "https://controller-host:8001/api/v2/users/permissions" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "admin": {
        "ACCESS_FEEDBACK_EDITOR": true,
        "AUTO_APPROVE_FEEDBACK": true,
        "CONFIGURE_TLS": false,
        "DEPLOY_ADAPTED_LPS": true,
        "DOWNLOAD_ALL_TRANSLATIONS": false,
        "LIST_DICTIONARIES": true,
        "MANAGE_ADAPTED_LPS": true,
        "MANAGE_ALL_TRANSLATIONS": true,
        "MANAGE_BRANDS": true,
        "MANAGE_CUSTOM_FILES": false,
        "MANAGE_DICTIONARIES": true,
        "MANAGE_ENTITLEMENTS": true,
        "MANAGE_FEEDBACK": true,
        "MANAGE_HOSTS": true,
        "MANAGE_LABELS": true,
        "MANAGE_LP_CHAINS": true,
        "MANAGE_METRICS": true,
        "MANAGE_REPORTS": true,
        "MANAGE_SYSTEM_SETTINGS": true,
        "MANAGE_THEMES": true,
        "MANAGE_THEMES_SECURITY": false,
        "MANAGE_USERS": true,
        "MANAGE_WEBHOOKS": true,
        "SUBMIT_FEEDBACK": true,
        "SUBMIT_TRANSLATIONS": true,
        "TRANSCRIBE_STREAM": true,
        "UPDATE_DICTIONARIES": true,
        "VIEW_DICTIONARIES": true,
        "VIEW_HOSTS": true,
        "VIEW_METRICS": true
    },
    "linguist": {
        "ACCESS_FEEDBACK_EDITOR": true,
        "AUTO_APPROVE_FEEDBACK": false,
        "CONFIGURE_TLS": false,
        "DEPLOY_ADAPTED_LPS": false,
        "DOWNLOAD_ALL_TRANSLATIONS": false,
        "LIST_DICTIONARIES": true,
        "MANAGE_ADAPTED_LPS": true,
        "MANAGE_ALL_TRANSLATIONS": false,
        "MANAGE_BRANDS": false,
        "MANAGE_CUSTOM_FILES": false,
        "MANAGE_DICTIONARIES": true,
        "MANAGE_ENTITLEMENTS": false,
        "MANAGE_FEEDBACK": true,
        "MANAGE_HOSTS": false,
        "MANAGE_LABELS": false,
        "MANAGE_LP_CHAINS": false,
        "MANAGE_METRICS": false,
        "MANAGE_REPORTS": false,
        "MANAGE_SYSTEM_SETTINGS": false,
        "MANAGE_THEMES": false,
        "MANAGE_THEMES_SECURITY": false,
        "MANAGE_USERS": false,
        "MANAGE_WEBHOOKS": false,
        "SUBMIT_FEEDBACK": true,
        "SUBMIT_TRANSLATIONS": true,
        "UPDATE_DICTIONARIES": true,
        "VIEW_DICTIONARIES": true,
        "VIEW_HOSTS": true,
        "VIEW_METRICS": false
    },
    "observer": {
        "ACCESS_FEEDBACK_EDITOR": false,
        "AUTO_APPROVE_FEEDBACK": false,
        "CONFIGURE_TLS": false,
        "DEPLOY_ADAPTED_LPS": false,
        "DOWNLOAD_ALL_TRANSLATIONS": false,
        "LIST_DICTIONARIES": false,
        "MANAGE_ADAPTED_LPS": false,
        "MANAGE_ALL_TRANSLATIONS": false,
        "MANAGE_BRANDS": false,
        "MANAGE_CUSTOM_FILES": false,
        "MANAGE_DICTIONARIES": false,
        "MANAGE_ENTITLEMENTS": false,
        "MANAGE_FEEDBACK": false,
        "MANAGE_HOSTS": false,
        "MANAGE_LABELS": false,
        "MANAGE_LP_CHAINS": false,
        "MANAGE_METRICS": false,
        "MANAGE_REPORTS": false,
        "MANAGE_SYSTEM_SETTINGS": false,
        "MANAGE_THEMES": false,
        "MANAGE_THEMES_SECURITY": false,
        "MANAGE_USERS": false,
        "MANAGE_WEBHOOKS": false,
        "SUBMIT_FEEDBACK": false,
        "SUBMIT_TRANSLATIONS": false,
        "UPDATE_DICTIONARIES": false,
        "VIEW_DICTIONARIES": false,
        "VIEW_HOSTS": false,
        "VIEW_METRICS": true
    },
    "super admin": {
        "ACCESS_FEEDBACK_EDITOR": true,
        "AUTO_APPROVE_FEEDBACK": true,
        "CONFIGURE_TLS": true,
        "DEPLOY_ADAPTED_LPS": true,
        "DOWNLOAD_ALL_TRANSLATIONS": true,
        "LIST_DICTIONARIES": true,
        "MANAGE_ADAPTED_LPS": true,
        "MANAGE_ALL_TRANSLATIONS": true,
        "MANAGE_BRANDS": true,
        "MANAGE_CUSTOM_FILES": true,
        "MANAGE_DICTIONARIES": true,
        "MANAGE_ENTITLEMENTS": true,
        "MANAGE_FEEDBACK": true,
        "MANAGE_HOSTS": true,
        "MANAGE_LABELS": true,
        "MANAGE_LP_CHAINS": true,
        "MANAGE_METRICS": true,
        "MANAGE_REPORTS": true,
        "MANAGE_SYSTEM_SETTINGS": true,
        "MANAGE_THEMES": true,
        "MANAGE_THEMES_SECURITY": true,
        "MANAGE_USERS": true,
        "MANAGE_WEBHOOKS": true,
        "RESET_ROLES_TO_DEFAULT": true,
        "SUBMIT_FEEDBACK": true,
        "SUBMIT_TRANSLATIONS": true,
        "TRANSCRIBE_STREAM": true,
        "UPDATE_DICTIONARIES": true,
        "VIEW_DICTIONARIES": true,
        "VIEW_HOSTS": true,
        "VIEW_METRICS": true
    },
    "translator": {
        "ACCESS_FEEDBACK_EDITOR": false,
        "AUTO_APPROVE_FEEDBACK": false,
        "CONFIGURE_TLS": false,
        "DEPLOY_ADAPTED_LPS": false,
        "DOWNLOAD_ALL_TRANSLATIONS": false,
        "LIST_DICTIONARIES": true,
        "MANAGE_ADAPTED_LPS": false,
        "MANAGE_ALL_TRANSLATIONS": false,
        "MANAGE_BRANDS": false,
        "MANAGE_CUSTOM_FILES": false,
        "MANAGE_DICTIONARIES": false,
        "MANAGE_ENTITLEMENTS": false,
        "MANAGE_FEEDBACK": false,
        "MANAGE_HOSTS": false,
        "MANAGE_LABELS": false,
        "MANAGE_LP_CHAINS": false,
        "MANAGE_METRICS": false,
        "MANAGE_REPORTS": false,
        "MANAGE_SYSTEM_SETTINGS": false,
        "MANAGE_THEMES": false,
        "MANAGE_THEMES_SECURITY": false,
        "MANAGE_USERS": false,
        "MANAGE_WEBHOOKS": false,
        "SUBMIT_FEEDBACK": true,
        "SUBMIT_TRANSLATIONS": true,
        "UPDATE_DICTIONARIES": false,
        "VIEW_DICTIONARIES": false,
        "VIEW_HOSTS": true,
        "VIEW_METRICS": false
    }
}

Return a list of permission for each user role.

HTTP Request

GET /api/v2/users/permissions

Returns

Returns a list of Permissions for each user role.

Permissions

Each role has the following boolean permission attributes.

Permission	Description
`ACCESS_FEEDBACK_EDITOR`	Permission to access feedback editor
`AUTO_APPROVE_FEEDBACK`	Permission to auto approve feedback
`CONFIGURE_TLS`	Permission to configure TLS configuration
`DEPLOY_ADAPTED_LPS`	Permission to deploy adapted language pairs
`DOWNLOAD_ALL_TRANSLATIONS`	Permission to download all translations
`LIST_DICTIONARIES`	Permission to list dictionaries
`MANAGE_ADAPTED_LPS`	Permission to manage adapted language pairs
`MANAGE_ALL_TRANSLATIONS`	Permission to manage all translations
`MANAGE_BRANDS`	Permission to manage brands
`MANAGE_CUSTOM_FILES`	Permission to manage custom files
`MANAGE_DICTIONARIES`	Permission to manage dictionaries
`MANAGE_ENTITLEMENTS`	Permission to manage entitlements
`MANAGE_FEEDBACK`	Permission to manage feedback
`MANAGE_HOSTS`	Permission to manage hosts
`MANAGE_LABELS`	Permission to manage labels
`MANAGE_LP_CHAINS`	Permission to manage language pair chains
`MANAGE_METRICS`	Permission to manage metrics
`MANAGE_REPORTS`	Permission to manage reports
`MANAGE_SYSTEM_SETTINGS`	Permission to manage system settings
`MANAGE_THEMES`	Permission to manage themes
`MANAGE_THEMES_SECURITY`	Permission to manage themes security settings
`MANAGE_USERS`	Permission to manage users and permissions
`MANAGE_WEBHOOKS`	Permission to manage webhooks
`RESET_ROLES_TO_DEFAULT`	Permission to reset roles to default
`SUBMIT_FEEDBACK`	Permission to submit feedback
`SUBMIT_TRANSLATIONS`	Permission to submit translations
`TRANSCRIBE_STREAM`	Permission to transcribe stream
`UPDATE_DICTIONARIES`	Permission to update dictionaries
`VIEW_DICTIONARIES`	Permission to view dictionaries
`VIEW_HOSTS`	Permission to view hosts
`VIEW_METRICS`	Permission to view metrics

List permissions for current user

curl "https://controller-host:8001/api/v2/users/me/permissions" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "ACCESS_FEEDBACK_EDITOR": true,
    "AUTO_APPROVE_FEEDBACK": true,
    "CONFIGURE_TLS": true,
    "DEPLOY_ADAPTED_LPS": true,
    "DOWNLOAD_ALL_TRANSLATIONS": true,
    "LIST_DICTIONARIES": true,
    "MANAGE_ADAPTED_LPS": true,
    "MANAGE_ALL_TRANSLATIONS": true,
    "MANAGE_BRANDS": true,
    "MANAGE_CUSTOM_FILES": true,
    "MANAGE_DICTIONARIES": true,
    "MANAGE_ENTITLEMENTS": true,
    "MANAGE_FEEDBACK": true,
    "MANAGE_HOSTS": true,
    "MANAGE_LABELS": true,
    "MANAGE_LP_CHAINS": true,
    "MANAGE_METRICS": true,
    "MANAGE_REPORTS": true,
    "MANAGE_SYSTEM_SETTINGS": true,
    "MANAGE_THEMES": true,
    "MANAGE_THEMES_SECURITY": true,
    "MANAGE_USERS": true,
    "MANAGE_WEBHOOKS": true,
    "RESET_ROLES_TO_DEFAULT": true,
    "SUBMIT_FEEDBACK": true,
    "SUBMIT_TRANSLATIONS": true,
    "TRANSCRIBE_STREAM": true,
    "UPDATE_DICTIONARIES": true,
    "VIEW_DICTIONARIES": true,
    "VIEW_HOSTS": true,
    "VIEW_METRICS": true
}

Return permissions for current user’s role.

HTTP Request

GET /api/v2/users/me/permissions

Returns

Returns Permissions for current user’s role.

Update a permission

curl "https://controller-host:8001/api/v2/users/permissions" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d enabled="true" \
    -d permission="SUBMIT_TRANSLATIONS" \
    -d role="translator"

Update a permission for the desired role.

HTTP Request

PUT /api/v2/users/permissions

Request Parameters

Name	Type	Description	Default Value
`role`	string	Role to modify
`permission`	string	Permission to modify
`enabled` (optional)	boolean	Whether this permission is enabled for the role	`false`

Returns

Returns a list of Permissions for each user role with its modified state.

Reset permissions

curl "https://controller-host:8001/api/v2/users/permissions/reset" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf

Reset permissions for all roles to default settings.

HTTP Request

PUT /api/v2/users/permissions/reset

Returns

Returns a list of Permissions for each user role in its reset state.

Hosts

List hosts

curl "https://controller-host:8001/api/v2/hosts" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "hosts": [
        {
            "hostname": "controller-host",
            "hostAgentPort": 4637,
            "hostAgentRunning": true,
            "languagePairs": {
                "EngFra_Generic_SRV_TNMV_8_4_x_1": true,
                "SpaEng_Generic_SRV_TNMV_8_4_x_2": true
            },
            "message": {
                "warnings": [
                    "warning1",
                    "warning2"
                ],
                "errors": [
                    "error1",
                    "error2"
                ]
            },
            "jobEngines": [
                {
                    "config": {
                        "id": "34a2",
                        "host": "controller-host",
                        "hostAgentPort": 4637
                    },
                    "running": true,
                    "expectedRunning": true
                }
            ],
            "translationEngines": [
                {
                    "config": {
                        "id": "a1d8",
                        "host": "controller-host",
                        "hostAgentPort": 4637,
                        "languagePair": "EngFra_Generic_SRV_TNMV_8_4_x_1",
                        "isEdgeCloud": false
                    },
                    "running": true,
                    "expectedRunning": true
                },
                {
                    "config": {
                        "id": "onw8",
                        "host": "controller-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

curl "https://controller-host:8001/api/v2/hosts" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d hostAgentPort="4637" \
    -d hostname="controller-host"

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

Add a new host, which can serve job engine(s) and/or translation engine(s). This host must already have Language Weaver Edge installed and its Host Agent running. This host can be either a Controller host or a Worker host, so long as there is only one Controller host in the entire Language Weaver Edge 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`	boolean	Whether this host’s Host Agent is running
`languagePairs`	map from string to boolean	For each language pair installed on this host, the language pair identifier (string) and whether it is licensed on this host (bool)
`message`	object	A `Message` object with attributes:
`→ warnings`	array of strings	A list of host warning messages
`→ errors`	array of strings	A list of host error messages
`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
`edgeCloudEngines`	array of objects	List of edge cloud engines on this host as an array of `EdgeCloudEngine` objects
`trainingEngines`	array of objects	List of training engines on this host as an array of `TrainingEngine` objects
`summarizerEngines`	array of objects	List of summarizer engines on this host as an array of `SummarizerEngine` objects

Retrieve host profile

curl "https://controller-host:8001/api/v2/hosts/controller-host/profile" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "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"
            ],
            "utilization": 2.22
        }
    ],
    "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`	float	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
`→ utilization`	float	Percentage of CPU being used
`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

curl "https://controller-host:8001/api/v2/hosts/controller-host" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf

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

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

curl "https://controller-host:8001/api/v2/hosts/controller-host/job-engines" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d id="34a2" \
    -d start="true"

{
    "config": {
        "id": "34a2",
        "host": "controller-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	`[Random ID]`
`start` (optional)	boolean	Start the engine when added	`false`

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`	boolean	Whether this job engine is actually running
`expectedRunning`	boolean	Whether this job engine is expected to be running

Start a job engine

curl "https://controller-host:8001/api/v2/hosts/controller-host/job-engines/34a2/start" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "config": {
        "id": "34a2",
        "host": "controller-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

curl "https://controller-host:8001/api/v2/hosts/controller-host/job-engines/34a2/stop" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "config": {
        "id": "34a2",
        "host": "controller-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.

Reset a job engine config

curl "https://controller-host:8001/api/v2/hosts/controller-host/job-engines/34a2/reset-config" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf

"OK"

Reset an existing job engine config to default settings. The job engine must be restarted for the new settings to take effect.

HTTP Request

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

Path Parameters

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

Returns

Returns HTTP Status 200 (OK).

Delete a job engine

curl "https://controller-host:8001/api/v2/hosts/controller-host/job-engines/34a2" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "config": {
        "id": "34a2",
        "host": "controller-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

curl "https://controller-host:8001/api/v2/hosts/controller-host/translation-engines" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d desiredProcessingUnits="2" \
    -d id="a1d8" \
    -d languagePair="EngFra_Generic_SRV_TNMV_8_4_x_1" \
    -d start="true"

{
    "config": {
        "id": "a1d8",
        "host": "controller-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`
`maximumProcessingUnits` (optional)	int	Maximum number of processing units Language Weaver Edge can automatically assign to this translation engine	`same as the value of desiredProcessingUnits`
`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 `auto` for auto-detect)	`cpu`
`start` (optional)	boolean	Start the engine when added	`false`

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`	boolean	Whether language pair is on Edge Cloud
`→ desiredProcessingUnits`	int	Number of processing units desired to assign to this translation engine
`→ maximumProcessingUnits`	int	Maximum number of processing units Language Weaver Edge can automatically assign to this translation engine
`→ mode`	string	Translation engine mode
`running`	boolean	Whether this translation engine is actually running
`expectedRunning`	boolean	Whether this translation engine is expected to be running

Start a translation engine

curl "https://controller-host:8001/api/v2/hosts/controller-host/translation-engines/a1d8/start" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "config": {
        "id": "a1d8",
        "host": "controller-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

curl "https://controller-host:8001/api/v2/hosts/controller-host/translation-engines/a1d8/stop" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "config": {
        "id": "a1d8",
        "host": "controller-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.

Reset a translation engine config

curl "https://controller-host:8001/api/v2/hosts/controller-host/translation-engines/a1d8/reset-config" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf

"OK"

Reset an existing translation engine config to default settings. The translation engine must be restarted for the new settings to take effect.

HTTP Request

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

Path Parameters

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

Request Parameters

Name	Type	Description	Default Value
`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 `auto` or left blank for auto-detect)	`auto`

Returns

Returns HTTP Status 200 (OK).

Delete a translation engine

curl "https://controller-host:8001/api/v2/hosts/controller-host/translation-engines/a1d8" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "config": {
        "id": "a1d8",
        "host": "controller-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 an edge cloud engine

curl "https://controller-host:8001/api/v2/hosts/controller-host/edge-cloud-engines" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d id="ec01" \
    -d start="true"

{
    "config": {
        "id": "ec01",
        "host": "controller-host",
        "hostAgentPort": 4637
    },
    "running": false,
    "expectedRunning": false
}

Add an edge cloud engine to a host.

HTTP Request

POST /api/v2/hosts/{hostname}/edge-cloud-engines

Path Parameters

Name	Type	Description
`hostname`	string	Name of host

Request Parameters

Name	Type	Description	Default Value
`id` (optional)	string	Identifier to name edge cloud 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
`start` (optional)	boolean	Start the engine when added	`false`

Returns

Returns the newly-added edge cloud engine as an EdgeCloudEngine object with the following attributes:

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

Start an edge cloud engine

curl "https://controller-host:8001/api/v2/hosts/controller-host/edge-cloud-engines/ec01/start" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "config": {
        "id": "ec01",
        "host": "controller-host",
        "hostAgentPort": 4637
    },
    "running": false,
    "expectedRunning": true
}

Start an existing edge cloud engine to process translations via Language Weaver.

HTTP Request

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

Path Parameters

Name	Type	Description
`hostname`	string	Name of host
`engineId`	string	Identifier of edge cloud engine

Returns

Returns the started edge cloud engine as an EdgeCloudEngine object.

Stop an edge cloud engine

curl "https://controller-host:8001/api/v2/hosts/controller-host/edge-cloud-engines/ec01/stop" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "config": {
        "id": "ec01",
        "host": "controller-host",
        "hostAgentPort": 4637
    },
    "running": true,
    "expectedRunning": false
}

Stop an existing edge cloud engine so it is no longer available to process translations via Language Weaver.

HTTP Request

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

Path Parameters

Name	Type	Description
`hostname`	string	Name of host
`engineId`	string	Identifier of edge cloud engine

Returns

Returns the stopped edge cloud engine as an EdgeCloudEngine object.

Delete an edge cloud engine

curl "https://controller-host:8001/api/v2/hosts/controller-host/edge-cloud-engines/ec01" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "config": {
        "id": "ec01",
        "host": "controller-host",
        "hostAgentPort": 4637
    },
    "running": true,
    "expectedRunning": true
}

Delete an edge cloud engine from a host.

HTTP Request

DELETE /api/v2/hosts/{hostname}/edge-cloud-engines/{engineId}

Path Parameters

Name	Type	Description
`hostname`	string	Name of host
`engineId`	string	Identifier of edge cloud engine

Returns

Returns the deleted edge cloud engine as an EdgeCloudEngine object.

Add a training engine

curl "https://controller-host:8001/api/v2/hosts/controller-host/training-engines" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d id="d9s4" \
    -d start="true"

{
    "config": {
        "id": "d9s4",
        "host": "controller-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
`mode` (optional)	string	Mode of training engine (either `cpu`, `gpu` - for hosts with a GPU, or `auto` or left blank for auto-detect)	`auto`
`start` (optional)	boolean	Start the engine when added	`false`

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`	boolean	Whether this training engine is actually running
`expectedRunning`	boolean	Whether this training engine is expected to be running

Start a training engine

curl "https://controller-host:8001/api/v2/hosts/controller-host/training-engines/d9s4/start" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "config": {
        "id": "d9s4",
        "host": "controller-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

curl "https://controller-host:8001/api/v2/hosts/controller-host/training-engines/d9s4/stop" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "config": {
        "id": "d9s4",
        "host": "controller-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.

Reset a training engine config

curl "https://controller-host:8001/api/v2/hosts/controller-host/training-engines/d9s4/reset-config" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf

"OK"

Reset an existing training engine config to default settings. The training engine must be restarted for the new settings to take effect.

HTTP Request

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

Path Parameters

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

Request Parameters

Name	Type	Description	Default Value
`mode` (optional)	string	Mode of training engine (either `cpu`, `gpu` - for hosts with a GPU, or `auto` or left blank for auto-detect)	`auto`

Returns

Returns HTTP Status 200 (OK).

Delete a training engine

curl "https://controller-host:8001/api/v2/hosts/controller-host/training-engines/d9s4" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "config": {
        "id": "d9s4",
        "host": "controller-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.

Add a summarizer engine

curl "https://controller-host:8001/api/v2/hosts/controller-host/summarizer-engines" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d id="cd51" \
    -d start="true"

{
    "config": {
        "id": "cd51",
        "host": "controller-host",
        "hostAgentPort": 4637,
        "returnIndexesOnly": false,
        "minSegmentLength": 0,
        "requireEosPunctuation": true,
        "summaryLength": 3,
        "summarizationTimeout": 600
    },
    "running": false,
    "expectedRunning": false
}

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

HTTP Request

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

Path Parameters

Name	Type	Description
`hostname`	string	Name of host

Request Parameters

Name	Type	Description	Default Value
`id` (optional)	string	Identifier to name summarizer 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	`[Random ID]`
`start` (optional)	boolean	Start the engine when added	`false`

Returns

Returns the newly-added summarizer engine as a SummarizerEngine object with the following attributes:

Name	Type	Description
`config`	object	Configuration of summarizer engine (expanded below)
`→ id`	string	Identifier of summarizer engine
`→ host`	string	Name of host on which summarizer engine is running
`→ hostAgentPort`	string	Host Agent port
`→ returnIndexesOnly`	boolean	Whether to return the indices of the ‘summaryLength’ segments
`→ minSegmentLength`	int	Only analyze segments above this number of characters
`→ requireEosPunctuation`	boolean	Whether to require end of sentence punctuation [’.’, ’?’, ’!’]
`→ summaryLength`	int	The maximum number of summaries to return
`→ summarizationTimeout`	int	Timeout for summarization in seconds
`running`	boolean	Whether this summarizer engine is actually running
`expectedRunning`	boolean	Whether this summarizer engine is expected to be running

Start a summarizer engine

curl "https://controller-host:8001/api/v2/hosts/controller-host/summarizer-engines/cd51/start" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "config": {
        "id": "cd51",
        "host": "controller-host",
        "hostAgentPort": 4637,
        "returnIndexesOnly": false,
        "minSegmentLength": 0,
        "requireEosPunctuation": true,
        "summaryLength": 3,
        "summarizationTimeout": 600
    },
    "running": false,
    "expectedRunning": true
}

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

HTTP Request

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

Path Parameters

Name	Type	Description
`hostname`	string	Name of host
`engineId`	string	Identifier of summarizer engine

Returns

Returns the started summarizer engine as a SummarizerEngine object.

Stop a summarizer engine

curl "https://controller-host:8001/api/v2/hosts/controller-host/summarizer-engines/cd51/stop" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "config": {
        "id": "cd51",
        "host": "controller-host",
        "hostAgentPort": 4637,
        "returnIndexesOnly": false,
        "minSegmentLength": 0,
        "requireEosPunctuation": true,
        "summaryLength": 3,
        "summarizationTimeout": 600
    },
    "running": true,
    "expectedRunning": false
}

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

HTTP Request

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

Path Parameters

Name	Type	Description
`hostname`	string	Name of host
`engineId`	string	Identifier of summarizer engine

Returns

Returns the stopped summarizer engine as a SummarizerEngine object.

Reset a summarizer engine config

curl "https://controller-host:8001/api/v2/hosts/controller-host/summarizer-engines/cd51/reset-config" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf

"OK"

Reset an existing summarizer engine config to default settings. The summarizer engine must be restarted for the new settings to take effect.

HTTP Request

PUT /api/v2/hosts/{hostname}/summarizer-engines/{engineId}/reset-config

Path Parameters

Name	Type	Description
`hostname`	string	Name of host
`engineId`	string	Identifier of summarizer engine

Returns

Returns HTTP Status 200 (OK).

Delete a summarizer engine

curl "https://controller-host:8001/api/v2/hosts/controller-host/summarizer-engines/cd51" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "config": {
        "id": "cd51",
        "host": "controller-host",
        "hostAgentPort": 4637,
        "returnIndexesOnly": false,
        "minSegmentLength": 0,
        "requireEosPunctuation": true,
        "summaryLength": 3,
        "summarizationTimeout": 600
    },
    "running": true,
    "expectedRunning": true
}

Delete a summarizer 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}/summarizer-engines/{engineId}

Path Parameters

Name	Type	Description
`hostname`	string	Name of host
`engineId`	string	Identifier of summarizer engine

Returns

Returns the deleted summarizer engine as a SummarizerEngine object.

Add an audio transcription engine

curl "https://controller-host:8001/api/v2/hosts/controller-host/audio-transcription-engines" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d capabilities="batching" \
    -d id="a28c" \
    -d start="true"

{
    "config": {
        "id": "a28c",
        "host": "controller-host",
        "hostAgentPort": 4637
    },
    "running": false,
    "expectedRunning": false
}

Add an audio transcription engine with a specific language pair to a host.

HTTP Request

POST /api/v2/hosts/{hostname}/audio-transcription-engines

Path Parameters

Name	Type	Description
`hostname`	string	Name of host

Request Parameters

Name	Type	Description	Default Value
`id` (optional)	string	Identifier to name audio transcription 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
`start` (optional)	boolean	Start the engine when added	`false`
`mode` (optional)	string	Audio Transcription engine mode (either `cpu`, `gpu`, or `auto`	`auto`
`capabilities` (optional)	string	Audio Transcription engine capability (valid option is `batching`	`[batching]`

Returns

Returns the newly-added audio transcription engine as a AudioTranscriptionEngine object with the following attributes:

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

Start an audio transcription engine

curl "https://controller-host:8001/api/v2/hosts/controller-host/audio-transcription-engines/a28c/start" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "config": {
        "id": "a28c",
        "host": "controller-host",
        "hostAgentPort": 4637
    },
    "running": false,
    "expectedRunning": true
}

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

HTTP Request

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

Path Parameters

Name	Type	Description
`hostname`	string	Name of host
`engineId`	string	Identifier of audio transcription engine

Returns

Returns the started audio transcription engine as a AudioTranscriptionEngine object.

Stop an audio transcription engine

curl "https://controller-host:8001/api/v2/hosts/controller-host/audio-transcription-engines/a28c/stop" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "config": {
        "id": "a28c",
        "host": "controller-host",
        "hostAgentPort": 4637
    },
    "running": true,
    "expectedRunning": false
}

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

HTTP Request

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

Path Parameters

Name	Type	Description
`hostname`	string	Name of host
`engineId`	string	Identifier of audio transcription engine

Returns

Returns the stopped audio transcription engine as a AudioTranscriptionEngine object.

Reset an audio transcription engine config

curl "https://controller-host:8001/api/v2/hosts/controller-host/audio-transcription-engines/a28c/reset-config" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf

"OK"

Reset an existing audio transcription engine config to default settings. The audio transcription engine must be restarted for the new settings to take effect.

HTTP Request

PUT /api/v2/hosts/{hostname}/audio-transcription-engines/{engineId}/reset-config

Path Parameters

Name	Type	Description
`hostname`	string	Name of host
`engineId`	string	Identifier of audio transcription engine

Request Parameters

Name	Type	Description	Default Value
`mode` (optional)	string	Audio Transcription engine mode (either `cpu`, `gpu`, or `auto`	`auto`

Returns

Returns HTTP Status 200 (OK).

Delete an audio transcription engine

curl "https://controller-host:8001/api/v2/hosts/controller-host/audio-transcription-engines/a28c" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "config": {
        "id": "a28c",
        "host": "controller-host",
        "hostAgentPort": 4637
    },
    "running": true,
    "expectedRunning": true
}

Delete an audio transcription 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}/audio-transcription-engines/{engineId}

Path Parameters

Name	Type	Description
`hostname`	string	Name of host
`engineId`	string	Identifier of audio transcription engine

Returns

Returns the deleted audio transcription engine as a AudioTranscriptionEngine object.

Entitlements

Retrieve entitlements

curl "https://controller-host:8001/api/v2/entitlements" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "processingUnits": {
        "desired": [
            {
                "translationEngineId": "a1d8",
                "count": 3
            },
            {
                "translationEngineId": "onw8",
                "count": 2
            }
        ],
        "maximum": [
            {
                "translationEngineId": "a1d8",
                "count": 4
            },
            {
                "translationEngineId": "onw8",
                "count": 2
            }
        ],
        "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
`→ → count`	int	Number of processing units desired to be assigned to the translation engine
`→ maximum`	array of objects	List of maximum assignments of processing units to translation engines
`→ → translationEngineId`	string	Identifier of translation engine
`→ → count`	int	Maximum number of processing units Language Weaver Edge may automatically assign to the translation engine as needed
`→ filled`	array of objects	List of processing units actually filled by translation engines
`→ → translationEngineId`	string	Identifier of translation engine
`→ → count`	int	Number of processing units actually filled by the translation engine
`→ total`	int	Total number of processing units available in license

Update entitlements

curl "https://controller-host:8001/api/v2/entitlements" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -H "Content-Type: application/json" \
    -d '{"processingUnits":{"desired":[{"translationEngineId":"a1d8","count":3},{"translationEngineId":"onw8","count":2}],"maximum":[{"translationEngineId":"a1d8","count":4},{"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`	array of objects	List of desired assignments of processing units to translation engines
`→ → translationEngineId`	string	Identifier of translation engine
`→ → count`	int	Number of processing units desired to be assigned to the translation engine
`→ maximum` (optional)	array of objects	List of maximum assignments of processing units to translation engines
`→ → translationEngineId` (optional)	string	Identifier of translation engine
`→ → count` (optional)	int	Maximum number of processing units Language Weaver Edge may automatically assign to the translation engine as needed	`same as the value of desired count for the same translation engine ID`

Update Language Weaver license file

curl "https://controller-host:8001/api/v2/entitlements/license" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    --data-urlencode file="@filepath"

"OK"

Change the active Language Weaver Edge license file.

HTTP Request

PUT /api/v2/entitlements/license

Request Parameters

Name	Type	Description	Default Value
`file` (optional)	file	New license file for Language Weaver Edge to use

Returns

Returns HTTP Status 200 (OK).

Download the entitlements profile

curl "https://controller-host:8001/api/v2/entitlements/profile" \
    -X GET \
    -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 Language Weaver

Language Pair Adaptation

Retrieve adapted language pairs

curl "https://controller-host:8001/api/v2/adapted-language-pairs" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "languagePairs": [
        {
            "trainingId": "06f0be27-96f0-4961-a630-49372f21f497",
            "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": "controller-host",
                "adaptationMode": "balanced"
            },
            "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,
                    "autoExtractedTranslationUnits": 1000
                }
            },
            "bleu": {
                "baseline": 25.3,
                "adapted": 25.3
            },
            "qualityMetrics": {
                "baseline": {
                    "chrF++": 33.99,
                    "bleuScore": 25.3,
                    "editDistance": 24.53
                },
                "adapted": {
                    "chrF++": 33.99,
                    "bleuScore": 25.3,
                    "editDistance": 24.53
                }
            },
            "timestamps": {
                "queued": "2019-02-05 13:52:50.98704786Z",
                "trainingStart": "",
                "completed": ""
            },
            "errorMessage": "",
            "state": "training",
            "progress": 54,
            "dataCleanerReport": {
                "trainingDataReport": {
                    "segmentsIn": 5,
                    "segmentsOut": 3,
                    "segmentsDiscarded": 2
                }
            }
        }
    ],
    "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
`baselineModel` (optional)	string	Filters adapted language pairs to those that have the given baseline model
`username` (optional)	string	Filters adapted language pairs to those that were submitted by a given user
`domain` (optional)	string	Filters adapted language pairs to those that have the given domain
`model` (optional)	string	Filters adapted language pairs to those that have the given model
`statuses` (optional)	string	Show only adapted language pairs with the given list of statuses, separated by commas
`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
`uploading`	training data is being uploaded to a training host
`dispatching`	job is being dispatched to a training engine
`initializing`	job is beginning training
`training`	job is being trained
`computingQualityMetrics`	job is having its quality metrics computed
`downloading`	adapted lp is being downloaded to controller host
`readyToDeploy`	job has finished training and can be deployed
`deleting`	job is being deleted
`deleted`	job has been deleted
`canceled`	job has been canceled
`failed`	job has failed

Create an adapted language pair

curl "https://controller-host:8001/api/v2/adapted-language-pairs" \
    -X POST \
    -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="controller-host"
    -F name="myAdaptedLP"
    -F testData="@<file>"
    -F trainingData="@<file>"

{
    "trainingId": "06f0be27-96f0-4961-a630-49372f21f497",
    "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": "controller-host",
        "adaptationMode": "balanced"
    },
    "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,
            "autoExtractedTranslationUnits": 1000
        }
    },
    "bleu": {
        "baseline": 25.3,
        "adapted": 25.3
    },
    "qualityMetrics": {
        "baseline": {
            "chrF++": 33.99,
            "bleuScore": 25.3,
            "editDistance": 24.53
        },
        "adapted": {
            "chrF++": 33.99,
            "bleuScore": 25.3,
            "editDistance": 24.53
        }
    },
    "timestamps": {
        "queued": "2019-02-05 13:52:50.98704786Z",
        "trainingStart": "",
        "completed": ""
    },
    "errorMessage": "",
    "state": "dispatching",
    "dataCleanerReport": {
        "trainingDataReport": {
            "segmentsIn": 5,
            "segmentsOut": 3,
            "segmentsDiscarded": 2
        }
    }
}

Begin training a language-pair for adaptation

HTTP Request

POST /api/v2/adapted-language-pairs

Request Parameters

Name	Type	Description
`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 language pair on it.
`comments` (optional)	string	Optional comments to add to the adapted LP
`verifySegmentation` (optional)	boolean	Optional flag to tell the trainer to verify that each line has one segment (and to normalize it otherwise)

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`	boolean	True if the test data was automatically extracted from the input training data. If false, sufficient test data was supplied.
`→ → autoExtractedTranslationUnits`	int	Number of translation units automatically extracted from input training data for test data
`→ verifySegmentation`	boolean	True if verification of the one-segment-per-line rule for the input was requested.
`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
`qualityMetrics`	object	The quality metrics of the adapted language pair versus the baseline language pair’s result (expanded below)
`→ baseline`	object	The quality metrics of the baseline language pair (expanded below)
`→ → chrF++`	object	The chrF++ of the baseline language pair
`→ → bleuScore`	object	The bleu score of the baseline language pair
`→ → editDistance`	object	The edit distance of the baseline language pair
`→ adapted`	object	The quality metrics of the adapted language pair (expanded below)
`→ → chrF++`	object	The chrF++ of the adapted language pair
`→ → bleuScore`	object	The bleu score of the adapted language pair
`→ → editDistance`	object	The edit distance 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`
`dataCleanerReport`	object	Training data cleaning report
`segmentsIn`	int	Number of segments received by data cleaner
`segmentsOut`	int	Number of segments output by data cleaner
`segmentsDiscarded`	int	Number of discarded segments
`state`	string	Training job state (see table)
`hostsDeployedTo`	array of strings	A list of hosts this language pair is currently deployed to

Analyze training input data

curl "https://controller-host:8001/api/v2/adapted-language-pairs/analyze" \
    -X POST \
    -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>"

{
    "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,
            "autoExtractedTranslationUnits": 1000
        }
    }
}

Analyze training input data for language-pair adaptation

HTTP Request

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

Request Parameters

Name	Type	Description
`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`	boolean	True if the test data was automatically extracted from the input training data. If false, sufficient test data was supplied.
`→ → autoExtractedTranslationUnits`	int	Number of translation units automatically extracted from input training data for test data
`→ verifySegmentation`	boolean	True if verification of the one-segment-per-line rule for the input was requested.

Retrieve information on adapted language pairs

curl "https://controller-host:8001/api/v2/adapted-language-pairs/EngFra_Adapted-myAdaptedLP_SRV_PB_8_0_x_0/training-jobs/06f0be27-96f0-4961-a630-49372f21f497" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "trainingId": "06f0be27-96f0-4961-a630-49372f21f497",
    "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": "controller-host",
        "adaptationMode": "balanced"
    },
    "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,
            "autoExtractedTranslationUnits": 1000
        }
    },
    "bleu": {
        "baseline": 25.3,
        "adapted": 25.3
    },
    "qualityMetrics": {
        "baseline": {
            "chrF++": 33.99,
            "bleuScore": 25.3,
            "editDistance": 24.53
        },
        "adapted": {
            "chrF++": 33.99,
            "bleuScore": 25.3,
            "editDistance": 24.53
        }
    },
    "timestamps": {
        "queued": "2019-02-05 13:52:50.98704786Z",
        "trainingStart": "",
        "completed": ""
    },
    "errorMessage": "",
    "state": "training",
    "progress": 54,
    "dataCleanerReport": {
        "trainingDataReport": {
            "segmentsIn": 5,
            "segmentsOut": 3,
            "segmentsDiscarded": 2
        }
    }
}

Retrieve information on a given adapted language pair

HTTP Request

GET /api/v2/adapted-language-pairs/{languagePairId}/training-jobs/{trainingId}

Path Parameters

Name	Type	Description
`languagePairId`	string	ID of adapted language pair
`trainingId`	string	Training ID of the adaptation job

Returns

Returns information on the adapted language pair as an AdaptedLanguagePair object

Update a language pair adaptation

curl "https://controller-host:8001/api/v2/adapted-language-pairs/EngFra_Adapted-myAdaptedLP_SRV_PB_8_0_x_0/training-jobs/06f0be27-96f0-4961-a630-49372f21f497" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    --data-urlencode comment="This is my new adapted LP comment."

{
    "trainingId": "06f0be27-96f0-4961-a630-49372f21f497",
    "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": "controller-host",
        "adaptationMode": "balanced"
    },
    "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,
            "autoExtractedTranslationUnits": 1000
        }
    },
    "bleu": {
        "baseline": 25.3,
        "adapted": 25.3
    },
    "qualityMetrics": {
        "baseline": {
            "chrF++": 33.99,
            "bleuScore": 25.3,
            "editDistance": 24.53
        },
        "adapted": {
            "chrF++": 33.99,
            "bleuScore": 25.3,
            "editDistance": 24.53
        }
    },
    "timestamps": {
        "queued": "2019-02-05 13:52:50.98704786Z",
        "trainingStart": "",
        "completed": ""
    },
    "errorMessage": "",
    "state": "readyToDeploy",
    "dataCleanerReport": {
        "trainingDataReport": {
            "segmentsIn": 5,
            "segmentsOut": 3,
            "segmentsDiscarded": 2
        }
    }
}

Update a given adapted language pair

HTTP Request

PUT /api/v2/adapted-language-pairs/{languagePairId}/training-jobs/{trainingId}

Path Parameters

Name	Type	Description
`languagePairId`	string	ID of adapted language pair
`trainingId`	string	Training 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

curl "https://controller-host:8001/api/v2/adapted-language-pairs/EngFra_Adapted-myAdaptedLP_SRV_PB_8_0_x_0/training-jobs/06f0be27-96f0-4961-a630-49372f21f497/cancel" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "trainingId": "06f0be27-96f0-4961-a630-49372f21f497",
    "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": "controller-host",
        "adaptationMode": "balanced"
    },
    "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,
            "autoExtractedTranslationUnits": 1000
        }
    },
    "bleu": {
        "baseline": 25.3,
        "adapted": 25.3
    },
    "qualityMetrics": {
        "baseline": {
            "chrF++": 33.99,
            "bleuScore": 25.3,
            "editDistance": 24.53
        },
        "adapted": {
            "chrF++": 33.99,
            "bleuScore": 25.3,
            "editDistance": 24.53
        }
    },
    "timestamps": {
        "queued": "2019-02-05 13:52:50.98704786Z",
        "trainingStart": "",
        "completed": ""
    },
    "errorMessage": "",
    "state": "canceled",
    "dataCleanerReport": {
        "trainingDataReport": {
            "segmentsIn": 5,
            "segmentsOut": 3,
            "segmentsDiscarded": 2
        }
    }
}

Cancel the adaptation of a language pair

HTTP Request

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

Path Parameters

Name	Type	Description
`languagePairId`	string	ID of adapted language pair
`trainingId`	string	Training ID of adapted language pair

Returns

Returns information on the adapted language pair as an AdaptedLanguagePair object

Deploy an adapted language pair

curl "https://controller-host:8001/api/v2/adapted-language-pairs/EngFra_Adapted-myAdaptedLP_SRV_PB_8_0_x_0/training-jobs/06f0be27-96f0-4961-a630-49372f21f497/deploy" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d hostname="controller-host"

{
    "trainingId": "06f0be27-96f0-4961-a630-49372f21f497",
    "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": "controller-host",
        "adaptationMode": "balanced"
    },
    "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,
            "autoExtractedTranslationUnits": 1000
        }
    },
    "bleu": {
        "baseline": 25.3,
        "adapted": 25.3
    },
    "qualityMetrics": {
        "baseline": {
            "chrF++": 33.99,
            "bleuScore": 25.3,
            "editDistance": 24.53
        },
        "adapted": {
            "chrF++": 33.99,
            "bleuScore": 25.3,
            "editDistance": 24.53
        }
    },
    "timestamps": {
        "queued": "2019-02-05 13:52:50.98704786Z",
        "trainingStart": "",
        "completed": ""
    },
    "errorMessage": "",
    "state": "readyToDeploy",
    "hostsDeployedTo": [
        "controller-host"
    ],
    "dataCleanerReport": {
        "trainingDataReport": {
            "segmentsIn": 5,
            "segmentsOut": 3,
            "segmentsDiscarded": 2
        }
    }
}

Deploys an adapted language pair to a given host

HTTP Request

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

Path Parameters

Name	Type	Description
`languagePairId`	string	ID of adapted language pair
`trainingId`	string	Training 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

curl "https://controller-host:8001/api/v2/adapted-language-pairs/EngFra_Adapted-myAdaptedLP_SRV_PB_8_0_x_0/undeploy" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d hostname="controller-host"

{
    "trainingId": "06f0be27-96f0-4961-a630-49372f21f497",
    "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": "controller-host",
        "adaptationMode": "balanced"
    },
    "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,
            "autoExtractedTranslationUnits": 1000
        }
    },
    "bleu": {
        "baseline": 25.3,
        "adapted": 25.3
    },
    "qualityMetrics": {
        "baseline": {
            "chrF++": 33.99,
            "bleuScore": 25.3,
            "editDistance": 24.53
        },
        "adapted": {
            "chrF++": 33.99,
            "bleuScore": 25.3,
            "editDistance": 24.53
        }
    },
    "timestamps": {
        "queued": "2019-02-05 13:52:50.98704786Z",
        "trainingStart": "",
        "completed": ""
    },
    "errorMessage": "",
    "state": "readyToDeploy",
    "dataCleanerReport": {
        "trainingDataReport": {
            "segmentsIn": 5,
            "segmentsOut": 3,
            "segmentsDiscarded": 2
        }
    }
}

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

Export an adapted language pair

curl "https://controller-host:8001/api/v2/adapted-language-pairs/EngFra_Adapted-myAdaptedLP_SRV_PB_8_0_x_0/training-jobs/06f0be27-96f0-4961-a630-49372f21f497/export" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

"application/zip"

Exports an adapted language pair from a given host

HTTP Request

GET /api/v2/adapted-language-pairs/{languagePairId}/training-jobs/{trainingId}/export

Path Parameters

Name	Type	Description
`languagePairId`	string	ID of adapted language pair
`trainingId`	string	Training ID of adapted language pair

Returns

Returns an archive containing the adapted language pair and supporting metadata

Import an adapted language pair

curl "https://controller-host:8001/api/v2/adapted-language-pairs/import" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -H "Content-Type: multipart/form-data" \
    -F input="@<file>"

{
    "trainingId": "06f0be27-96f0-4961-a630-49372f21f497",
    "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": "controller-host",
        "adaptationMode": "balanced"
    },
    "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,
            "autoExtractedTranslationUnits": 1000
        }
    },
    "bleu": {
        "baseline": 25.3,
        "adapted": 25.3
    },
    "qualityMetrics": {
        "baseline": {
            "chrF++": 33.99,
            "bleuScore": 25.3,
            "editDistance": 24.53
        },
        "adapted": {
            "chrF++": 33.99,
            "bleuScore": 25.3,
            "editDistance": 24.53
        }
    },
    "timestamps": {
        "queued": "2019-02-05 13:52:50.98704786Z",
        "trainingStart": "",
        "completed": ""
    },
    "errorMessage": "",
    "state": "readyToDeploy",
    "dataCleanerReport": {
        "trainingDataReport": {
            "segmentsIn": 5,
            "segmentsOut": 3,
            "segmentsDiscarded": 2
        }
    }
}

Imports an exported adapted language pair

HTTP Request

PUT /api/v2/adapted-language-pairs/import

Request Parameters

Name	Type	Description	Default Value
`input`	file	An archive of an adapted LP that was obtained by exporting an adapted LP

Returns

Returns information on the adapted language pair as an AdaptedLanguagePair object

Delete an adapted language pair

curl "https://controller-host:8001/api/v2/adapted-language-pairs/EngFra_Adapted-myAdaptedLP_SRV_PB_8_0_x_0/training-jobs/06f0be27-96f0-4961-a630-49372f21f497" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "trainingId": "06f0be27-96f0-4961-a630-49372f21f497",
    "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": "controller-host",
        "adaptationMode": "balanced"
    },
    "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,
            "autoExtractedTranslationUnits": 1000
        }
    },
    "bleu": {
        "baseline": 25.3,
        "adapted": 25.3
    },
    "qualityMetrics": {
        "baseline": {
            "chrF++": 33.99,
            "bleuScore": 25.3,
            "editDistance": 24.53
        },
        "adapted": {
            "chrF++": 33.99,
            "bleuScore": 25.3,
            "editDistance": 24.53
        }
    },
    "timestamps": {
        "queued": "2019-02-05 13:52:50.98704786Z",
        "trainingStart": "",
        "completed": ""
    },
    "errorMessage": "",
    "state": "deleted",
    "dataCleanerReport": {
        "trainingDataReport": {
            "segmentsIn": 5,
            "segmentsOut": 3,
            "segmentsDiscarded": 2
        }
    }
}

Delete a language pair adaptation

HTTP Request

DELETE /api/v2/adapted-language-pairs/{languagePairId}/training-jobs/{trainingId}

Path Parameters

Name	Type	Description
`languagePairId`	string	ID of adapted language pair
`trainingId`	string	Training ID of adapted language pair

Returns

Returns information on the adapted language pair as an AdaptedLanguagePair object

List auto adaptive language pairs

curl "https://controller-host:8001/api/v2/adapted-language-pairs/auto?sourceLanguageId=eng&targetLanguageId=ger" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "entries": [
        {
            "languagePairId": "EngGer_AutoAdaptive_SRV_TNM",
            "baselineLanguagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
            "autoAdaptationEnabled": true,
            "useUserProvidedTestData": false,
            "adaptationMode": "balanced",
            "dictionaryChanges": 492,
            "feedbackChanges": 392,
            "translationMemoryChanges": 17,
            "dictionaryTrainingUnits": 0,
            "feedbackTrainingUnits": 0,
            "translationMemoryTrainingUnits": 0,
            "trainingHost": "controller-host",
            "translationMemories": [
                {
                    "languagePairId": "EngGer_AutoAdaptive_SRV_TNM",
                    "filename": "",
                    "uploadedBy": "jsmith@example.com",
                    "uploadTime": "2018-06-21 19:03:31.799810031Z",
                    "tuCount": 23901,
                    "uuid": "205cb9b9-f72b-42b6-bbf2-824aa15c4978",
                    "isTestData": false
                }
            ],
            "desiredDeployedTrainingJob": "06f0be27-96f0-4961-a630-49372f21f497",
            "hostsToDeployTo": [
                "controller-host"
            ]
        }
    ],
    "page": 0,
    "perPage": 25,
    "totalPages": 1,
    "totalItems": 1
}

Retrieve the list of all auto adaptive language pairs

HTTP Request

GET /api/v2/adapted-language-pairs/auto

Request Parameters

Name	Type	Description	Default Value
`sourceLanguageId` (optional)	string	Filters auto adaptive language pair templates to those that share the same source language ID
`targetLanguageId` (optional)	string	Filters auto adaptive language pair templates to those that share the same target language ID
`page` (optional)	int	Page number to return	`1`
`perPage` (optional)	int	Number of auto adaptive language pair templates to return per page	`25`

Returns

Returns all auto adaptive language pairs as an AutoAdaptiveLPTemplateEntryList object with the following attributes:

Name	Type	Description
`entries`	array of objects	List of auto adaptive language pairs as an array of `AutoAdaptiveLPTemplateEntry` objects
`page`	int	Page number returned
`perPage`	int	Number of auto adaptive language pairs returned per page
`totalPages`	int	Total number of pages available
`totalItems`	int	Total number of auto adaptive language pairs

Retrieve auto adaptive language pair template

curl "https://controller-host:8001/api/v2/adapted-language-pairs/auto/EngGer_AutoAdaptive_SRV_TNM" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "languagePairId": "EngGer_AutoAdaptive_SRV_TNM",
    "baselineLanguagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
    "autoAdaptationEnabled": true,
    "useUserProvidedTestData": false,
    "adaptationMode": "balanced",
    "dictionaryChanges": 492,
    "feedbackChanges": 392,
    "translationMemoryChanges": 17,
    "dictionaryTrainingUnits": 0,
    "feedbackTrainingUnits": 0,
    "translationMemoryTrainingUnits": 0,
    "trainingHost": "controller-host",
    "translationMemories": [
        {
            "languagePairId": "EngGer_AutoAdaptive_SRV_TNM",
            "filename": "",
            "uploadedBy": "jsmith@example.com",
            "uploadTime": "2018-06-21 19:03:31.799810031Z",
            "tuCount": 23901,
            "uuid": "205cb9b9-f72b-42b6-bbf2-824aa15c4978",
            "isTestData": false
        }
    ],
    "desiredDeployedTrainingJob": "06f0be27-96f0-4961-a630-49372f21f497",
    "hostsToDeployTo": [
        "controller-host"
    ]
}

Retrieve auto adaptation information about the language pair

HTTP Request

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

Path Parameters

Name	Type	Description
`languagePairId`	string	ID of the auto adaptive language pair template

Returns

Returns auto adaptation information on the language pair as an AutoAdaptiveLPTemplateEntry

Name	Type	Description
`languagePairId`	string	The language pair ID
`baselineLanguagePairId`	string	The current baseline language pair ID
`autoAdaptationEnabled`	boolean	Whether the language pair will be auto adapted regularly
`trainingHost`	string	The name of the host on which the language pair will be trained
`dictionaryChanges`	int	The number of logged dictionary entries modified with respect to the language pair. This number will increase with deletions.
`feedbackChanges`	int	The number of logged feedback entries modified with respect to the language pair. This number will increase with deletions.
`translationMemoryChanges`	int	The number of logged translation memory entries modified with respect to the language pair. This number will increase with deletions.
`dictionaryTrainingUnits`	int	The number of dictionary entries that will be included on the next automated training job
`feedbackTrainingUnits`	int	The number of feedback entries that will be included on the next automated training job
`translationMemoryTrainingUnits`	int	The number of translation memory entries that will be included on the next automated training job
`translationMemories`	array of `AutoAdaptiveLPTemplateEntryTMs`	The uploaded training and test translation memories
`useUserProvidedTestData`	boolean	If true, training will primarily use test data supplied for bleu scoring
`desiredDeployedTrainingJob`	string	The ID of the training job that we want deployed
`hostsToDeployTo`	array of strings	A list of hostnames to deploy the created adapted LPs to

Create an auto adaptive language pair template

curl "https://controller-host:8001/api/v2/adapted-language-pairs/auto" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d autoAdaptationEnabled="true" \
    -d baselineLanguagePairId="EngFra_Generic_SRV_TNMV_8_4_x_1" \
    -d hostsToDeployTo="controller-host" \
    -d trainingHost="controller-host"

{
    "languagePairId": "EngGer_AutoAdaptive_SRV_TNM",
    "baselineLanguagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
    "autoAdaptationEnabled": true,
    "useUserProvidedTestData": false,
    "adaptationMode": "balanced",
    "dictionaryChanges": 492,
    "feedbackChanges": 392,
    "translationMemoryChanges": 17,
    "dictionaryTrainingUnits": 0,
    "feedbackTrainingUnits": 0,
    "translationMemoryTrainingUnits": 0,
    "trainingHost": "controller-host",
    "translationMemories": [
        {
            "languagePairId": "EngGer_AutoAdaptive_SRV_TNM",
            "filename": "",
            "uploadedBy": "jsmith@example.com",
            "uploadTime": "2018-06-21 19:03:31.799810031Z",
            "tuCount": 23901,
            "uuid": "205cb9b9-f72b-42b6-bbf2-824aa15c4978",
            "isTestData": false
        }
    ],
    "desiredDeployedTrainingJob": "06f0be27-96f0-4961-a630-49372f21f497",
    "hostsToDeployTo": [
        "controller-host"
    ]
}

Create an auto adaptive language pair template

HTTP Request

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

Request Parameters

Name	Type	Description	Default Value
`baselineLanguagePairId`	string	The baseline language pair ID to use to train
`autoAdaptationEnabled` (optional)	boolean	Whether the language pair will be auto adapted regularly	`false`
`trainingHost`	string	The name of host the language pair will be trained on
`hostsToDeployTo` (optional)	string	Comma-separated list of hostnames to deploy created adapted LPs to
`useUserProvidedTestData` (optional)	boolean	If true, training will primarily use test data supplied for bleu scoring	`false`

Returns

Returns an auto adaptive language pair as an AutoAdaptiveLPTemplateEntry object

Update an auto adaptive language pair template

curl "https://controller-host:8001/api/v2/adapted-language-pairs/auto/EngGer_AutoAdaptive_SRV_TNM" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d autoAdaptationEnabled="true" \
    -d hostsToDeployTo="controller-host" \
    -d trainingHost="controller-host"

{
    "languagePairId": "EngGer_AutoAdaptive_SRV_TNM",
    "baselineLanguagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
    "autoAdaptationEnabled": true,
    "useUserProvidedTestData": false,
    "adaptationMode": "balanced",
    "dictionaryChanges": 492,
    "feedbackChanges": 392,
    "translationMemoryChanges": 17,
    "dictionaryTrainingUnits": 0,
    "feedbackTrainingUnits": 0,
    "translationMemoryTrainingUnits": 0,
    "trainingHost": "controller-host",
    "translationMemories": [
        {
            "languagePairId": "EngGer_AutoAdaptive_SRV_TNM",
            "filename": "",
            "uploadedBy": "jsmith@example.com",
            "uploadTime": "2018-06-21 19:03:31.799810031Z",
            "tuCount": 23901,
            "uuid": "205cb9b9-f72b-42b6-bbf2-824aa15c4978",
            "isTestData": false
        }
    ],
    "desiredDeployedTrainingJob": "06f0be27-96f0-4961-a630-49372f21f497",
    "hostsToDeployTo": [
        "controller-host"
    ]
}

Update an auto adaptive language pair template

HTTP Request

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

Path Parameters

Name	Type	Description
`languagePairId`	string	ID of the auto adaptive language pair template

Request Parameters

Name	Type	Description	Default Value
`trainingHost` (optional)	string	The name of host the language pair will be trained on
`hostsToDeployTo` (optional)	string	Comma-separated list of hostnames to deploy created adapted LPs to
`useUserProvidedTestData` (optional)	boolean	If true, training will primarily use test data supplied for bleu scoring	`false`
`autoAdaptationEnabled` (optional)	boolean	Whether the language pair will be auto adapted regularly	`false`

Returns

Returns an auto adaptive language pair as an AutoAdaptiveLPTemplateEntry object

Delete an auto adaptive language pair template

curl "https://controller-host:8001/api/v2/adapted-language-pairs/auto/EngGer_AutoAdaptive_SRV_TNM" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "languagePairId": "EngGer_AutoAdaptive_SRV_TNM",
    "baselineLanguagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
    "autoAdaptationEnabled": true,
    "useUserProvidedTestData": false,
    "adaptationMode": "balanced",
    "dictionaryChanges": 492,
    "feedbackChanges": 392,
    "translationMemoryChanges": 17,
    "dictionaryTrainingUnits": 0,
    "feedbackTrainingUnits": 0,
    "translationMemoryTrainingUnits": 0,
    "trainingHost": "controller-host",
    "translationMemories": [
        {
            "languagePairId": "EngGer_AutoAdaptive_SRV_TNM",
            "filename": "",
            "uploadedBy": "jsmith@example.com",
            "uploadTime": "2018-06-21 19:03:31.799810031Z",
            "tuCount": 23901,
            "uuid": "205cb9b9-f72b-42b6-bbf2-824aa15c4978",
            "isTestData": false
        }
    ],
    "desiredDeployedTrainingJob": "06f0be27-96f0-4961-a630-49372f21f497",
    "hostsToDeployTo": [
        "controller-host"
    ]
}

Delete an auto adaptive language pair template

HTTP Request

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

Path Parameters

Name	Type	Description
`languagePairId`	string	ID of the auto adaptive language pair template

Returns

Returns an auto adaptive language pair as an AutoAdaptiveLPTemplateEntry object

Upload a translation memory to an auto adaptive language pair template

curl "https://controller-host:8001/api/v2/adapted-language-pairs/EngFra_Generic_SRV_TNMV_8_4_x_1/data" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d isTestData="true" \
    -d translationMemory="@<file>"

{
    "languagePairId": "EngGer_AutoAdaptive_SRV_TNM",
    "filename": "",
    "uploadedBy": "jsmith@example.com",
    "uploadTime": "2018-06-21 19:03:31.799810031Z",
    "tuCount": 23901,
    "uuid": "205cb9b9-f72b-42b6-bbf2-824aa15c4978",
    "isTestData": false
}

Upload a translation memory to be used during auto adaptation for the given language pair

HTTP Request

POST /api/v2/adapted-language-pairs/{languagePairId}/data

Path Parameters

Name	Type	Description
`languagePairId`	string	ID of baseline language pair

Request Parameters

Name	Type	Description	Default Value
`isTestData` (optional)	boolean	Whether the uploaded document is considered test data (true) or training data (false)	`false`
`translationMemory`	file	TMX document to use for training or testing the language pair

Returns

Returns an auto adaptive language pair translation memory

Name	Type	Description
`languagePairId`	string	The language pair ID
`uploadedBy`	string	The user that uploaded the translation memory
`uploadedTime`	string	The time that the translation memory was uploaded
`tuCount`	int	The total number of translation units contained within the translation memory
`uuid`	string	The unique identifier of the translation memory
`filename`	string	The name of the translation memory file
`isTestData`	boolean	Whether the uploaded document is considered test data (true) or training data (false)

Update a translation memory of an auto adaptive language pair template

curl "https://controller-host:8001/api/v2/adapted-language-pairs/EngFra_Generic_SRV_TNMV_8_4_x_1/data/205cb9b9-f72b-42b6-bbf2-824aa15c4978" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d isTestData="true"

{
    "languagePairId": "EngGer_AutoAdaptive_SRV_TNM",
    "filename": "",
    "uploadedBy": "jsmith@example.com",
    "uploadTime": "2018-06-21 19:03:31.799810031Z",
    "tuCount": 23901,
    "uuid": "205cb9b9-f72b-42b6-bbf2-824aa15c4978",
    "isTestData": false
}

Update a translation memory of an auto adaptative LP template for the given language pair

HTTP Request

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

Path Parameters

Name	Type	Description
`languagePairId`	string	ID of baseline language pair
`translationMemoryId`	string	ID of the translation memory

Request Parameters

Name	Type	Description	Default Value
`isTestData` (optional)	boolean	Whether the uploaded document is considered test data (true) or training data (false)	`false`

Returns

Returns the auto adaptive language pair translation memory that was deleted as an AutoAdaptiveLPTemplateEntryTM

Delete an auto adaptive translation memory

curl "https://controller-host:8001/api/v2/adapted-language-pairs/EngFra_Generic_SRV_TNMV_8_4_x_1/data/205cb9b9-f72b-42b6-bbf2-824aa15c4978" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "languagePairId": "EngGer_AutoAdaptive_SRV_TNM",
    "filename": "",
    "uploadedBy": "jsmith@example.com",
    "uploadTime": "2018-06-21 19:03:31.799810031Z",
    "tuCount": 23901,
    "uuid": "205cb9b9-f72b-42b6-bbf2-824aa15c4978",
    "isTestData": false
}

Delete a translation memory associated with an auto adaptive language pair template

HTTP Request

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

Path Parameters

Name	Type	Description
`languagePairId`	string	ID of baseline language pair
`translationMemoryId`	string	ID of the translation memory

Returns

Returns the auto adaptive language pair translation memory that was deleted as an AutoAdaptiveLPTemplateEntryTM

System

Retrieve Edge installation information

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

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

Retrieve information about the currently installed version of Edge

HTTP Request

GET /api/v2/system/info

Returns

Returns system information about the currently installed version of Edge as an EdgeInfo object with the following attributes:

Name	Type	Description
`etsVersion`	string	The currently installed version of Edge
`etsBuild`	string	The build GUID of the currently installed version of Edge
`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.
`→ autoChainManagement`	string	'enabled’ if automatic translation chain management is turned on, 'disabled’ otherwise.

Retrieve input size limits

curl "https://controller-host:8001/api/v2/system/input-size-limits" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "languageDetectionMaxSizeInMB": 100,
    "translationMaxSizeInMB": 100,
    "dictionaryMaxSizeInMB": 100,
    "trainingDataMaxSizeInMB": 3000,
    "themesMaxSizeInMB": 20,
    "importFeedbackMaxSizeInMB": 100,
    "brandMaxSizeInMB": 50,
    "profilesMaxSizeInMB": 20,
    "transcriptionMaxSizeInMB": 200
}

Retrieve the current input size limits.

HTTP Request

GET /api/v2/system/input-size-limits

Returns

Returns input size limit configuration as InputSizeLimits object with the following attributes:

Name	Type	Description
`languageDetectionMaxSizeInMB`	string	Input file size limit (MB) for language detection
`translationMaxSizeInMB`	string	Input file size limit (MB) for translation
`dictionaryMaxSizeInMB`	string	Input file size limit (MB) for dictionary upload
`trainingDataMaxSizeInMB`	string	Input file size limit (MB) for training data
`themesMaxSizeInMB`	string	Input file size limit (MB) for themes upload
`importFeedbackMaxSizeInMB`	string	Input file size limit (MB) for feedback import
`brandMaxSizeInMB`	string	Input file size limit (MB) for brand upload
`profilesMaxSizeInMB`	string	Input file size limit (MB) for profiles import
`transcriptionMaxSizeInMB`	string	Input file size limit (MB) for transcription

Retrieve SMTP settings

curl "https://controller-host:8001/api/v2/system/smtp" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

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

Retrieve the current SMTP server configuration used to send emails to Language Weaver Edge 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
`sender`	string	Email address to appear in the sender field
`enabled`	boolean	Whether SMTP is enabled in Language Weaver Edge

Test SMTP settings

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

{
    "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
`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
`sender` (optional)	string	Email address to appear in the sender field

Returns

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

Name	Type	Description
`success`	boolean	Whether or not the test was successful

Update SMTP settings

curl "https://controller-host:8001/api/v2/system/smtp" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d enabled="true" \
    -d host="smtp.example.com" \
    -d password="password" \
    -d port="587" \
    -d username="admin" \
    --data-urlencode sender="notifications@example.com"

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

Change the SMTP server configuration used to send emails to Language Weaver Edge users.

HTTP Request

PUT /api/v2/system/smtp

Request Parameters

Name	Type	Description
`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
`sender` (optional)	string	Email address to appear in the sender field
`enabled` (optional)	boolean	Whether SMTP is enabled in Language Weaver Edge

Returns

Returns the updated SMTP settings as an SmtpSettings object.

Retrieve LDAP settings

curl "https://controller-host:8001/api/v2/system/ldap" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "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,
        "roleGroups": [],
        "attributes": {
            "name": "cn",
            "email": "mail"
        }
    },
    "syncIntervalInSecs": 3600,
    "resetRolesOnLogin": false,
    "enabled": false
}

Retrieve the current LDAP configuration used for authenticating Language Weaver Edge 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`	boolean	Whether LDAP server uses TLS
`→ insecureSkipVerify`	boolean	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 Language Weaver Edge, 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 Language Weaver Edge, 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 Language Weaver Edge contacts the LDAP server to verify user is still active
`resetRolesOnLogin`	boolean	If true, the roles of the user are reset and re-computed after each login, using the information from the LDAP server
`enabled`	boolean	Whether LDAP is enabled in Language Weaver Edge

Test LDAP settings

curl "https://controller-host:8001/api/v2/system/ldap/test" \
    -X PUT \
    -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=edgeuser.group,OU=acme,DC=example,DC=com"],"adminGroups":["CN=edgeadmin.group,OU=acme,DC=example,DC=com"],"roleGroups":[{"role":"admin","groups":["CN=edgeadmin.group,OU=acme,DC=example,DC=com"]},{"role":"linguist","groups":["CN=edgelinguist.group,OU=acme,DC=example,DC=com"]},{"role":"translator","groups":["CN=edgetranslator.group,OU=acme,DC=example,DC=com"]}],"attributes":{"name":"cn","email":"mail"}},"syncIntervalInSecs":3600,"resetRolesOnLogin":false,"enabled":true},"username":"jsmith@example.com","password":"abcd1234"}'

{
    "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": "login",
            "description": "full login: 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: role group membership",
            "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
`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

curl "https://controller-host:8001/api/v2/system/ldap" \
    -X PUT \
    -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=edgeuser.group,OU=acme,DC=example,DC=com"],"adminGroups":["CN=edgeadmin.group,OU=acme,DC=example,DC=com"],"roleGroups":[{"role":"admin","groups":["CN=edgeadmin.group,OU=acme,DC=example,DC=com"]},{"role":"linguist","groups":["CN=edgelinguist.group,OU=acme,DC=example,DC=com"]},{"role":"translator","groups":["CN=edgetranslator.group,OU=acme,DC=example,DC=com"]}],"attributes":{"name":"cn","email":"mail"}},"syncIntervalInSecs":3600,"resetRolesOnLogin":false,"enabled":true},"username":"jsmith@example.com","password":"abcd1234"}'

{
    "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=edgeuser.group,OU=acme,DC=example,DC=com"
        ],
        "adminGroups": [
            "CN=edgeadmin.group,OU=acme,DC=example,DC=com"
        ],
        "roleGroups": [
            {
                "role": "admin",
                "groups": [
                    "CN=edgeadmin.group,OU=acme,DC=example,DC=com"
                ]
            },
            {
                "role": "linguist",
                "groups": [
                    "CN=edgelinguist.group,OU=acme,DC=example,DC=com"
                ]
            },
            {
                "role": "translator",
                "groups": [
                    "CN=edgetranslator.group,OU=acme,DC=example,DC=com"
                ]
            }
        ],
        "attributes": {
            "name": "cn",
            "email": "mail"
        }
    },
    "syncIntervalInSecs": 3600,
    "resetRolesOnLogin": false,
    "enabled": true
}

Change the LDAP configuration used for authenticating Language Weaver Edge 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

curl "https://controller-host:8001/api/v2/system/saml/available" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "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`	boolean	Whether SAML available (i.e. configured and enabled)

Retrieve SAML settings

curl "https://controller-host:8001/api/v2/system/saml" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "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,
        "attributes": {
            "name": "",
            "email": ""
        }
    },
    "resetRolesOnLogin": false,
    "loginGroups": [
        "some-group-id"
    ],
    "roleGroups": null,
    "loginRoles": null,
    "roles": 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`	boolean	Whether SAML is enabled in Language Weaver Edge
`identityProvider`	object	Identity Provider configuration (expanded below)
`→ metadataUrl`	string	URL used to retrieve the Identity Provider metadata
`→ insecureSkipVerify`	boolean	If true, Language Weaver Edge 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`	boolean	Ask the Identity Provider to always require authentication (i.e. prompt the user for a password), even if the session is still available
`resetRolesOnLogin`	boolean	If true, the roles of the user are reset and re-computed after each login, using the information from the Identity Provider
`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

curl "https://controller-host:8001/api/v2/system/saml" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d enabled="true" \
    -d identityProvider.attributes.email="email" \
    -d identityProvider.attributes.name="name" \
    -d identityProvider.azure.applicationId="1234-1234-1234-9999" \
    -d identityProvider.forceAuthentication="false" \
    -d loginGroup="some-group-id" \
    --data-urlencode identityProvider.metadataUrl="https://login.microsoftonline.com/df02c2f8-e418-484f-8bd6-c7f2e154f300/federationmetadata/2007-06/federationmetadata.xml" \
    --data-urlencode role="admin=adminRole" \
    --data-urlencode role="admin=otherAdminRole" \
    --data-urlencode role="linguist=linguistRole" \
    --data-urlencode roleGroup="admin=CN=edgeadmin.group,OU=acme,DC=example,DC=com" \
    --data-urlencode roleGroup="admin=CN=otheredgeadmin.group,OU=acme,DC=example,DC=com" \
    --data-urlencode roleGroup="linguist=CN=edgelinguist.group,OU=acme,DC=example,DC=com"

{
    "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,
        "attributes": {
            "name": "name",
            "email": "email"
        }
    },
    "resetRolesOnLogin": false,
    "loginGroups": [
        "some-group-id"
    ],
    "roleGroups": null,
    "loginRoles": null,
    "roles": 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)	boolean	Whether SAML is enabled	`false`
`identityProvider.azure.applicationId` (optional)	string	Azure only: Application ID on the Azure side
`identityProvider.metadataUrl`	string	URL used to retrieve Identity Provider metadata. Required when SAML is enabled.
`identityProvider.insecureSkipVerify` (optional)	boolean	If true, Language Weaver Edge will skip the verification of the certifiate supplied by the Identity Provider	`false`
`identityProvider.forceAuthentication` (optional)	boolean	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	`false`
`identityProvider.attributes.name` (optional)	string	After login, the Identity Provider sends the user name in an attribute. This field allows overriding the name of the attribute. Overriding is usually not required.
`identityProvider.attributes.email` (optional)	string	After login, the Identity Provider sends the user email in an attribute. This field allows overriding the name of the attribute. Overriding is usually not required.
`resetRolesOnLogin` (optional)	boolean	If true, the roles of the user are reset and re-computed after each login, using the information from the Identity Provider.	`false`
`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.
`roleGroup` (optional)	string array	If not empty, the user is required to be a member of one of these groups in order to be a member of the corresponding role. 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.
`role` (optional)	string array	If not empty, the user is required to have the SAML role in order to be a member of the corresponding LWE role. The Identity Provider must be configured to send the roles as claims. This parameter can be repeated if there is more than one role.

Returns

Returns the updated SAML settings as an object.

Retrieve proxy settings

curl "https://controller-host:8001/api/v2/system/proxy" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "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`	boolean	Whether proxy is enabled in Language Weaver Edge

Update proxy settings

curl "https://controller-host:8001/api/v2/system/proxy" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d enabled="true" \
    -d host="proxy2.example.com" \
    -d password="password" \
    -d port="567" \
    -d username="admin"

{
    "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)	boolean	Whether proxy is enabled in Language Weaver Edge	`false`

Returns

Returns the updated proxy settings as a ProxySettings object.

Retrieve TLS settings

curl "https://controller-host:8001/api/v2/system/tls" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "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 Edge 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`	boolean	Whether TLS is enabled in Language Weaver Edge
`minimumVersion`	string	The minimum version of TLS to use (`1.1` or `1.2`)
`maximumVersion`	string	The maximum version of TLS to use (`1.1` or `1.2`)
`certificatePath`	string	Path to TLS certificate
`privateKeyPath`	string	Path to TLS private key

Update TLS settings

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

{
    "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 Edge services are served. Note: You must manually restart Language Weaver Edge Manager on the Controller host for these changes to take effect.

HTTP Request

PUT /api/v2/system/tls

Request Parameters

Name	Type	Description	Default Value
`enabled` (optional)	boolean	Whether TLS is enabled in Language Weaver Edge
`minimumVersion` (optional)	string	The minimum version of TLS to use (`1.1`, `1.2` or `1.3`)	`1.2`
`maximumVersion` (optional)	string	The maximum version of TLS to use (`1.1`, `1.2` or `1.3`)
`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

curl "https://controller-host:8001/api/v2/system/edge-cloud" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "host": "https://api.languageweaver.com",
    "port": 443,
    "clientId": "7A30s2",
    "enabled": true,
    "allowedLpIds": [
        "engfra_generic",
        "araeng_generic"
    ],
    "disallowedLpIds": [
        "engfra_adapted",
        "araeng_adapted"
    ]
}

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`	boolean	Whether Edge Cloud is enabled in Language Weaver Edge
`allowedLpIds`	string array	List of allowed Language Weaver language pair names available for translation
`disallowedLpIds`	string array	List of disallowed Language Weaver language pair names not available for translation

Test Edge Cloud settings

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

{
    "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
`host`	string	Host of MT Cloud server
`port`	string	Port of MT Cloud server
`clientId`	string	Client ID to login to MT Cloud server
`clientSecret` (optional)	string	Client secret to login to MT Cloud server

Returns

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

Name	Type	Description
`success`	boolean	Whether or not the test was successful

Update Edge Cloud settings

curl "https://controller-host:8001/api/v2/system/edge-cloud" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d allowedLpId="engfra_generic" \
    -d clientId="7A30s2" \
    -d clientSecret="AbC_123" \
    -d disallowedLpId="fraeng_generic" \
    -d enabled="true" \
    -d port="443" \
    --data-urlencode host="https://api.languageweaver.com"

{
    "host": "https://api.languageweaver.com",
    "port": 443,
    "clientId": "7A30s2",
    "enabled": true,
    "allowedLpIds": [
        "engfra_generic"
    ],
    "disallowedLpIds": [
        "fraeng_generic"
    ]
}

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	`existing configured value`
`port` (optional)	string	Port of MT Cloud server	`existing configured value`
`clientId` (optional)	string	Client ID to login to MT Cloud server	`existing configured value`
`clientSecret` (optional)	string	Client secret to login to MT Cloud server	`existing configured value`
`enabled` (optional)	boolean	Whether Edge Cloud is enabled in Language Weaver Edge	`existing configured value`
`allowedLpId` (optional)	string array	List of allowed Language Weaver language pair names available for translation	`existing configured value`
`disallowedLpId` (optional)	string array	List of disallowed Language Weaver language pair names not available for translation	`existing configured value`

Returns

Returns the updated Edge Cloud settings as an EdgeCloudConfig object.

Retrieve reports settings

curl "https://controller-host:8001/api/v2/system/reports" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "translations": {
        "enabled": true,
        "purgeMaxAgeInSecs": 8640000,
        "dbAddIntervalInSecs": 1,
        "maxQueueSize": 200,
        "maxBufferSize": 500
    }
}

Retrieve the reports configuration.

HTTP Request

GET /api/v2/system/reports

Returns

Returns the reports configuration object with the database path excluded.

Update the reports settings

curl "https://controller-host:8001/api/v2/system/reports/translations" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d dbAddIntervalInSecs="1" \
    -d enabled="true" \
    -d maxBufferSize="500" \
    -d maxQueueSize="200" \
    -d purgeMaxAgeInSecs="8640000"

{
    "enabled": true,
    "purgeMaxAgeInSecs": 8640000,
    "dbAddIntervalInSecs": 1,
    "maxQueueSize": 200,
    "maxBufferSize": 500
}

Change the reports configuration.

HTTP Request

PUT /api/v2/system/reports/translations

Request Parameters

Name	Type	Description	Default Value
`enabled` (optional)	boolean	Whether translations will be added to the reports database	`false`
`purgeMaxAgeInSecs` (optional)	int	Maximum age of translations in the reports database kept during daily purges	`8640000`
`dbAddIntervalInSecs` (optional)	int	Interval of how often queued translations are added to the reports database	`1`
`maxQueueSize` (optional)	int	Maximum size before queued translations are added to the reports database	`200`
`maxBufferSize` (optional)	int	Maximum buffer size to store translations before queueing	`500`

Returns

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

Retrieve Public URL settings

curl "https://controller-host:8001/api/v2/system/public-url" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "publicUrl": "https://public-host:8001",
    "privateApiUrl": "https://controller-host:8001",
    "privateWebUrl": "https://controller-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 Edge 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 Edge instance from internal networks.
`privateWebUrl`	string	The web URL that is used to access this Edge instance from internal networks.

Update Public URL settings

curl "https://controller-host:8001/api/v2/system/public-url" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    --data-urlencode publicUrl="https://public-host:8001"

{
    "publicUrl": "https://public-host:8001",
    "privateApiUrl": "https://controller-host:8001",
    "privateWebUrl": "https://controller-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 front-end HTTP settings

curl "https://controller-host:8001/api/v2/system/http-headers" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "headers": [
        "Header1: Value1",
        "Header2: Value2"
    ]
}

Retrieves HTTP settings for the Web user interface.

HTTP Request

GET /api/v2/system/http-headers

Returns

Returns the HTTP settings as a FrontEndHTTP object with the following attributes:

Name	Type	Description
`Headers`	string array	A list of additional HTTP headers the server will use for every response.

Update front-end HTTP settings

curl "https://controller-host:8001/api/v2/system/http-headers" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    --data-urlencode headers="Header1: Value1" \
    --data-urlencode headers="Header2: Value2"

{
    "headers": [
        "Header1: Value1",
        "Header2: Value2"
    ]
}

Updates HTTP settings for the Web user interface.

HTTP Request

PUT /api/v2/system/http-headers

Request Parameters

Name	Type	Description	Default Value
`headers`	string array	HTTP Headers to add

Returns

Returns the HTTP settings as a FrontEndHTTP object.

Retrieve translation settings

curl "https://controller-host:8001/api/v2/system/translation" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "disableInstantTranslation": false,
    "disableLanguageDetection": false,
    "sourceCharacterLimit": {
        "enabled": false,
        "max": 0
    },
    "watermark": {
        "enabled": false
    },
    "alternativeTranslations": {
        "enabled": false,
        "count": 0
    },
    "pdfConversion": {
        "pdfOutput": {
            "restriction": {
                "enabled": true,
                "permissions": [
                    "Changes",
                    "CopyingOfContent"
                ]
            }
        }
    }
}

Retrieve translation settings details

HTTP Request

GET /api/v2/system/translation

Returns

Returns the updated translation settings configuration as a TranslationSettingsConfig object. (expanded below)

Name	Type	Description
`disableInstantTranslation`	boolean	Stop translating user input continuously as user types in the text field on the Translate web page
`disableLanguageDetection`	boolean	Disallow users from using the language detection feature on the Translate web page
`sourceCharacterLimit`	object	Description of sourceCharacterLimit settings used for the Translate page (expanded below)
`→ enabled`	boolean	Whether limiting the number of source characters is enabled
`→ max`	int	Maximum number of source characters to allow
`watermark`	object	Description of watermark settings options (expanded below)
`→ enabled`	boolean	Whether `watermark → text` will be added to translations
`→ text`	string	Text to add as a watermark to translations
`→ backgroundEnabled`	boolean	Whether `watermark → text` will be added to background of MS Word document translations
`pdfConversion`	object	Description of pdfConversion settings used for PDF document translations (expanded below)
`→ pdfOutput`	object	Description of pdfOutput settings used for PDF document translations (expanded below)
`→ → restriction`	object	Description of restriction settings used for PDF document translations (expanded below)
`→ → → enabled`	boolean	Whether `pdfOutput → restriction → permissions` are applied to generated PDF document
`→ → → permissions`	array of strings	An array of permissions to restrict for generated PDF document (see table of restricted permissions for PDF output)

Restricted Permissions For PDF Output

Name	Description
`Changes`	Restrict filling of form fields, commenting, signing and creating of template pages
`CopyingOfContent`	Restrict content copying
`Printing`	Restrict printing
`TextAccessForAccessibilityTools`	Restrict accessibility tools from reading content

Update translation settings

curl "https://controller-host:8001/api/v2/system/translation" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d alternativeTranslationsCount="3" \
    -d disableInstantTranslation="false" \
    -d disableLanguageDetection="false" \
    -d enableAlternativeTranslations="true" \
    -d enableTranslationWatermark="true" \
    -d enableTranslationWatermarkBackground="true" \
    -d pdfOutputRestrictionEnabled="true" \
    -d pdfOutputRestrictionPassword="Password" \
    -d pdfOutputRestrictionPermission="Changes" \
    -d sourceCharacterLimitEnabled="true" \
    -d sourceCharacterLimitMax="5000" \
    -d translationWatermarkText="RWS"

{
    "disableInstantTranslation": false,
    "disableLanguageDetection": false,
    "sourceCharacterLimit": {
        "enabled": true,
        "max": 5000
    },
    "watermark": {
        "enabled": true,
        "text": "RWS",
        "backgroundEnabled": true
    },
    "alternativeTranslations": {
        "enabled": true,
        "count": 3
    },
    "pdfConversion": {
        "pdfOutput": {
            "restriction": {
                "enabled": true,
                "permissions": [
                    "Changes",
                    "CopyingOfContent"
                ]
            }
        }
    }
}

Update translation settings details

HTTP Request

PUT /api/v2/system/translation

Request Parameters

Name	Type	Description	Default Value
`disableInstantTranslation` (optional)	boolean	Stop translating user input continuously as user types in the text field on the Translate web page
`disableLanguageDetection` (optional)	boolean	Disallow users from using the language detection feature on the Translate web page
`sourceCharacterLimitEnabled` (optional)	boolean	Whether limiting the number of source characters is enabled
`sourceCharacterLimitMax` (optional)	int	Maximum number of source characters to allow	`5000`
`enableTranslationWatermark` (optional)	boolean	Whether `watermarkText` will be added to translations
`translationWatermarkText` (optional)	string	Text to add as a watermark to translations
`enableTranslationWatermarkBackground` (optional)	boolean	Whether `watermarkText` will be added to background of MS Word document translations
`enableAlternativeTranslations` (optional)	boolean	Whether translation jobs should return translation alternatives	`true`
`alternativeTranslationsCount` (optional)	string	The number of alternative translations to return. The value must be between 1 and 5	`3`
`pdfOutputRestrictionEnabled` (optional)	boolean	Whether `restrictedPermission` selections are applied to generated PDF document; if enabled without any restrictions, the `Changes`, `CopyingOfContent` and `Printing` restrictions will automatically be set
`pdfOutputRestrictionPermission` (optional)	string	A permission to restrict for the generated PDF document (see table of restricted permissions for PDF output); multiple restrictions can be specified
`pdfOutputRestrictionPassword` (optional)	string	Password used during restriction for the generated PDF document; Job-engines are restarted when modified

Returns

Returns the updated translation settings configuration as a TranslationSettingsConfig object.

Retrieve asynchronous translation purge configuration

curl "https://controller-host:8001/api/v2/system/translations/purge" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "maxAgeInSecs": 8640000,
    "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`	boolean	Whether translations will have their records regularly purged after they exceed their maximum age.

Update asynchronous translation purge configuration

curl "https://controller-host:8001/api/v2/system/translations/purge" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d enabled="false" \
    -d maxAgeInSecs="8640000"

{
    "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)	boolean	Whether translations will have their records regularly purged after they exceed their maximum age.	`false`

Returns

Returns the updated translation purge configuration as a TranslationPurgeConfig object.

Retrieve asynchronous edited translation purge configuration

curl "https://controller-host:8001/api/v2/system/translations/edited-purge" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

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

Retrieve the asynchronous edited translation purge configuration.

HTTP Request

GET /api/v2/system/translations/edited-purge

Returns

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

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

Update asynchronous edited translation purge configuration

curl "https://controller-host:8001/api/v2/system/translations/edited-purge" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d enabled="false" \
    -d maxAgeInSecs="11232000"

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

Change the asynchronous edited translation purge configuration.

HTTP Request

PUT /api/v2/system/translations/edited-purge

Request Parameters

Name	Type	Description	Default Value
`maxAgeInSecs` (optional)	int	Maximum age an edited translation is kept before being purged. The age begins when the translation is first edited.	`11232000`
`enabled` (optional)	boolean	Whether translations will have their records regularly purged after they exceed their maximum age.	`false`

Returns

Returns the updated edited translation purge configuration as a TranslationPurgeConfig object.

Retrieve translation chain settings

curl "https://controller-host:8001/api/v2/system/translation-chains" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "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`	boolean	Whether the system automatically creates and disposes of translation chains as the necessary resources become available/unavailable.
`enabled`	boolean	Whether translation chains are enabled on the system.

Update translation chain settings

curl "https://controller-host:8001/api/v2/system/translation-chains" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d autoManage="true" \
    -d enabled="true"

{
    "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)	boolean	Whether the system automatically creates and disposes of translation chains as the necessary resources become available/unavailable.
`enabled` (optional)	boolean	Whether translation chains are enabled on the system.

Returns

Returns the current settings as a ChainManagementSettings object.

Retrieve language detection settings

curl "https://controller-host:8001/api/v2/system/language-detections" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "timeoutInSecs": 300,
    "filter": "sdl"
}

Retrieve the current status of system-wide language detection settings.

HTTP Request

GET /api/v2/system/language-detections

Returns

Returns the current settings as a LanguageDetectionConfig object with the following attributes:

Name	Type	Description
`filter`	string	Filter type set for language detections, including auto-detect translations.
`timeoutInSecs`	int	The duration that the system will wait for an in-progress language detection request.

Update language detection settings

curl "https://controller-host:8001/api/v2/system/language-detections" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d filter="sdl"

{
    "timeoutInSecs": 300,
    "filter": "sdl"
}

Update system-wide settings for language detection

HTTP Request

PUT /api/v2/system/language-detections

Request Parameters

Name	Type	Description	Default Value
`filter` (optional)	string	Filter type to use for all language detection requests. Choices: `running` to only display detected languages that are the source language of a running translation engine, `installed` to only display languages that are the source language of an installed language pair, `sdl` to only display Language Weaver-supported languages, or `all` to display all detected languages.
`timeoutInSecs` (optional)	int	The duration that the system will wait for an in-progress language detection request.	`existing configured value`

Returns

Returns the current settings as a LanguageDetectionConfig object.

Retrieve language pair adaptation settings

curl "https://controller-host:8001/api/v2/system/language-pair-adaptation" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "languagePairsDir": "/opt/sdl/ets/data/adapted-lps",
    "minimumTrainingUnits": 1000,
    "minimumTestUnits": 50,
    "minimumDiskSpaceRequiredInMB": 10000,
    "maximumSegmentsToParse": 0,
    "dataCleaner": {
        "enabled": true,
        "withTestData": true,
        "timeoutInSecs": 600
    }
}

Retrieve the system-wide settings for language pair adaptation.

HTTP Request

GET /api/v2/system/language-pair-adaptation

Returns

Returns language pair adaptation settings as an LanguagePairTrainerConfig object with the following attributes:

Name	Type	Description
`languagePairsDir`	string	Directory to store adapted language pairs
`minimumTrainingUnits`	int	Minimum training units for adaptation
`minimumTestUnits`	int	Minimum test units for adaptation
`minimumDiskSpaceRequiredInMB`	int	Minimum disk space required in MB for adapation
`dataCleaner`	object	`DataCleanerConfig` object (expanded below)

Language Pair Adaptation Data Cleaner Config

Name	Type	Description
`enabled`	boolean	Whether data cleaning is enabled
`withTestData`	boolean	Whether data cleaning of test dataset is enabled
`path`	string	Optional path to data cleaner
`configPath`	string	Path to optional data cleaner config file
`arguments`	string	Optional data cleaner arguments
`timeoutInSecs`	int	Timeout for data cleaning in seconds
`pipeline`	string	Pipeline to use for data cleaning

Update language pair adaptation settings

curl "https://controller-host:8001/api/v2/system/language-pair-adaptation" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d dataCleanerEnabled="true" \
    -d dataCleanerTimeoutInSecs="200" \
    -d dataCleanerWithTestData="true" \
    -d maximumSegmentsToParse="30000000" \
    -d minimumDiskSpaceRequiredInMB="15000" \
    -d minimumTestUnits="100" \
    -d minimumTrainingUnits="2000" \
    --data-urlencode languagePairsDir="/opt/sdl/ets/data/adaptation"

{
    "languagePairsDir": "/opt/sdl/ets/data/adaptation",
    "minimumTrainingUnits": 2000,
    "minimumTestUnits": 100,
    "minimumDiskSpaceRequiredInMB": 15000,
    "maximumSegmentsToParse": 30000000,
    "dataCleaner": {
        "enabled": true,
        "withTestData": true,
        "timeoutInSecs": 600
    }
}

Update the system-wide settings for language pair adaptation.

HTTP Request

PUT /api/v2/system/language-pair-adaptation

Request Parameters

Name	Type	Description	Default Value
`languagePairsDir` (optional)	string	Directory to store adapted language pairs	`existing configured value`
`minimumTrainingUnits` (optional)	int	Minimum training units for adaptation	`existing configured value`
`minimumTestUnits` (optional)	int	Minimum test units for adaptation	`existing configured value`
`minimumDiskSpaceRequiredInMB` (optional)	int	Minimum disk space required in MB for adapation	`existing configured value`
`maximumSegmentsToParse` (optional)	int	Maximum number of segments to parse for adapation across all sources	`existing configured value`
`dataCleanerEnabled` (optional)	boolean	Whether data cleaning is enabled	`existing configured value`
`dataCleanerWithTestData` (optional)	boolean	Whether data cleaning of test data is enabled	`existing configured value`
`dataCleanerPath` (optional)	string	Path to data cleaner	`existing configured value`
`dataCleanerArguments` (optional)	string	Extra arguments to pass to data cleaner	`existing configured value`
`dataCleanerTimeoutInSecs` (optional)	int	Timeout for data cleaning in seconds	`600`
`dataCleanerPipeline` (optional)	string	Pipeline to use for data cleaning; available pipelines: default, regex, defaultAndRegex	`default`

Returns

Returns the updated language pair adaptation settings as an LanguagePairTrainerConfig object.

Retrieve themes settings

curl "https://controller-host:8001/api/v2/system/themes" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "enabled": true
}

Retrieve the themes configuration.

HTTP Request

GET /api/v2/system/themes

Returns

Returns the themes configuration object.

Update the themes settings

curl "https://controller-host:8001/api/v2/system/themes" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d enabled="true"

{
    "enabled": true
}

Change the themes configuration.

HTTP Request

PUT /api/v2/system/themes

Request Parameters

Name	Type	Description	Default Value
`enabled` (optional)	boolean	Whether custom theme will be enabled	`existing configured value`

Returns

Returns the updated themes configuration object.

Retrieve profiles settings

curl "https://controller-host:8001/api/v2/system/profiles" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "enabled": false
}

Retrieve the profiles configuration.

HTTP Request

GET /api/v2/system/profiles

Returns

Returns the ProfilesSettings object with the following attributes:

Name	Type	Description
`enabled`	boolean	Whether the profiles are used during Edge translation jobs

Update the profiles settings

curl "https://controller-host:8001/api/v2/system/profiles" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d enabled="true"

{
    "enabled": true
}

Change the profiles configuration.

HTTP Request

PUT /api/v2/system/profiles

Request Parameters

Name	Type	Description	Default Value
`enabled` (optional)	boolean	Whether the profiles are used during Edge translation jobs	`false`

Returns

Returns the updated settings as a ProfilesSettings object.

Retrieve brands settings

curl "https://controller-host:8001/api/v2/system/brands" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "enabled": true
}

Retrieve the brands configuration.

HTTP Request

GET /api/v2/system/brands

Returns

Returns the brands configuration object.

Update the brands settings

curl "https://controller-host:8001/api/v2/system/brands" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d enabled="true"

{
    "enabled": true
}

Change the brands configuration.

HTTP Request

PUT /api/v2/system/brands

Request Parameters

Name	Type	Description	Default Value
`enabled` (optional)	boolean	Whether brands will be enabled	`existing configured value`

Returns

Returns the updated brands configuration object.

Retrieve the webhooks settings

curl "https://controller-host:8001/api/v2/system/webhooks" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "username": "jsmith@example.com",
    "purgeMaxAgeInSecs": 8640000,
    "enabled": true,
    "authenticationType": "Basic"
}

Retrieve the webhooks configuration.

HTTP Request

GET /api/v2/system/webhooks

Returns

Returns the webhooks configuration object.

Update the webhooks settings

curl "https://controller-host:8001/api/v2/system/webhooks" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    --data-urlencode username="jsmith@example.com"

{
    "username": "jsmith@example.com",
    "purgeMaxAgeInSecs": 8640000,
    "enabled": true,
    "authenticationType": "Basic"
}

Update the webhooks configuration.

HTTP Request

PUT /api/v2/system/webhooks

Request Parameters

Name	Type	Description	Default Value
`username` (optional)	string	The username to pass with each webhook via basic authentication	`existing configured value`
`password` (optional)	string	The password to pass with each webhook via basic authentication	`existing configured value`
`enabled` (optional)	string	Whether or not webhooks are enabled	`existing configured value`
`purgeMaxAgeInSecs` (optional)	int	Maximum age of webhook events kept during purges	`8640000`

Returns

Returns the webhooks configuration object.

Retrieve the labels settings

curl "https://controller-host:8001/api/v2/system/labels" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "enabled": true,
    "enforceForTranslation": false,
    "labelLengthLimit": 225,
    "maxLabelCount": 5000,
    "maxLabelsPerTranslation": 10,
    "preventMultiSelect": false
}

Retrieve the labels configuration.

HTTP Request

GET /api/v2/system/labels

Returns

Returns the labels configuration object.

Update the labels settings

curl "https://controller-host:8001/api/v2/system/labels" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "enabled": true,
    "enforceForTranslation": false,
    "labelLengthLimit": 225,
    "maxLabelCount": 5000,
    "maxLabelsPerTranslation": 10,
    "preventMultiSelect": false
}

Update the labels configuration.

HTTP Request

PUT /api/v2/system/labels

Request Parameters

Name	Type	Description	Default Value
`enabled` (optional)	string	Whether or not labels are enabled via the UI	`existing configured value`
`enforceForTranslation` (optional)	string	Whether or not labels are required for translation via the UI	`existing configured value`
`labelLengthLimit` (optional)	int	Maximum length of a label name	`existing configured value`
`maxLabelCount` (optional)	int	Maximum number of total labels	`5000`
`maxLabelsPerTranslation` (optional)	int	Maximum number of labels allowed per translation	`10`
`preventMultiSelect` (optional)	string	Prevent selection of multiple labels for translation via the UI	`existing configured value`

Returns

Returns the labels configuration object.

Retrieve the event logging settings

curl "https://controller-host:8001/api/v2/system/eventlog" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "enabled": true,
    "logFailedEvents": true,
    "routesToLog": [
        "/api/v2/system/eventlog",
        "/api/v2/users"
    ]
}

Retrieve the event logging configuration.

HTTP Request

GET /api/v2/system/eventlog

Returns

Returns the event logging settings as a EventLoggingConfig object.

Name	Type	Description
`enabled`	boolean	Whether event logging is enabled
`routesToLog`	array of strings	An array of the routes we would like to log. If it is simply ’[“all”]’ or empty, all routes will be logged.
`logFailedEvents`	boolean	Whether failed http events will be logged.

Update the event logging settings

curl "https://controller-host:8001/api/v2/system/eventlog" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d enabled="true" \
    -d logFailedEvents="true" \
    --data-urlencode routesToLog="/api/v2/system/eventlog" \
    --data-urlencode routesToLog="/api/v2/users"

{
    "enabled": true,
    "logFailedEvents": true,
    "routesToLog": [
        "/api/v2/system/eventlog",
        "/api/v2/users"
    ]
}

Update the event logging configuration.

HTTP Request

PUT /api/v2/system/eventlog

Request Parameters

Name	Type	Description	Default Value
`enabled` (optional)	boolean	Whether or not event logging is enabled	`existing configured value`
`routesToLog` (optional)	string	A route to enable event logging for. Multiple routeToLogs can be specified to add multiple routes. Specify “all” to log all routes.	`existing configured value`
`logFailedEvents` (optional)	boolean	Whether or not to log failed HTTP events	`existing configured value`

Returns

Returns the updated event logging settings as a EventLoggingConfig object

Update the auto adaptation settings

curl "https://controller-host:8001/api/v2/system/auto-adaptation" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d dictionariesEnabled="true" \
    -d enabled="true" \
    -d feedbackEnabled="true" \
    -d includePendingFeedback="false" \
    -d retryFailedTrainingIntervalInSecs="120" \
    -d threshold="1000" \
    -d translationMemoriesEnabled="false"

{
    "sources": {
        "translationMemories": {
            "enabled": false
        },
        "dictionaries": {
            "enabled": true
        },
        "feedback": {
            "enabled": true
        }
    },
    "enabled": true,
    "threshold": 1000,
    "successfulTrainingsToKeep": 3,
    "unsuccessfulTrainingsToKeep": 1,
    "includePendingFeedback": false,
    "gracePeriodInSecs": 0,
    "retryFailedTrainingIntervalInSecs": 120
}

Update the auto adaptation configuration.

HTTP Request

PUT /api/v2/system/auto-adaptation

Request Parameters

Name	Type	Description	Default Value
`enabled` (optional)	boolean	Whether overall auto adaptation is enabled	`existing configured value`
`threshold` (optional)	int	The overall threshold to trigger an adaptation	`existing configured value`
`includePendingFeedback` (optional)	boolean	Whether to include pending feedback in the gathered feedback data	`existing configured value`
`retryFailedTrainingIntervalInSecs` (optional)	int	Number of seconds to wait between failed trainings	`existing configured value`
`dictionariesEnabled` (optional)	boolean	Whether dictionaries are enabled as an auto adaptation source	`existing configured value`
`translationMemoriesEnabled` (optional)	boolean	Whether submitted translation memories are enabled as an auto adaptation source	`existing configured value`
`feedbackEnabled` (optional)	boolean	Whether feedback is enabled as an auto adaptation source	`existing configured value`

Returns

Returns the auto adaptation configuration object.

Retrieve the auto adaptation settings

curl "https://controller-host:8001/api/v2/system/auto-adaptation" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "translationMemories": {
        "enabled": false
    },
    "dictionaries": {
        "enabled": true
    },
    "feedback": {
        "enabled": true
    }
}

Retrieve the auto adaptation configuration.

HTTP Request

GET /api/v2/system/auto-adaptation

Returns

Returns the auto adaptation settings as a AutoAdaptationSources object.

Name	Type	Description
`enabled`	boolean	Whether overall auto adaptation is enabled
`threshold`	int	The overall threshold to trigger an adaptation
`successfulTrainingsToKeep`	int	The number of successful training jobs to keep per language pair ID
`unsuccessfulTrainingsToKeep`	int	The number of unsuccessful (cancelled or failed) training jobs to keep per language pair ID
`includePendingFeedback`	boolean	Whether to include pending feedback in the gathered feedback data
`retryFailedTrainingIntervalInSecs`	int	The number of seconds to wait after a failed training before attempting to start a new one
`sources`	object	The sources factored into the auto adaptations
`→ translationMemories`	object	Settings pertaining to translation memories input
`→ → enabled`	boolean	Whether this source is enabled as an auto adaptation source
`→ dictionaries`	object	Settings pertaining to dictionaries input
`→ → enabled`	boolean	Whether this source is enabled as an auto adaptation source
`→ feedback`	object	Settings pertaining to feedback input
`→ → enabled`	boolean	Whether this source is enabled as an auto adaptation source

Languages

List languages

curl "https://controller-host:8001/api/v2/languages" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "languages": [
        {
            "code": "eng",
            "name": "English",
            "languageTag": "en"
        }
    ]
}

Return the list of known languages along with language code and tag.

HTTP Request

GET /api/v2/languages

Returns

Returns all known languages as a LanguageList object with the following attributes:

Name	Type	Description
`languages`	array of objects	List of languages as an array of `Language` objects (expanded below)
`→ code`	string	Edge code of language (see language codes table)
`→ name`	string	Full name of language
`→ languageTag`	string	IETF language tag of language (see language codes table).

Language Detections

Create a language detection

curl "https://controller-host:8001/api/v2/language-detections" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d base64="0" \
    --data-urlencode input="This is some text in English."

{
    "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
`base64` (optional)	string	When this parameter is set to 0 (the default is 1), the “input” parameter below does not need to be Base64-encoded	`1`
`input`	string	Base64-encoded (unless base64 parameter above is explicitly set to 0) and URL-encoded content to submit for language detection
`inputFormat` (optional)	string	Format of input document (see table of possible input formats)	`text/plain`
`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	Edge 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

Monitoring

Retrieve Prometheus metrics

curl "https://controller-host:8001/metrics" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

# HELP mte_users Number of users.
# TYPE mte_users gauge
mte_users{status="active"} 2
# HELP mte_http_requests_by_type HTTP Requests received by the API server, by type.
# TYPE mte_http_requests_by_type counter
mte_http_requests_by_type{method="GET",status_code="200"} 90
mte_http_requests_by_type{method="POST",status_code="200"} 1

Retrieve monitoring results of Prometheus metric values in Prometheus text exposition format.

HTTP Request

GET /metrics

Request Body

Add “Accept: application/json” to the HTTP header in order to return the metrics in JSON format.

Returns

A list of metrics in the Prometheus text format

# HELP <metric name> <help text>
# TYPE <metric name> <type>
<metric name>{<label name>=<label value>, …}

Retrieve metrics

curl "https://controller-host:8001/api/v2/metrics" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

[
    {
        "name": "mte_users",
        "help": "Number of users.",
        "type": "GAUGE",
        "metrics": [
            {
                "labels": {
                    "status": "active"
                },
                "value": "2"
            }
        ]
    },
    {
        "name": "mte_http_requests_by_type",
        "help": "HTTP requests received by the API server, by type.",
        "type": "COUNTER",
        "metrics": [
            {
                "labels": {
                    "method": "GET",
                    "status_code": "200"
                },
                "value": "90"
            },
            {
                "labels": {
                    "method": "POST",
                    "status_code": "200"
                },
                "value": "1"
            }
        ]
    }
]

Retrieve monitoring results of Prometheus metric values.

HTTP Request

GET /api/v2/metrics

Returns

Returns a list of metric values as an array of PrometheusMetricFamily objects

Name	Type	Description
	array of objects	List of `PrometheusMetricFamily` objects (expanded below)
`→ name`	string	Name of the metric being monitored
`→ help`	string	Description of the metric
`→ type`	string	One of the four `PrometheusMetricTypes` (listed below)
`→ metrics`	array of objects	List of `PrometheusMetric` objects, depending on the `PrometheusMetricType`

Prometheus Metric Types

Type	Description
`Counter`	A single numerical value that only ever goes up.
`Gauge`	A single numerical value that can arbitrarily go up and down.
`Histogram`	Keeps counts of individual observations from an event or sample stream in configurable buckets and also provides a sum of observations and an observation count.
`Summary`	Tracks individual observations from an event or sample stream and summarizes them in a manner similar to traditional summary statistics: 1. sum of observations, 2. observation count, 3. rank estimations.

Prometheus Counter Metrics

Name	Type	Description
`labels`	object	Custom label object providing more information on the metric value
`value`	string	A single numerical value that only ever goes up

Prometheus Gauge Metrics

Name	Type	Description
`labels`	object	Custom label object providing more information on the metric value
`value`	string	A single numerical value that can arbitrarily go up and down

Prometheus Histogram Metric

Name	Type	Description
`labels`	object	Custom label object providing more information on the metric value
`buckets`	object	Cumulative counters for the observation buckets, determined by an upper inclusive bound
`count`	string	The count of all events that have been observed
`sum`	string	The sum of all observed values

Prometheus Summary Metric

Name	Type	Description
`labels`	object	Custom label object providing more information on the metric value
`quantiles`	object	Streaming φ-quantiles (0 ≤ φ ≤ 1) of observed events
`count`	string	The count of all events that have been observed
`sum`	string	The sum of all observed values

Retrieve metrics history

curl "https://controller-host:8001/api/v2/metrics/history" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

[
    {
        "metricFamilies": [
            {
                "name": "mte_users",
                "help": "Number of users.",
                "type": "GAUGE",
                "metrics": [
                    {
                        "labels": {
                            "status": "active"
                        },
                        "value": "2"
                    }
                ]
            },
            {
                "name": "mte_http_requests_by_type",
                "help": "HTTP requests received by the API server, by type.",
                "type": "COUNTER",
                "metrics": [
                    {
                        "labels": {
                            "method": "GET",
                            "status_code": "200"
                        },
                        "value": "90"
                    },
                    {
                        "labels": {
                            "method": "POST",
                            "status_code": "200"
                        },
                        "value": "1"
                    }
                ]
            }
        ],
        "timestamp": "2021-05-19 21:47:16.516497363Z"
    },
    {
        "metricFamilies": [
            {
                "name": "mte_users",
                "help": "Number of users.",
                "type": "GAUGE",
                "metrics": [
                    {
                        "labels": {
                            "status": "active"
                        },
                        "value": "2"
                    }
                ]
            },
            {
                "name": "mte_http_requests_by_type",
                "help": "HTTP requests received by the API server, by type.",
                "type": "COUNTER",
                "metrics": [
                    {
                        "labels": {
                            "method": "GET",
                            "status_code": "200"
                        },
                        "value": "90"
                    },
                    {
                        "labels": {
                            "method": "POST",
                            "status_code": "200"
                        },
                        "value": "1"
                    }
                ]
            }
        ],
        "timestamp": "2021-05-19 21:47:21.517820251Z"
    }
]

Retrieve a history of monitoring results of Prometheus metric values.

HTTP Request

GET /api/v2/metrics/history

Returns

Returns a list of metric values as an array of PrometheusMetricFamilies objects

Name	Type	Description
	array of objects	List of `PrometheusMetricFamilies` objects (expanded below)
`→ metricFamilies`	array of objects	List of `PrometheusMetricFamily` objects
`→ timestamp`	string	Timestamp (in UTC) of when these metrics were observed (see timestamps for formatting)

Reports

Retrieve a report of translations

curl "https://controller-host:8001/api/v2/reports/translations?fromTimestamp=2019-01-01_11%3A26%3A45.158516672" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "translations": [
        {
            "translationId": "bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd",
            "type": "sync",
            "translationRecord": {
                "translationId": "bf91b9b6-d3c2-4ff2-ad3b-c9be89bd67fd",
                "profile": {
                    "username": "jsmith@example.com",
                    "title": "example translation",
                    "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
                    "encoding": "utf-8",
                    "inputFormat": "text/html",
                    "pdfConverter": "",
                    "pdfPageCount": 0,
                    "imageConverter": "",
                    "dictionaryIds": [
                        "dict1_c95c72dd2f138da2a46c872a40616eb1",
                        "dict2_397e8373985929881616bcaa4805844a"
                    ],
                    "outputFormat": "",
                    "highlightDictionary": true,
                    "highlightBrand": true,
                    "highlightFeedback": true,
                    "unknownMode": "transliteration",
                    "highlightUnknown": false,
                    "markSegments": true,
                    "sourceRequested": false,
                    "generateMetadata": false,
                    "translationMethod": "MTE",
                    "labels": [
                        {
                            "id": 4,
                            "name": "Legal"
                        },
                        {
                            "id": 28,
                            "name": "Medical"
                        }
                    ],
                    "includeEditorInput": false,
                    "includeTextContent": false,
                    "includeSegmentPairs": false
                },
                "result": {
                    "completedSegments": 64,
                    "inputSize": 3613,
                    "sourceCharacterCount": 3498,
                    "sourceWordCount": 689,
                    "targetCharacterCount": 3840,
                    "targetWordCount": 766,
                    "totalSegments": 64,
                    "outputSize": 4006,
                    "progress": 100,
                    "wordsPerMinute": 52065,
                    "qualityEstimation": {
                        "good": 73.333336,
                        "adequate": 10.123456,
                        "poor": 16.543211
                    }
                },
                "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": "",
            "timeQueued": ""
        }
    ],
    "options": {
        "username": "",
        "languagePairId": "",
        "languagePairTypes": "",
        "translationType": "",
        "substate": "",
        "labels": "",
        "fromTimestamp": "2019-01-01 11:26:45.158516672Z",
        "toTimestamp": ""
    },
    "page": 1,
    "perPage": 25,
    "totalPages": 1,
    "totalItems": 1
}

Retrieve a report of translations filtered by given parameters.

HTTP Request

GET /api/v2/reports/translations

Request Parameters

Name	Type	Description	Default Value
`translationId` (optional)	string	Identifier of translation job
`username` (optional)	string	Username to filter results by
`languagePairId` (optional)	string	Language Pair to filter results by
`languagePairTypes` (optional)	string	Language Pair types to filter results by (Adapted, Chained, Cloud, Custom, Generic)
`translationType` (optional)	string	Translation types to filter results by (see table)
`substate` (optional)	string	Substate to filter results by (see table)
`labels` (optional)	string	Labels set at time of translation to filter results by – comma-separated identifiers
`fromTimestamp` (optional)	string	Beginning timestamp (in UTC) to filter results by. (see timestamps for formatting)
`toTimestamp` (optional)	string	End timestamp (in UTC) to filter results by. (see timestamps for formatting)
`page` (optional)	int	Page number to return	`1`
`perPage` (optional)	int	Number of translations to return per page	`25`

Returns

Returns a report of translations 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
`→ languagePairTypes`	string	Language Pair types the results are filtered by
`→ translationType`	string	Type of translation the results are filtered by (see table)
`→ substate`	string	Subtype of translation the results are filtered by (see table)
`→ labels`	string	Labels 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

Retrieve a report of cumulative translation totals

curl "https://controller-host:8001/api/v2/reports/totals/translations?fromTimestamp=2019-01-01_11%3A26%3A45.158516672" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "totals": {
        "numberOfTranslations": 100,
        "sourceWords": 300,
        "sourceCharacters": 1500,
        "targetWords": 400,
        "targetCharacters": 2000,
        "numberOfLanguagePairs": 10,
        "numberOfUsers": 5
    },
    "options": {
        "username": "",
        "languagePairId": "",
        "languagePairTypes": "",
        "translationType": "",
        "substate": "",
        "labels": "",
        "fromTimestamp": "2019-01-01 11:26:45.158516672Z",
        "toTimestamp": ""
    }
}

Retrieve a report of cumulative translation totals filtered by given parameters.

HTTP Request

GET /api/v2/reports/totals/translations

Request Parameters

Name	Type	Description
`translationId` (optional)	string	Identifier of translation job
`username` (optional)	string	Username to filter results by
`languagePairId` (optional)	string	Language Pair to filter results by
`languagePairTypes` (optional)	string	Language Pair types to filter results by (Adapted, Chained, Cloud, Custom, Generic)
`translationType` (optional)	string	Translation types to filter results by (see table)
`substate` (optional)	string	Substate to filter results by (see table)
`labels` (optional)	string	Labels set at time of translation to filter results by – comma-separated identifiers
`fromTimestamp` (optional)	string	Beginning timestamp (in UTC) to filter results by. (see timestamps for formatting)
`toTimestamp` (optional)	string	End timestamp (in UTC) to filter results by. (see timestamps for formatting)

Returns

Returns a report of translation totals filtered by the given timestamps and other provided parameters.

Name	Type	Description
`totals`	object	Fields the returned translation totals (expanded below)
`→ numberOfTranslations`	int	Total number of documents processed
`→ sourceWords`	int	Total number of source words processed
`→ sourceCharacters`	int	Total number of source characters processed
`→ targetWords`	int	Total number of target words processed
`→ targetCharacters`	int	Total number of target characters processed
`→ numberOfLanguagePairs`	int	Total number of language pairs used for translations
`→ numberOfUsers`	int	Total number of users who have performed translations
`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
`→ languagePairTypes`	string	Language Pair types the results are filtered by
`→ translationType`	string	Type of translation the results are filtered by (see table)
`→ substate`	string	Subtype of translation the results are filtered by (see table)
`→ labels`	string	Labels 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

Retrieve a report of cumulative translation totals per language pair

curl "https://controller-host:8001/api/v2/reports/totals/translations/language-pairs?fromTimestamp=2019-01-01_11%3A26%3A45.158516672" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "totalsPerLp": [
        {
            "numberOfTranslations": 100,
            "languagePairId": "EngFra_Generic_SRV_TNMV_8_4_x_1",
            "sourceWords": 300,
            "sourceCharacters": 1500,
            "targetWords": 400,
            "targetCharacters": 2000
        }
    ],
    "options": {
        "username": "",
        "languagePairId": "",
        "languagePairTypes": "",
        "translationType": "",
        "substate": "",
        "labels": "",
        "fromTimestamp": "2019-01-01 11:26:45.158516672Z",
        "toTimestamp": ""
    }
}

Retrieve a report of cumulative translation totals per language pair filtered by given parameters.

HTTP Request

GET /api/v2/reports/totals/translations/language-pairs

Request Parameters

Name	Type	Description
`translationId` (optional)	string	Identifier of translation job
`username` (optional)	string	Username to filter results by
`languagePairId` (optional)	string	Language Pair to filter results by
`languagePairTypes` (optional)	string	Language Pair types to filter results by (Adapted, Chained, Cloud, Custom, Generic)
`translationType` (optional)	string	Translation types to filter results by (see table)
`substate` (optional)	string	Substate to filter results by (see table)
`labels` (optional)	string	Labels set at time of translation to filter results by – comma-separated identifiers
`fromTimestamp` (optional)	string	Beginning timestamp (in UTC) to filter results by. (see timestamps for formatting)
`toTimestamp` (optional)	string	End timestamp (in UTC) to filter results by. (see timestamps for formatting)

Returns

Returns a report of translation totals per language pair filtered by the given timestamps and other provided parameters.

Name	Type	Description
`totalsPerLp`	array of totals	List of totals per language pair
`→ languagePairId`	string	Language pair identifier
`→ numberOfTranslations`	int	Total number of documents processed
`→ sourceWords`	int	Total number of source words processed
`→ sourceCharacters`	int	Total number of source characters processed
`→ targetWords`	int	Total number of target words processed
`→ targetCharacters`	int	Total number of target characters processed
`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
`→ languagePairTypes`	string	Language Pair types the results are filtered by
`→ translationType`	string	Type of translation the results are filtered by (see table)
`→ substate`	string	Subtype of translation the results are filtered by (see table)
`→ labels`	string	Labels 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

Retrieve a report of cumulative translation totals per user

curl "https://controller-host:8001/api/v2/reports/totals/translations/users?fromTimestamp=2019-01-01_11%3A26%3A45.158516672" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "totalsPerUser": [
        {
            "numberOfTranslations": 100,
            "username": "jsmith@example.com",
            "sourceWords": 300,
            "sourceCharacters": 1500,
            "targetWords": 400,
            "targetCharacters": 2000
        }
    ],
    "options": {
        "username": "",
        "languagePairId": "",
        "languagePairTypes": "",
        "translationType": "",
        "substate": "",
        "labels": "",
        "fromTimestamp": "2019-01-01 11:26:45.158516672Z",
        "toTimestamp": ""
    }
}

Retrieve a report of cumulative translation totals per user filtered by given parameters.

HTTP Request

GET /api/v2/reports/totals/translations/users

Request Parameters

Name	Type	Description
`translationId` (optional)	string	Identifier of translation job
`username` (optional)	string	Username to filter results by
`languagePairId` (optional)	string	Language Pair to filter results by
`languagePairTypes` (optional)	string	Language Pair types to filter results by (Adapted, Chained, Cloud, Custom, Generic)
`translationType` (optional)	string	Translation types to filter results by (see table)
`substate` (optional)	string	Substate to filter results by (see table)
`labels` (optional)	string	Labels set at time of translation to filter results by – comma-separated identifiers
`fromTimestamp` (optional)	string	Beginning timestamp (in UTC) to filter results by. (see timestamps for formatting)
`toTimestamp` (optional)	string	End timestamp (in UTC) to filter results by. (see timestamps for formatting)

Returns

Returns a report of translation totals per user filtered by the given timestamps and other provided parameters.

Name	Type	Description
`totalsPerUser`	array of totals	List of totals per user
`→ username`	string	Username
`→ numberOfTranslations`	int	Total number of documents processed
`→ sourceWords`	int	Total number of source words processed
`→ sourceCharacters`	int	Total number of source characters processed
`→ targetWords`	int	Total number of target words processed
`→ targetCharacters`	int	Total number of target characters processed
`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
`→ languagePairTypes`	string	Language Pair types the results are filtered by
`→ translationType`	string	Type of translation the results are filtered by (see table)
`→ substate`	string	Subtype of translation the results are filtered by (see table)
`→ labels`	string	Labels 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

Retrieve a spreadsheet report of cumulative translation totals

curl "https://controller-host:8001/api/v2/reports/totals/translations/export?fromTimestamp=2019-01-01_11%3A26%3A45.158516672" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

application/vnd.openxmlformats-officedocument.spreadsheetml

Retrieve a spreadsheet report of cumulative translation totals filtered by given parameters.

HTTP Request

GET /api/v2/reports/totals/translations/export

Request Parameters

Name	Type	Description
`translationId` (optional)	string	Identifier of translation job
`username` (optional)	string	Username to filter results by
`languagePairId` (optional)	string	Language Pair to filter results by
`languagePairTypes` (optional)	string	Language Pair types to filter results by (Adapted, Chained, Cloud, Custom, Generic)
`translationType` (optional)	string	Translation types to filter results by (see table)
`substate` (optional)	string	Substate to filter results by (see table)
`labels` (optional)	string	Labels set at time of translation to filter results by – comma-separated identifiers
`fromTimestamp` (optional)	string	Beginning timestamp (in UTC) to filter results by. (see timestamps for formatting)
`toTimestamp` (optional)	string	End timestamp (in UTC) to filter results by. (see timestamps for formatting)

Returns

Returns a spreadsheet.

Delete translations from reports database

curl "https://controller-host:8001/api/v2/reports/translations" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d purgeMaxAgeInSecs="36000"

{
    "purgeMaxAgeInSecs": 8640000
}

Delete translations from reports database beyond a given maximum age in seconds.

HTTP Request

DELETE /api/v2/reports/translations

Request Parameters

Name	Type	Description	Default Value
`purgeMaxAgeInSecs`	int	Translations at this age and older will be deleted from the reports database

Returns

Returns the maximum age of the translations not deleted.

Name	Type	Description
`purgeMaxAgeInSecs`	int	Maximum age in seconds of translations not deleted

Themes

Retrieve the custom theme

curl "https://controller-host:8001/api/v2/themes" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "styleNavigationBarBackgroundColor": "#008080",
    "styleNavigationBarTextColor": "#FFF",
    "styleLoginFormBackgroundColor": "#FFF",
    "stylePrimaryGroupTextColor": "#FFF",
    "stylePrimaryGroupColor": "#008080",
    "styleTranslationNotificationBackgroundColor": "#FFF",
    "styleLoginNotificationBackgroundColor": "#FFF",
    "tabTitle": "Language Weaver Edge",
    "navigationBarLogoUrl": "/themes/be7d9db3-1ca9-4c39-9ea7-6cb6e70a294e/navigationBarLogo.png",
    "loginLogoUrl": "/themes/be7d9db3-1ca9-4c39-9ea7-6cb6e70a294e/loginLogo.png",
    "faviconUrl": "/themes/be7d9db3-1ca9-4c39-9ea7-6cb6e70a294e/favicon.png",
    "translationNotificationMessage": "Hello",
    "sanitizeTranslationNotification": false,
    "loginNotificationMessage": "Welcome",
    "sanitizeLoginNotification": false
}

Retrieve the attributes of the custom theme.

HTTP Request

GET /api/v2/themes

Returns

Returns the theme object with the current attributes.

Name	Type	Description
`styleNavigationBarBackgroundColor`	string	Hex color of navigation bar background
`styleNavigationBarTextColor`	string	Hex color of navigation bar text
`styleLoginFormBackgroundColor`	string	Hex color of login form background
`stylePrimaryGroupTextColor`	string	Hex color of primary group text
`stylePrimaryGroupColor`	string	Hex color of primary group
`styleTranslationNotificationBackgroundColor`	string	Hex color of notification message background color
`styleLoginNotificationBackgroundColor`	string	Hex color of login notification message background color
`tabTitle`	string	Title of browser tab
`navigationBarLogoUrl`	string	Unique URL to navigation bar logo
`loginLogoUrl`	string	Unique URL to login logo
`faviconUrl`	string	Unique URL to browser favicon
`translationNotificationMessage`	string	Notification message to display on Translate page
`sanitizeTranslationNotification`	boolean	Whether the translation notification message will be sanitized
`loginNotificationMessage`	string	Notification message to display on the Login page
`sanitizeLoginNotification`	boolean	Whether the login notification message will be sanitized

Update the custom theme

curl "https://controller-host:8001/api/v2/themes" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -H "Content-Type: multipart/form-data" \
    -F favicon="@<file>"
    -F loginLogo="@<file>"
    -F loginNotificationMessage="Welcome"
    -F navigationBarLogo="@<file>"
    -F sanitizeLoginNotification="false"
    -F sanitizeTranslationNotification="false"
    -F styleLoginFormBackgroundColor="#FFF"
    -F styleLoginNotificationBackgroundColor="#FFF"
    -F styleNavigationBarBackgroundColor="#008080"
    -F styleNavigationBarTextColor="#FFF"
    -F stylePrimaryGroupColor="#008080"
    -F stylePrimaryGroupTextColor="#FFF"
    -F styleTranslationNotificationBackgroundColor="#FFF"
    -F tabTitle="Language Weaver Edge"
    -F translationNotificationMessage="Hello"

{
    "styleNavigationBarBackgroundColor": "#008080",
    "styleNavigationBarTextColor": "#FFF",
    "styleLoginFormBackgroundColor": "#FFF",
    "stylePrimaryGroupTextColor": "#FFF",
    "stylePrimaryGroupColor": "#008080",
    "styleTranslationNotificationBackgroundColor": "#FFF",
    "styleLoginNotificationBackgroundColor": "#FFF",
    "tabTitle": "Language Weaver Edge",
    "navigationBarLogoUrl": "/themes/be7d9db3-1ca9-4c39-9ea7-6cb6e70a294e/navigationBarLogo.png",
    "loginLogoUrl": "/themes/be7d9db3-1ca9-4c39-9ea7-6cb6e70a294e/loginLogo.png",
    "faviconUrl": "/themes/be7d9db3-1ca9-4c39-9ea7-6cb6e70a294e/favicon.png",
    "translationNotificationMessage": "Hello",
    "sanitizeTranslationNotification": false,
    "loginNotificationMessage": "Welcome",
    "sanitizeLoginNotification": false
}

Update the attributes of the custom theme. If a field is left empty, the previous attribute will be used.

HTTP Request

POST /api/v2/themes

Request Parameters

Name	Type	Description	Default Value
`styleNavigationBarBackgroundColor` (optional)	string	Hex color of navigation bar background	`existing configured value`
`styleNavigationBarTextColor` (optional)	string	Hex color of navigation bar text	`existing configured value`
`styleLoginFormBackgroundColor` (optional)	string	Hex color of login form background	`existing configured value`
`stylePrimaryGroupTextColor` (optional)	string	Hex color of primary group text	`existing configured value`
`stylePrimaryGroupColor` (optional)	string	Hex color of primary group	`existing configured value`
`styleTranslationNotificationBackgroundColor` (optional)	string	Hex color of translation notification message background color	`existing configured value`
`styleLoginNotificationBackgroundColor` (optional)	string	Hex color of login notification message background color	`existing configured value`
`tabTitle` (optional)	string	Title of browser tab	`existing configured value`
`navigationBarLogo` (optional)	file	Image (.jpg, .png, .svg) file to set as navigation bar logo	`existing configured value`
`loginLogo` (optional)	file	Image (.jpg, .png, .svg) file to set as login form logo	`existing configured value`
`favicon` (optional)	file	Image (.ico) file to set as browser favicon	`existing configured value`
`translationNotificationMessage` (optional)	string	Notification message to display on Translate page	`existing configured value`
`sanitizeTranslationNotification` (optional)	boolean	Whether the translation notification message will be sanitized	`existing configured value`
`loginNotificationMessage` (optional)	string	Notification message to display on the Login page	`existing configured value`
`sanitizeLoginNotification` (optional)	boolean	Whether the login notification message will be sanitized	`existing configured value`

Returns

Returns the theme object with the user defined attributes.

Name	Type	Description
`styleNavigationBarBackgroundColor`	string	Hex color of navigation bar background
`styleNavigationBarTextColor`	string	Hex color of navigation bar text
`styleLoginFormBackgroundColor`	string	Hex color of login form background
`stylePrimaryGroupTextColor`	string	Hex color of primary group text
`stylePrimaryGroupColor`	string	Hex color of primary group
`styleTranslationNotificationBackgroundColor`	string	Hex color of notification message background color
`styleLoginNotificationBackgroundColor`	string	Hex color of login message background color
`tabTitle`	string	Title of browser tab
`navigationBarLogoUrl`	string	Unique URL to navigation bar logo
`loginLogoUrl`	string	Unique URL to login logo
`faviconUrl`	string	Unique URL to browser favicon
`translationNotificationMessage`	string	Notification message to display on Translate page
`loginNotificationMessage`	string	Notification message to display on the Login page

Profiles

List profiles

curl "https://controller-host:8001/api/v2/profiles" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf \
    -H "Content-Type: multipart/form-data" \
    -F ids="1ce92dda-0a13-4d6d-ae32-eff80042390e"

{
    "profiles": [
        {
            "id": "1ce92dda-0a13-4d6d-ae32-eff80042390e",
            "order": 1,
            "name": "profile1",
            "enforced": false,
            "enabled": true,
            "selector": {
                "sourceLanguageId": "eng",
                "targetLanguageId": "fra",
                "roles": [
                    "super admin"
                ],
                "usernames": [
                    "jsmith@example.com"
                ]
            },
            "rules": {
                "dictionaryIds": [
                    "dictionary1"
                ],
                "labels": [
                    "label1"
                ],
                "languageModel": "Generic",
                "linguisticOptions": [
                    {
                        "id": "Spelling",
                        "value": "US"
                    }
                ],
                "outputFormat": {
                    "pdfTo": "application/pdf"
                },
                "pdfConverter": "Standard",
                "qualityEstimation": "Enabled"
            }
        }
    ],
    "page": 1,
    "perPage": 25,
    "totalPages": 1,
    "totalItems": 1
}

Return a list of profiles based upon the specified filters.

HTTP Request

GET /api/v2/profiles

Request Parameters

Name	Type	Description	Default Value
`ids` (optional)	string	List profiles that match any of the given comma-separated id substrings
`names` (optional)	string	List profiles that match any of the given comma-separated name substrings
`enabled` (optional)	boolean	List profiles that match the given enabled value
`enforced` (optional)	boolean	List profiles that match the given enforced value
`sourceLanguageId` (optional)	string	List profiles that match the given sourceLanguageId (3-letter-code)
`targetLanguageId` (optional)	string	List profiles that match the given targetLanguageId (3-letter-code)
`roles` (optional)	string	List profiles that match the given comma-separated roles
`usernames` (optional)	string	List profiles that match any of the given comma-separated username substrings
`dictionaryIds` (optional)	string	List profiles that match any of the given comma-separated dictionaryId substrings
`labels` (optional)	string	List profiles that match any of the given comma-separated label substrings
`languageModels` (optional)	string	List profiles that match the given comma-separated languageModels
`linguisticOptions` (optional)	string	List profiles that match the given comma-separated key:value linguisticOptions; (see list language-pairs) to display available linguistic options.
`outputFormatsEmailTo` (optional)	string	List profiles that match the given comma-separated output format for Email input documents
`outputFormatsImageTo` (optional)	string	List profiles that match the given comma-separated output format for Image input documents
`outputFormatsPdfTo` (optional)	string	List profiles that match the given comma-separated output format for PDF input documents
`outputFormatsWordTo` (optional)	string	List profiles that match the given comma-separated output format for Word input documents
`outputFormatsOtherTo` (optional)	string	List profiles that match the given comma-separated output format for all other input documents
`pdfConverters` (optional)	string	List profiles that match the given comma-separated PDF Converter types
`qualityEstimations` (optional)	string	List profiles that match the given comma-separated Quality Estimation settings
`page` (optional)	int	Page number to return	`1`
`perPage` (optional)	int	Number of translations to return per page	`25`

Returns

Returns a list of profiles as a ProfileList object with the following attributes:

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

Retrieve profile

curl "https://controller-host:8001/api/v2/profiles/1ce92dda-0a13-4d6d-ae32-eff80042390e" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "id": "1ce92dda-0a13-4d6d-ae32-eff80042390e",
    "order": 1,
    "name": "profile1",
    "enforced": false,
    "enabled": true,
    "selector": {
        "sourceLanguageId": "eng",
        "targetLanguageId": "fra",
        "roles": [
            "super admin"
        ],
        "usernames": [
            "jsmith@example.com"
        ]
    },
    "rules": {
        "dictionaryIds": [
            "dictionary1"
        ],
        "labels": [
            "label1"
        ],
        "languageModel": "Generic",
        "linguisticOptions": [
            {
                "id": "Spelling",
                "value": "US"
            }
        ],
        "outputFormat": {
            "pdfTo": "application/pdf"
        },
        "pdfConverter": "Standard",
        "qualityEstimation": "Enabled"
    }
}

Return the profile of a specified ID.

HTTP Request

GET /api/v2/profiles/{id}

Path Parameters

Name	Type	Description
`id`	string	Identifier of a profile

Returns

Returns a Profile object with the following attributes:

Name	Type	Description
`id`	string	Identifier of the profile
`order`	string	Order number of the profile; profiles inherit rules from preceding profiles
`name`	string	Name of the profile
`enabled`	boolean	Whether the profile is enabled
`enforced`	boolean	Whether the profile is enforced; profile rule is enforced over user-provided translation setting
`selector`	object	Selectors used to determine when profile rules are used
`→ sourceLanguageId`	string	The sourceLanguageId (3-letter-code) a translation job will be matched against before profile rules are applied
`→ targetLanguageId`	string	The targetLanguageId (3-letter-code) a translation job will be matched against before profile rules are applied
`→ roles`	array of strings	List of roles a translation job will be matched against before profile rules are applied; only one role or username needs to match before application
`→ usernames`	array of strings	List of usernames a translation job will be matched against before profile rules are applied; only one username or role needs to match before application
`rules`	object	Rules are translation parameters that are applied to translations that have matching profile selectors
`→ dictionaryIds`	array of strings	List of dictionaryIds to apply to translation
`→ labels`	array of strings	List of labels to apply to translation
`→ languageModel`	string	The languageModel to apply to a language detection translation when multiple models of a language pair exist; in the Language Weaver Edge Web GUI the languageModel is set as the default model for translations
`→ linguisticOptions`	array of key:value strings	List of linguisticOption key:values to apply to translation; (see list language-pairs) to display available linguistic options
`→ outputFormat`	object	Output format to use for each input format
`→ → emailTo`	string	Output format to use for Email input documents
`→ → imageTo`	string	Output format to use for Image input documents
`→ → pdfTo`	string	Output format to use for PDF input documents
`→ → wordTo`	string	Output format to use for Word input documents
`→ → otherTo`	string	Output format to use for all other input documents
`→ pdfConverter`	string	The PDF Converter to use for PDF document translations: `Abbyy` (license required) or Standard.
`→ qualityEstimation`	string	The Quality Estimation setting to use for a translation: `Enabled` or `Disabled`.

Export profiles

curl "https://controller-host:8001/api/v2/profiles/export" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "profiles": [
        {
            "id": "1ce92dda-0a13-4d6d-ae32-eff80042390e",
            "order": 1,
            "name": "profile1",
            "enforced": false,
            "enabled": true,
            "selector": {
                "sourceLanguageId": "eng",
                "targetLanguageId": "fra",
                "roles": [
                    "super admin"
                ],
                "usernames": [
                    "jsmith@example.com"
                ]
            },
            "rules": {
                "dictionaryIds": [
                    "dictionary1"
                ],
                "labels": [
                    "label1"
                ],
                "languageModel": "Generic",
                "linguisticOptions": [
                    {
                        "id": "Spelling",
                        "value": "US"
                    }
                ],
                "outputFormat": {
                    "pdfTo": "application/pdf"
                },
                "pdfConverter": "Standard",
                "qualityEstimation": "Enabled"
            }
        }
    ]
}

Export all the profiles as JSON format.

HTTP Request

GET /api/v2/profiles/export

Returns

Returns a ProfilesFile object with the following attributes:

Name	Type	Description
`profiles`	array of profiles	List of profiles as an array of `Profile` objects

Add profiles

curl "https://controller-host:8001/api/v2/profiles" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -H "Content-Type: multipart/form-data" \
    -F input="@<file>"

{
    "total": 5,
    "totalSkipped": 2,
    "warnings": [
        "duplicate name exists"
    ]
}

Append new profiles to existing profile list.

HTTP Request

POST /api/v2/profiles

Request Parameters

Name	Type	Description	Default Value
`input`	file	A JSON file containing a `ProfileList` object

Returns

Returns a ProfileResponse object with the following attributes:

Name	Type	Description
`total`	int	Total number of profiles added
`totalSkipped`	int	Total number of profiles skipped
`warnings`	array of strings	An array of warnings describing why a profile was skipped; one warning may be returned for multiple profiles that share the same reason for being skipped. View the API logs for more details.

Overwrite profiles

curl "https://controller-host:8001/api/v2/profiles" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -H "Content-Type: multipart/form-data" \
    -F input="@<file>"

{
    "total": 5,
    "totalSkipped": 2,
    "warnings": [
        "duplicate name exists"
    ]
}

Overwrite all profiles with a new list.

HTTP Request

PUT /api/v2/profiles

Request Parameters

Name	Type	Description	Default Value
`input`	file	A JSON file containing a `ProfileList` object

Returns

Returns a ProfileResponse object with the following attributes:

Name	Type	Description
`total`	int	Total number of profiles added
`totalSkipped`	int	Total number of profiles skipped
`warnings`	array of strings	An array of warnings describing why a profile was skipped; one warning may be returned for multiple profiles that share the same reason for being skipped. View the API logs for more details.

Update profile

curl "https://controller-host:8001/api/v2/profiles/1ce92dda-0a13-4d6d-ae32-eff80042390e" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -H "Content-Type: multipart/form-data" \
    -F input="@<file>"

{
    "id": "1ce92dda-0a13-4d6d-ae32-eff80042390e",
    "order": 1,
    "name": "profile1",
    "enforced": false,
    "enabled": true,
    "selector": {
        "sourceLanguageId": "eng",
        "targetLanguageId": "fra",
        "roles": [
            "super admin"
        ],
        "usernames": [
            "jsmith@example.com"
        ]
    },
    "rules": {
        "dictionaryIds": [
            "dictionary1"
        ],
        "labels": [
            "label1"
        ],
        "languageModel": "Generic",
        "linguisticOptions": [
            {
                "id": "Spelling",
                "value": "US"
            }
        ],
        "outputFormat": {
            "pdfTo": "application/pdf"
        },
        "pdfConverter": "Standard",
        "qualityEstimation": "Enabled"
    }
}

Update the profile of a specified ID.

HTTP Request

PUT /api/v2/profiles/{id}

Path Parameters

Name	Type	Description
`id`	string	Identifier of a profile

Request Parameters

Name	Type	Description	Default Value
`input`	file	A JSON file containing a `Profile` object

Returns

Returns a Profile object of the updated profile.

Delete profile

curl "https://controller-host:8001/api/v2/profiles/1ce92dda-0a13-4d6d-ae32-eff80042390e" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "id": "1ce92dda-0a13-4d6d-ae32-eff80042390e",
    "order": 1,
    "name": "profile1",
    "enforced": false,
    "enabled": true,
    "selector": {
        "sourceLanguageId": "eng",
        "targetLanguageId": "fra",
        "roles": [
            "super admin"
        ],
        "usernames": [
            "jsmith@example.com"
        ]
    },
    "rules": {
        "dictionaryIds": [
            "dictionary1"
        ],
        "labels": [
            "label1"
        ],
        "languageModel": "Generic",
        "linguisticOptions": [
            {
                "id": "Spelling",
                "value": "US"
            }
        ],
        "outputFormat": {
            "pdfTo": "application/pdf"
        },
        "pdfConverter": "Standard",
        "qualityEstimation": "Enabled"
    }
}

Delete the profile of a specified ID.

HTTP Request

DELETE /api/v2/profiles/{id}

Path Parameters

Name	Type	Description
`id`	string	Identifier of a profile

Returns

Returns a Profile object of the deleted profile.

Delete profiles

curl "https://controller-host:8001/api/v2/profiles/batch-delete" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf \
    -H "Content-Type: multipart/form-data" \
    -F ids="1ce92dda-0a13-4d6d-ae32-eff80042390e"

Delete all or specified profiles.

HTTP Request

DELETE /api/v2/profiles/batch-delete

Request Parameters

Name	Type	Description	Default Value
`ids` (optional)	string	Comma-separated list of profile ids; if an id is not specified, all profiles are deleted

Returns

Returns number of profiles deleted.

Brands

Retrieve brand entries

curl "https://controller-host:8001/api/v2/brands" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf \
    -H "Content-Type: multipart/form-data" \

{
    "brands": [
        {
            "source": "\\b[a-z]+est\\b",
            "target": "",
            "comment": "Preserve all source words ending in 'est'",
            "isSearchPatternSource": true,
            "disabled": true
        },
        {
            "source": "test",
            "target": "best",
            "comment": "Output 'test' as 'best'",
            "isSearchPatternSource": false,
            "disabled": false
        }
    ],
    "page": 1,
    "perPage": 25,
    "totalPages": 1,
    "totalItems": 2
}

Retrieve a list of brand entries.

HTTP Request

GET /api/v2/brands

Request Parameters

Name	Type	Description	Default Value
`source` (optional)	string	Filter by source match; matches any substring
`target` (optional)	string	Filter by target match; matches any substring
`comment` (optional)	string	Filter by comment match; matches any substring
`isSearchPatternSource` (optional)	boolean	Filter by search pattern sources
`disabled` (optional)	boolean	Filter by disabled brands
`page` (optional)	int	Page number to return	`1`
`perPage` (optional)	int	Number of brand entries to return per page	`25`

Returns

Returns a list of brands a brand object with the following attributes.

Name	Type	Description
`brands`	array of objects	List of brand entries as an array of `Brand` objects
`page`	int	Page number returned
`perPage`	int	Number of brand entries returned per page
`totalPages`	int	Total number of pages available
`totalItems`	int	Total number of brand entries

Export brand entries

curl "https://controller-host:8001/api/v2/brands/export" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf \
    -H "Content-Type: multipart/form-data" \
    -F exportFormat="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"

Export all brands as an XML or spreadsheet.

HTTP Request

GET /api/v2/brands/export

Request Parameters

Name	Type	Description	Default Value
`exportFormat` (optional)	string	Format type to export (supports `text/xml` or `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`)	`text/xml`

Returns

Returns brands in desired format.

Create a brand entry

curl "https://controller-host:8001/api/v2/brands" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d disabled="true" \
    -d isSearchPatternSource="true" \
    -d target="test" \
    --data-urlencode comment="Output all words ending in 'est' as 'test'" \
    --data-urlencode source="\b[a-z]+est\b"

{
    "brands": [
        {
            "source": "\\b[a-z]+est\\b",
            "target": "test",
            "comment": "Output all words ending in 'est' as 'test'",
            "isSearchPatternSource": true,
            "disabled": true
        }
    ],
    "page": 1,
    "perPage": 25,
    "totalPages": 1,
    "totalItems": 1
}

Create a single brand entry.

HTTP Request

POST /api/v2/brands

Request Parameters

Name	Type	Description	Default Value
`source`	string	Source brand entry preserves source in translation output; can be literal string or a search pattern (ECMAScript regular expression syntax)
`target` (optional)	string	Optional target brand entry; if empty, source will be preserved in translation output, else translation output will contain target entry
`comment` (optional)	string	Optional comment brand entry
`isSearchPatternSource` (optional)	boolean	Optional isSearchPatternSource brand entry; set true if source is a search pattern (ECMAScript regular expression syntax)	`false`
`disabled` (optional)	boolean	Optional disabled brand entry; set true to disable brand entry	`false`

Returns

Returns the brand object with the following attributes.

Name	Type	Description
`source`	string	Brand entry source
`target`	string	Brand entry target
`comment`	string	Brand entry comment
`isSearchPatternSource`	boolean	Whether source is a search pattern
`disabled`	boolean	Whether brand entry is disabled

Import brand entries

curl "https://controller-host:8001/api/v2/brands/import" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    -H "Content-Type: multipart/form-data" \
    -F file="@<file>"
    -F importFormat="text/xml"

Import an XML or spreadsheet file of brand entries.

HTTP Request

POST /api/v2/brands/import

Request Parameters

Name	Type	Description	Default Value
`file`	file	File of brand entries that is in XML or XLSX format
`importFormat` (optional)	string	Format type of import (supports text/xml or application/vnd.openxmlformats-officedocument.spreadsheetml.sheet). Edge will attempt to determine format type if none is provided.	`detected from HTTP request Content-Type header`

Returns

Returns the number of brands imported.

Update a brand entry

curl "https://controller-host:8001/api/v2/brands" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -H "Content-Type: multipart/form-data" \
    -F comment="Output 'test' as 'best'"
    -F disabled="true"
    -F isSearchPatternSource="true"
    -F originalSource="test"
    -F source="\b[a-z]+est\b"
    -F target="best"

{
    "brands": [
        {
            "source": "\\b[a-z]+est\\b",
            "target": "test",
            "comment": "Output all words ending in 'est' as 'test'",
            "isSearchPatternSource": true,
            "disabled": true
        }
    ],
    "page": 1,
    "perPage": 25,
    "totalPages": 1,
    "totalItems": 1
}

Update a single brand entry.

HTTP Request

PUT /api/v2/brands

Request Parameters

Name	Type	Description	Default Value
`originalSource`	string	Source of brand entry to update
`source` (optional)	string	Optional updated source value of brand entry
`target` (optional)	string	Optional updated target value of brand entry
`comment` (optional)	string	Optional updated comment value of brand entry
`isSearchPatternSource` (optional)	boolean	Optional updated isSearchPatternSource value of brand entry	`existing value`
`disabled` (optional)	boolean	Optional updated disabled value of brand entry	`existing value`

Returns

Returns the brand object with the following updated attributes.

Name	Type	Description
`source`	string	Brand entry source
`target`	string	Brand entry target
`comment`	string	Brand entry comment
`isSearchPatternSource`	boolean	Whether source is a search pattern
`disabled`	boolean	Whether brand entry is disabled

Delete brand entries

curl "https://controller-host:8001/api/v2/brands" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf \
    -H "Content-Type: multipart/form-data" \
    -F source="test"

Delete a list of brand entries.

HTTP Request

DELETE /api/v2/brands

Request Parameters

Name	Type	Description	Default Value
`source`	array of strings	List of source entries to delete

Returns

Returns the number of deleted brand entries.

Delete brand entries with filter

curl "https://controller-host:8001/api/v2/brands/batch-delete" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf \
    -H "Content-Type: multipart/form-data" \
    -F source="test"

Delete a list of brand entries with extra filter options.

HTTP Request

DELETE /api/v2/brands/batch-delete

Request Parameters

Name	Type	Description
`source` (optional)	string	Delete brands by source match; matches any substring
`target` (optional)	string	Delete brands by target match; matches any substring
`comment` (optional)	string	Delete brands entries by comment match; matches any substring
`isSearchPatternSource` (optional)	boolean	Delete brands that are search pattern sources
`disabled` (optional)	boolean	Delete disabled brand entries

Returns

Returns the number of deleted brand entries.

Webhooks

List webhooks

curl "https://controller-host:8001/api/v2/webhooks" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "webhooks": [
        {
            "uuid": "febdcc87-3454-467c-82b3-cfee4c4524c0",
            "url": "https://my-webhook-server:8443",
            "description": "Webhook for translations",
            "username": "jsmith@example.com",
            "events": [
                "translation.created",
                "translation.statusChanged"
            ]
        }
    ],
    "page": 1,
    "perPage": 25,
    "totalPages": 1,
    "totalItems": 1
}

Return a list of all webhooks.

HTTP Request

GET /api/v2/webhooks

Request Parameters

Name	Type	Description	Default Value
`url` (optional)	string	URL substring to filter by
`description` (optional)	string	Description substring to filter by
`events` (optional)	string	Show only webhooks with the given comma-separated events. (see table of possible events)
`page` (optional)	int	Page number to return	`1`
`perPage` (optional)	int	Number of webhooks to return per page	`25`

Returns

Returns a list of webhooks as a Webhook object with the following attributes.

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

Webhook Event Types

There are multiple webhook event types. They are as follows:

Type	Description
`translation.created`	A translation was created
`translation.statusChanged`	A translation’s status has changed
`adaptedlp.created`	An adapted language pair was created
`adaptedlp.statusChanged`	An adapted language pair’s status has changed

Create a webhook

curl "https://controller-host:8001/api/v2/webhooks" \
    -X POST \
    -u jsmith@example.com:u0VmztKJrwqf \
    --data-urlencode description="Webhook for translations" \
    --data-urlencode events="translation.created,translation.statusChanged" \
    --data-urlencode url="https://my-webhook-server:8443"

{
    "uuid": "febdcc87-3454-467c-82b3-cfee4c4524c0",
    "url": "https://my-webhook-server:8443",
    "description": "Webhook for translations",
    "username": "jsmith@example.com",
    "events": [
        "translation.created",
        "translation.statusChanged"
    ]
}

Create a webhook.

HTTP Request

POST /api/v2/webhooks

Request Parameters

Name	Type	Description
`url`	string	URL to post events to
`events`	string	List of events that trigger the webhook
`description` (optional)	string	Description of the webhook

Returns

Returns the created Webhook object with the following attributes:

Name	Type	Description
`uuid`	int	Identifier of webhook
`url`	string	URL to post events to
`events`	array of strings	List of events that trigger the webhook
`description`	string	Description of the webhook

Update a webhook

curl "https://controller-host:8001/api/v2/webhooks/febdcc87-3454-467c-82b3-cfee4c4524c0" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    --data-urlencode description="Webhook for translations" \
    --data-urlencode events="translation.created,translation.statusChanged" \
    --data-urlencode url="https://my-webhook-server:8443"

{
    "uuid": "febdcc87-3454-467c-82b3-cfee4c4524c0",
    "url": "https://my-webhook-server:8443",
    "description": "Webhook for translations",
    "username": "jsmith@example.com",
    "events": [
        "translation.created",
        "translation.statusChanged"
    ]
}

Update a webhook’s details.

HTTP Request

PUT /api/v2/webhooks/{uuid}

Path Parameters

Name	Type	Description
`uuid`	string	Identifier of the webhook

Request Parameters

Name	Type	Description
`url`	string	URL to post events to
`events`	string	List of events that trigger the webhook
`description` (optional)	string	Description of the webhook

Returns

Returns the updated Webhook object.

Retrieve a webhook

curl "https://controller-host:8001/api/v2/webhooks/febdcc87-3454-467c-82b3-cfee4c4524c0" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "uuid": "febdcc87-3454-467c-82b3-cfee4c4524c0",
    "url": "https://my-webhook-server:8443",
    "description": "Webhook for translations",
    "username": "jsmith@example.com",
    "events": [
        "translation.created",
        "translation.statusChanged"
    ]
}

Retrieve a webhook’s details.

HTTP Request

GET /api/v2/webhooks/{uuid}

Path Parameters

Name	Type	Description
`uuid`	string	Identifier of the webhook

Returns

Returns the retrieved Webhook object.

Delete a webhook

curl "https://controller-host:8001/api/v2/webhooks/febdcc87-3454-467c-82b3-cfee4c4524c0" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "uuid": "febdcc87-3454-467c-82b3-cfee4c4524c0",
    "url": "https://my-webhook-server:8443",
    "description": "Webhook for translations",
    "username": "jsmith@example.com",
    "events": [
        "translation.created",
        "translation.statusChanged"
    ]
}

Delete a webhook.

HTTP Request

DELETE /api/v2/webhooks/{uuid}

Path Parameters

Name	Type	Description
`uuid`	string	Identifier of the webhook

Returns

Returns the deleted Webhook object.

Test webhook details

curl "https://controller-host:8001/api/v2/webhooks/test" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf \
    -d event="translation.created" \
    --data-urlencode url="https://my-webhook-server:8443"

{
    "success": true
}

Send an HTTP Post call to the specified URL, mimicking a webhook triggering for the given event.

HTTP Request

PUT /api/v2/webhooks/test

Request Parameters

Name	Type	Description	Default Value
`url`	string	URL to post events to
`event` (optional)	string	Event that triggers the webhook	`sampleEvent`

Returns

Returns the result of the webhook test as a TestResult object.

Name	Type	Description
`success`	boolean	Whether or not the test was successful

Webhook Audit Logging

List webhook audit entries

curl "https://controller-host:8001/api/v2/audit/webhooks" \
    -X GET \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "entries": [
        {
            "id": 1,
            "uuid": "febdcc87-3454-467c-82b3-cfee4c4524c0",
            "url": "https://my-webhook-server:8443",
            "event": "translation.created",
            "timeTriggered": "2018-06-21 19:03:31.799810031Z",
            "timeLastAttempted": "2018-06-21 19:03:31.799810031Z",
            "data": {
                "translationId": "acaa78f3-d739-4002-b1f6-b5027244f6e9"
            },
            "errorMessage": "",
            "retryAttempts": 0
        }
    ],
    "page": 1,
    "perPage": 25,
    "totalPages": 1,
    "totalItems": 1
}

Retrieve a list of webhook audit entries

HTTP Request

GET /api/v2/audit/webhooks

Request Parameters

Name	Type	Description	Default Value
`url` (optional)	string	URL substring to filter by
`failed` (optional)	boolean	Failure status to filter by
`event` (optional)	string	Show only webhooks with the given comma-separated events. (see table of possible events)
`page` (optional)	int	Page number to return	`1`
`perPage` (optional)	int	Number of webhooks to return per page	`25`

Returns

Returns a list of webhooks as a WebhookAuditEntryList object with the following attributes.

Name	Type	Description
`entries`	array of objects	List of entries as an array of `WebhookAuditEntry` objects
`page`	int	Page number returned
`perPage`	int	Number of entries returned per page
`totalPages`	int	Total number of pages available
`totalItems`	int	Total number of webhooks

Retry webhook audit entry

curl "https://controller-host:8001/api/v2/audit/webhooks/1/retry" \
    -X PUT \
    -u jsmith@example.com:u0VmztKJrwqf

Retry a webhook audit entry.

HTTP Request

PUT /api/v2/audit/webhooks/{id}/retry

Path Parameters

Name	Type	Description
`id`	int	Identifier of the webhook audit entry

Delete a webhook audit entry

curl "https://controller-host:8001/api/v2/audit/webhooks/1" \
    -X DELETE \
    -u jsmith@example.com:u0VmztKJrwqf

{
    "id": 1,
    "uuid": "febdcc87-3454-467c-82b3-cfee4c4524c0",
    "url": "https://my-webhook-server:8443",
    "event": "translation.created",
    "timeTriggered": "2018-06-21 19:03:31.799810031Z",
    "timeLastAttempted": "2018-06-21 19:03:31.799810031Z",
    "data": {
        "translationId": "acaa78f3-d739-4002-b1f6-b5027244f6e9"
    },
    "errorMessage": "",
    "retryAttempts": 0
}

Delete a webhook audit entry.

HTTP Request

DELETE /api/v2/audit/webhooks/{id}

Path Parameters

Name	Type	Description
`id`	int	Identifier of the webhook audit entry

Returns

Returns the deleted WebhookAuditEntry object.

Name	Type	Description
`id`	int	Identifier of the webhook audit entry
`uuid`	string	Identifier of the associated webhook
`url`	string	URL the webhook attempted to post to
`event`	string	Event that triggered the webhook
`timeTriggered`	string	The initial time the webhook was triggered
`timeLastAttempted`	string	The latest time the webhook audit entry was retried
`data`	string	The data to be posted to the remote server
`errorMessage`	string	The reason for the failed attempt (if applicable)
`retryAttempts`	int	How many times this webhook audit entry has been retried