API Documentation

Getting Started


The SDL Language Cloud Translation Toolkit enables developers to submit content for translation via the SDL Language Cloud translation platform. The SDL Language Cloud Translation Toolkit is REST-based and designed with resource-oriented URLs utilizing built-in HTTP features like HTTP authentication and HTTP verbs. The API allows developers to offer translation as a service within their own applications that are easily integrated with SDL Language Cloud Machine Translation.

Create Account


Create Account – Sign up for an account, go to Profile > User Information and enable Developer Capabilities to experience in Sandbox the full performance capabilities that the translation platform has to offer.

Generate API Key


All API calls to the translation platform need to be authenticated by utilizing an API Key. From your account you can generate an API Key so that translations can be performed in the next step. Take our translation API for a spin using the Sandbox mode. This mode offers features that enable developers to make translation calls to our platform to practice using the API without incurring fees.

Perform Translation


Now that you've created an account and generated an API Key, let's translate!

Let's translate "Hello Developers" to French by submitting a real-time translation call to the platform.

First, set the API Key (generated from the previous step) in the Authorization header of the HTTP request.
(e.g. "Authorization: LC apiKey=< Your API Key >")

Second, set the following parameter for the call:

    • text = Hello Developers
    • from = eng
    • to = fra

Lastly, translate it!

Example:

Request:

curl -X POST -H "Content-type: application/json" -H "Authorization: LC apiKey=<YOUR API KEY>" -d '{"text":"Hello Developers", "from":"eng", "to":"fra"}' https://lc-api.sdl.com/translate

Response:

{"translation":"Bonjour aux Développeurs","partialTranslation":false}

The translation platform offers a variety of machine translation services to developers.

HTTP Status Codes


200 OK
General response for successful HTTP requests.

201 Resource Created
The request has been fulfilled and resulted in a new resource being created. Reference the response body for more details.

400 Bad Request
General response for a request that could not be understood by the server. Reference the response body for more details.

401 Unauthorized
A response error caused by an invalid Authorization header or API Key. Double check the Authorization header in your request to ensure valid syntax and API Key.

403 Forbidden
The request was understood by the server, but the server refused to take any further action. The access to the requested resource is denied for some reason. Reference the response body for more details.

404 Not Found
The requested resource could not be found. Reference the response body for more details.

409 Conflict
The request could not be completed due to a conflict with the current state of the resource. Reference the response body for more details.

420 Method Failure
The request was not executed on a resource due to a flow exception. Reference the response body for more details.

422 Unprocessable Entity
The request was well-formed but was unable to be followed due to semantic errors. Reference the response body for more details.

500 Internal Server Error
A generic response for a server-side error. Reference the response body for more details.

Limitations


For Machine Translation you can use up to 500,000 characters per month in Sandbox for free.

API Reference

Utility Operations


View Languages

HTTP METHOD GET
URL /languages
CONTENT TYPE application/json
DESCRIPTION View Languages

Retrieve all Language Pairs for the qualities: machine translation 'Q1', domain specific and custom machine translation 'Q2'

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 403

You must be authorized in order to make this call

Code: 404

The entity you want to process does not exist

Code: 422

Your call contains invalid data

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
url from The source 3-letter language code (ISO 639) true
url quality The desired quality: machine translation 'Q1', domain specific and custom machine translation 'Q2' true
url extra Additional qualities. It specifies to retrieve additional machine translation engines which are applicable to particular vertical markets (e.g. Travel, Automotive) or specifically created for one customer, based on the Account's subscription. Accepted values: 'VERTICALS', 'CUSTOM' true
Samples

View Languages

curl -H "Authorization: LC apiKey=LanguageCloudAPIKey" https://lc-api.sdl.com/languages 
{
    "languageExpertise":"Q1":[
      {
         "languagePair": {
            "from":{
               "id":"505037985fe01ac20407b7fb",
               "apiVersion":null,
               "code":"eng",
               "name":"English",
               "fullName":"English",
               "rightToLeft":false
            },
            "to":{
               "id": "505037985fe01ac20407b814",
               "apiVersion":null,
               "code":"por",
               "name":"Portuguese",
               "fullName":"Portuguese",
               "rightToLeft":false
            }
         },
         "activity": "translation"
      }
   ]
}
}

View Languages (domain specific Language Pairs included)

curl -H "Authorization: LC apiKey=LanguageCloudAPIKey"
        "https://lc-api.sdl.com/languages?extra=VERTICALS" 
{
   "languageExpertise":{
       "Q1":[
         {
            "languagePair":{
               "from":{
                  "id":"505037985fe01ac20407b7fb",
                  "apiVersion":null,
                  "code":"eng",
                  "name":"English",
                   "fullName":"English",
                  "rightToLeft":false
               },
               "to":{
                  "id":"505037985fe01ac20407b814",
                  "apiVersion":null,
                  "code":"por",
                   "name":"Portuguese",
                  "fullName":"Portuguese",
                  "rightToLeft":false
               },
               "domainDescription":null,
               "domainCode":null
            },
            "activity":"translation"
         }
      ],
       "Q2":[
         {
            "languagePair":{
               "from":{
                  "id":"505037985fe01ac20407b81f",
                  "apiVersion":null,
                  "code":"spa",
                  "name":"Spanish",
                  "fullName": "Spanish; Castilian",
                  "rightToLeft":false
               },
               "to":{
                  "id":"505037985fe01ac20407b7fb",
                  "apiVersion":null,
                  "code":"eng",
                  "name":"English",
                  "fullName": "English",
                  "rightToLeft":false
               },
               "domainDescription":"medical",
               "domainCode":"MTAwMA"
            },
            "activity":"translation"
         }
      ]
   }
}

View Languages (domain specific and custom Language Pairs included)

curl -H "Authorization: LC apiKey=LanguageCloudAPIKey"
        "https://lc-api.sdl.com/languages?extra=VERTICALS&extra=CUSTOM" 
{
   "languageExpertise":{
       "Q1":[
         {
            "languagePair":{
               "from":{
                  "id":"505037985fe01ac20407b7fb",
                  "apiVersion":null,
                  "code":"eng",
                  "name":"English",
                   "fullName":"English",
                  "rightToLeft":false
               },
               "to":{
                  "id":"505037985fe01ac20407b814",
                  "apiVersion":null,
                  "code":"por",
                   "name":"Portuguese",
                  "fullName":"Portuguese",
                  "rightToLeft":false
               },
               "domainDescription":null,
               "domainCode":null
            },
            "activity":"translation"
         }
      ],
       "Q2":[
         {
            "languagePair":{
               "from":{
                  "id":"505037985fe01ac20407b81f",
                  "apiVersion":null,
                  "code":"spa",
                  "name":"Spanish",
                  "fullName": "Spanish; Castilian",
                  "rightToLeft":false
               },
               "to":{
                  "id":"505037985fe01ac20407b7fb",
                  "apiVersion":null,
                  "code":"eng",
                  "name":"English",
                  "fullName": "English",
                  "rightToLeft":false
               },
               "domainDescription":"medical",
               "domainCode":"MTAwMA"
            },
            "activity":"translation"
         }
      ]
   }
}

View Languages (only domain specific Language Pairs)

curl -H "Authorization: LC apiKey=LanguageCloudAPIKey" "https://lc-api.sdl.com/languages?quality=Q2" 
{
   "languageExpertise":{
      "Q2":[
         {
            "languagePair":{
               "from":{
                  "id":"505037985fe01ac20407b81f",
                  "apiVersion":null,
                  "code":"spa",
                  "name":"Spanish",
                  "fullName": "Spanish; Castilian",
                  "rightToLeft":false
               },
               "to":{
                  "id":"505037985fe01ac20407b7fb",
                  "apiVersion":null,
                  "code":"eng",
                  "name":"English",
                  "fullName": "English",
                  "rightToLeft":false
               },
               "domainDescription":"medical",
               "domainCode":"MTAwMA"
            },
            "activity":"translation"
         }
      ]
   }
}

View Machine Translation Engines

HTTP METHOD GET
URL /translation-engines
CONTENT TYPE application/json
DESCRIPTION View Machine Translation Engines

Retrieve all the available machine translation engines, including Generic machine translation, Industry-specific engines, which are applicable to particular vertical markets (e.g. Travel, Automotive) or machine translation engines specifically created for one customer, based on the Account�s subscription.

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

You must be authenticated in order to make this call

Code: 403

You must be authorized in order to make this call

Code: 422

Your call contains invalid data

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
url engineType The type of the engines you want to retrieve. Accepted values: 'baseline', 'vertical', 'custom'. If not
specified, all the engines available through the account's subscription are returned, regardless of the type.
true
Sample

View Machine Translation Engines

curl -H "Authorization: LC apiKey=LanguageCloudAPIKey"
        "https://lc-api.sdl.com/translation-engines?engineType=baseline&engineType=vertical&engineType=custom" 
{
    {
       "translationEngines": [
          {
             "to": {
                "rightToLeft": false,
                "name": "Portuguese",
                "locale": "pt",
                "active": true,
                "fullName": "Portuguese",
                "code": "por",
                "comments": null
            },
             "domainDescription": null,
             "toLanguageId": "505037985fe01ac20407b814",
             "trustScoreEnabled": false,
             "from": {
                "rightToLeft": false,
                "name": "English",
                "locale": "en",
                "active": true,
                "fullName": "English",
                "code": "eng",
                "comments": null
            },
             "type": "BASELINE",
             "fromLanguageId": "505037985fe01ac20407b7fb",
             "domainCode": null
         },
          {
             "to": {
                "rightToLeft": false,
                "name": "Spanish",
                "locale": "es",
                "active": true,
                "fullName": "Spanish",
                "code": "spa",
                "comments": null
            },
             "domainDescription": "english -> spanish",
             "toLanguageId": "505037985fe01ac20407b81f",
             "trustScoreEnabled": true,
             "from": {
                "rightToLeft": false,
                "name": "English",
                "locale": "en",
                "active": true,
                "fullName": "English",
                "code": "eng",
                "comments": null
            },
             "type": "VERTICAL",
             "fromLanguageId": "505037985fe01ac20407b7fb",
             "domainCode": "MTAxMA"
         }
      ],
       "totalCount": 2
   }
}

Detect Language

HTTP METHOD POST
URL /detect-language
CONTENT TYPE application/json
DESCRIPTION Detect Language

Identify the language of input text.

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

You must be authenticated in order to make this call

Code: 500

Checked exception related to application functionality.

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
body text The input text for language identification. A maximum of 10k characters will be used to detect the language. The text must be URL encoded. false
Sample

Detect language for some given text

curl -X POST -H "Content-Type: application/json" -H "Authorization: LC apiKey=LanguageCloudAPIKey"
        https://lc-api.sdl.com/detect-language -d '{"text":"My dog is green"}'
        
{
   "totalCount":2,
   "result":[
      {
         "confidence":61.0,
         "language":{
            "threeLetterCode":"eng",
            "languageCode":"en",
            "defaultSpecificLanguageCode":"en-US",
            "englishName":"English",
            "parentLanguageCode":null,
            "direction":"LEFT_TO_RIGHT"
         }
      },
      {
         "confidence":39.0,
         "language":{
            "threeLetterCode":"fin",
            "languageCode":"fi",
            "defaultSpecificLanguageCode":"fi-FI",
            "englishName":"Finnish",
            "parentLanguageCode":null,
            "direction":"LEFT_TO_RIGHT"
         }
      }
   ]
}

Detect Machine Translation Engines

HTTP METHOD POST
URL /translation-engines/detect
CONTENT TYPE application/json
DESCRIPTION Detect Machine Translation Engines

Retrieve a list of machine translation engines that can be used to translate text when the language of the input text is unknown. The source language is detected based on the input text. Any engines available through the account�s subscription with a matching source language are returned.

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

You must be authenticated in order to make this call

Code: 500

Checked exception related to application functionality.

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
body text The input text for language identification. A maximum of 10k characters will be used to detect the language. The text must be URL encoded. false
body engineType The type of the engines you want to retrieve. Accepted values: 'baseline', 'vertical', 'custom'. If not specified, all the engines available through the account's subscription are returned, regardless of the type. true
Sample

Detect machine translation engines based on input text in an unknown language

curl -X POST -H "Content-Type: application/json" -H
        "Authorization: LC apiKey=LanguageCloudAPIKey" https://lc-api.sdl.com/translation-engines/detect -d '{"text":"Mi perro
        caliente", "engineType":["custom","baseline"]}' 
{
   "totalCount":1,
   "result":[
      {
         "confidence":65.0,
         "engines":[
            {
               "trustScoreEnabled" :false,
               "from":{
                  "code":"spa",
                  "locale":"es",
                  "name":"Spanish" ,
                  "fullName":"Spanish",
                  "comments":null,
                  "active":true,
                  "rightToLeft":false
               },
               "fromLanguageId":"505037985fe01ac20407b81f",
               "to":{
                  "code" :"eng",
                  "locale":"en-US",
                  "name":"English",
                  "fullName":"English",
                  "comments" :null,
                  "active":true,
                  "rightToLeft":false
               },
               "toLanguageId" :"505037985fe01ac20407b7fb",
               "domainCode":null,
               "domainDescription":"spanish -> english",
               "type":"BASELINE"
            }
         ]
      }
   ]
}

Machine Translation


Translate Text

HTTP METHOD POST
URL /translate
CONTENT TYPE application/json
DESCRIPTION Translate Text

Text translation call between two languages defined using ISO 639(3 char code) or language id.
Note: The size limit for the text is 4500 bytes.

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 403

You must be authorized in order to make this call

Code: 422

Your call contains invalid data

Code: 500

There was an error during machine translation

Code: 501

A conflict occurred during your request

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
body text The text to be translated. The text must be URL encoded. false
body from The ISO 639(3 char code) or the internal language id of the source language false
body to The ISO 639(3 char code) or the internal language id of the destination language false
body inputFormat Input format for the translation, can be:html, plain true
body domainCode Unique identifier of a machine translation engine which is applicable to particular vertical markets (e.g. Travel, Automotive) or specifically created for one customer true
body termbaseIds Termbases to be used when translating true
Sample

Translate Text

curl -X POST -H "Content-type: application/json" -H
        "Authorization: LC apiKey=LanguageCloudAPIKey" -d '{"text" : "establish", "from" : "eng", "to" : "fra",
        "termbaseIds": ["52a240e484ae30abf3d664ce"]}'
        https://lc-api.sdl.com/translate 
{
    "to":"fra",
   "translation" : "Établir",
   "from":"eng",
   "partialTranslation":false,
   "wordCount":1,
   "charcount":9
}

Translate Array of Text

HTTP METHOD POST
URL /translations
CONTENT TYPE application/json
DESCRIPTION Translate Array of Text

Array of text translation call between two languages defined using ISO 639(3 char code) or language id
Note: The size limit for each text is 4500 bytes.

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 403

You must be authorized in order to make this call

Code: 422

Your call contains invalid data

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
body texts The array of text to be translated. The text must be URL encoded. false
body from The ISO 639(3 char code) or the internal language id of the source language false
body to The ISO 639(3 char code) or the internal language id of the destination language false
body inputFormat Input format for the translation, can be:html, plain true
body domainCode Unique identifier of a machine translation engine which is applicable to particular vertical markets (e.g. Travel, Automotive) or specifically created for one customer true
body termbaseIds Termbases to be used when translating true
Sample

Translate Text Array

curl -X POST -H "Content-type: application/json" -H
        "Authorization: LC apiKey=LanguageCloudAPIKey" -d '{"texts":["text%20to%20be%20translated", "text%20
        to%20be%20translated"], "from" : "eng", "to" : "fra", "termbaseIds": ["52a240e484ae30abf3d664ce"]}'
        https://lc-api.sdl.com/translations 
{
    "translations": [
       "Texte à traduire",
       "Texte à traduire"
   ],
    "partialTranslation": false,
    "from": "eng",
    "to": "fra",
    "wordCount": 8,
    "charCount": 36
}

Translate File

HTTP METHOD POST
URL /file-translations
CONTENT TYPE multipart/form-data
DESCRIPTION Translate File

File translation call between two languages defined using ISO 639 (3 char code) or language id
Note: Supported file types are .doc, .docx, .xlsx, .pdf, .txt, .ppt, .pptx, .odt, .xml, .htm, .html, .its (for .pdf files, the output will be .docx). The size limit for the file is 5MB.

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

You must be authenticated in order to make this call

Code: 500

Checked exception related to application functionality.

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
body file The actual file false
body from The ISO 639(3 char code) or the internal language id of the source language false
body to The ISO 639(3 char code) or the internal language id of the destination language false
body domainCode Unique identifier of a machine translation engine which is applicable to particular vertical markets (e.g. Travel, Automotive) or specifically created for one customer true
body termbaseIds Termbases to be used when translating true
body computeTrustScore This specifies whether TrustScore is requested or not. Accepted values: true, false. TrustScore™ is an automatic estimation of translation quality, on a scale from 1 to 5. If the parameter is true, but the machine translation engine used for the translation does not support TrustScore, the API call will return HTTP 422 - Unprocessable Entity true
Sample

Translate File

Send file to translation

curl -X POST -H "Content-type: multipart/form-data" -H "Authorization: LC apiKey=LanguageCloudAPIKey" -F
        "from=eng" -F "to=fra" -F "file=@test.txt" https://lc-api.sdl.com/file-translations 
{
   "id": "554b4fdac4aac4481cdab8e4",
    "result": {
      
   },
    "status": "inProgress"
}

Download Translated File

HTTP METHOD GET
URL /file-translations/{translationId}/translated-file
CONTENT TYPE application/octet-stream
DESCRIPTION Download Translated File

Download a translated file by translation id

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

You must be authenticated in order to make this call

Code: 401

Exception to signal lack of authorization for an operation call

Code: 500

Checked exception related to application functionality.

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
url translationId Unique identifier of the file translation false
Sample

Download Translated File

Note: You should redirect the output to a file

curl -H "Authorization: LC apiKey=LanguageCloudAPIKey"
        https://lc-api.sdl.com/file-translations/5176407e132b856177f4c87a/translated-file 
The actual file content will be returned.

File Translation Status

HTTP METHOD GET
URL /file-translations/{translationId}
CONTENT TYPE application/json
DESCRIPTION File Translation Status

View the status of a given file translation

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

You must be authenticated in order to make this call

Code: 401

Exception to signal lack of authorization for an operation call

Code: 500

Checked exception related to application functionality.

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
url translationId Unique identifier of the file translation false
Sample

Get File Translation Status

curl -H "Authorization: LC apiKey=LanguageCloudAPIKey"
        https://lc-api.sdl.com/file-translations/5176407e132b856177f4c87a 
{
   "id": "554b4fdac4aac4481cdab8e4",
    "result": {
       "downloadURL": "https://lc-api.sdl.com/file-translations/554b4fdac4aac4481cdab8e4/translated-file"
   },
    "status": "finished"
}

Projects


Create a Project

HTTP METHOD POST
URL /projects
CONTENT TYPE application/json
DESCRIPTION Create a Project

Create a new project
Note: Project will be deleted after a period of time (2 hours) if not submitted for payment.

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

Exception to signal lack of authorization for an operation call

Code: 403

You must be authorized in order to make this call

Code: 404

The entity you want to process does not exist

Code: 422

Your call contains invalid data

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
body type Type of the project false
body from The ISO 639(3 char code) or the language id of the source language false
body to The ISO 639(3 char code) or the language id of the destination language false
body name The project name true
body description A short description for the project true
body notificationCallbackURL No longer supported. true
body autoAccept The project autoAccept policy. Defaukt for machine translation will be true. true
body termbaseIds List of termbases used for translation true
Sample

Create a project

curl -X POST -H "Content-Type: application/json" -H "Authorization: LC apiKey=LanguageCloudAPIKey" -d '{"type" :
        "translationProject", "from" : "eng", "to" : "fra", "name" : "MyProject", "description" : "My first project", "termbaseIds": ["52a240e484ae30abf3d664ce"]}' https://lc-api.sdl.com/projects
        
{
    "project" : {
       "type" : "translationProject",
       "id" : "5176407e132b856177f4c87a",
       "notificationCallbackURL" : "https://some.api.com/endpoint",
       "autoAcceptProject" : null,
       "creationDate" : "2013-04-24 11:13:09",
       "lastModifiedDate" : null,
       "description" : null,
       "projectName" : null,
       "currentState" : null,
       "stateHistory" : [
          {
             "state" : "temporary",
             "date" : "2013-04-24 11:13:09",
             "comment" : null,
             "paymentTimeStamp" : 0
         }
      ],
       "price" : 200,
       "preApprove" : false,
       "jobs" : null,
       "from" : "505037985fe01ac20407b7fb",
       "to" : "301037985fe01ac20337b7fa",
       "customerProfileId" : "5176407e132b856177f4c87a",
       "quality" : null ,
       "paymentAttemptId" : null,
       "paymentTimestamp" : 0,
       "sandbox" : false
   },
    "paymentDetails" : null,
    "uploadToken" : "Uiwxj9GAnsX4cHW5wYRywQ%253D%253D",
    "sid" : null
}

Add Files to Project

HTTP METHOD PUT
URL /projects/{projectId}/files
CONTENT TYPE application/json
DESCRIPTION Add Files to Project

Process an uploaded list of files and associate them to a given project

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

Exception to signal lack of authorization for an operation call

Code: 404

The entity you want to process does not exist

Code: 420

Your call tried to change the state of an entity in an invalid way

Code: 422

Your call contains invalid data

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
url projectId Id of the project false
body fileIds A list of stored file ids. Ids are separated by ',' false
Sample

Add Files to Project

curl -X PUT -H "Content-Type: application/json" -H "Authorization: LC apiKey=LanguageCloudAPIKey" -d '{
        "fileIds" : [ "1234407e132b85617asdf872" ] }' https://lc-api.sdl.com/projects/5176407e132b856177f4c87a/files 
{
    "fileDetails" : [
       {
          "fileId" : "1234407e132b85617asdf872",
          "success" : true
      }
   ]
}

Delete Files from Project

HTTP METHOD DELETE
URL /projects/{projectId}/files/{fileIds}
CONTENT TYPE application/json
DESCRIPTION Delete Files from Project

Remove files from a project. Only valid until a project has been started.

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

Exception to signal lack of authorization for an operation call

Code: 404

The entity you want to process does not exist

Code: 420

Your call tried to change the state of an entity in an invalid way

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
url projectId Id of the project false
url fileIds list of file ids to be processed. Ids are separated by ',' false
Sample

Delete Files from Project

curl -X DELETE -H "Authorization: LC apiKey=LanguageCloudAPIKey"
        https://lc-api.sdl.com/projects/5176407e132b856177f4c87a/files/1234407e132b85617asdf872 
{
    "fileDetails" : [
       {
          "fileId" : "1234407e132b85617asdf872",
          "success" : true
      }
   ]
}

View Project

HTTP METHOD GET
URL /projects/{projectId}
CONTENT TYPE application/json
DESCRIPTION View Project

View the project by project id

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

Exception to signal lack of authorization for an operation call

Code: 404

The entity you want to process does not exist

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
url projectId Id of the project to view false
Samples

View project before an order is placed

curl -H "Authorization: LC apiKey=LanguageCloudAPIKey"
        https://lc-api.sdl.com/projects/51d3113de4b0ba2b68901c5a?returnPaymentDetails=true 
{
    "project" : {
       "type" : "translationProject",
       "id" : "51d3113de4b0ba2b68901c5a",
       "notificationCallbackURL" : "https://some.api.com/endpoint",
       "autoAcceptProject" : null,
       "creationDate" : "2013-04-24 11:13:09",
       "lastModifiedDate" : null,
       "description" : null,
       "projectName" : null,
       "currentState" : null,
       "stateHistory" : [
          {
             "state" : "temporary",
             "date" : "2013-04-24 11:13:09",
             "comment" : null,
             "paymentTimeStamp" : 0
         },
          {
             "state" : "paid",
             "date" : "2013-04-24 11:21:09",
             "comment" : null,
             "paymentTimeStamp" : 0
         },
          {
             "state" : "inProgress",
             "date" : "2013-04-24 12:13:09",
             "comment" : null,
             "paymentTimeStamp" : 0
         }
      ],
       "price" : 200,
       "preApprove" : false,
       "jobs" : null,
       "from" : "505037985fe01ac20407b7fb",
       "to" : "301037985fe01ac20337b7fa",
       "customerProfileId" : "5176407e132b856177f4c87a",
       "quality" : "Q1",
       "paymentAttemptId" : null,
       "paymentTimestamp" : 0,
       "fileDetails" : [
          {
             "fileId" : "120037985fe01ac20407b7fb",
             "xliffFileId" : null,
             "wordCount" : 12312,
             "fileName" : "poetry.doc",
             "size" : 12312,
             "failureCode" : null,
             "note" : null,
             "price" : 200,
             "duration" : null,
             "formattedPrice" : null,
             "formattedDuration" : null
         },
          {
             "fileId" : "887037985fe01ac20407b7fb",
             "xliffFileId" : null,
             "wordCount" : 45312,
             "fileName" : "novel.txt",
             "size" : 11122,
             "failureCode" : null,
             "note" : null,
             "price" : 200,
             "duration" : null,
             "formattedPrice" : null,
             "formattedDuration" : null
         }
      ],
       "sandbox" : false
   },
    "paymentDetails" : {
       "formattedProjectPrice" : "31.37",
       "formattedWalletAmount" : "20.00",
       "formattedRequiredAmount" : "11.73",
       "requiredAmount" : 11730
   },
    "uploadToken" : null,
    "sid" : null
}

View project after an order is placed

curl -H "Authorization: LC apiKey=LanguageCloudAPIKey"
        https://lc-api.sdl.com/projects/5176407e132b856177f4c87a?returnPaymentDetails=true 
{
    "project" : {
       "type" : "translationProject",
       "id" : "5176407e132b856177f4c87a",
       "notificationCallbackURL" : "https://some.api.com/endpoint",
       "autoAcceptProject" : null,
       "creationDate" : "2013-04-24 11:13:09",
       "lastModifiedDate" : null,
       "description" : null,
       "projectName" : null,
       "currentState" : null,
       "stateHistory" : [
          {
             "state" : "temporary",
             "date" : "2013-04-24 11:13:09",
             "comment" : null,
             "paymentTimeStamp" : 0
         },
          {
             "state" : "paid",
             "date" : "2013-04-24 11:21:09",
             "comment" : null,
             "paymentTimeStamp" : 0
         },
          {
             "state" : "inProgress",
             "date" : "2013-04-24 12:13:09",
             "comment" : null,
             "paymentTimeStamp" : 0
         }
      ],
       "price" : 200,
       "preApprove" : false,
       "from" : "505037985fe01ac20407b7fb",
       "to" : "301037985fe01ac20337b7fa",
       "customerProfileId" : "5176407e132b856177f4c87a",
       "quality" : "Q1",
       "paymentAttemptId" : null,
       "paymentTimestamp" : 0,
       "fileDetails" : {
          "fileId" : "120037985fe01ac20407b7fb",
          "xliffFileId" : null,
          "wordCount" : 12312,
          "fileName" : "poetry.doc",
          "size" : 12312,
          "failureCode" : null,
          "note" : null,
          "price" : 200,
          "duration" : 2,
          "formattedPrice" : 0.20,
          "formattedDuration" : 2
      },
      "jobs" : [
          {
             "type" : "translation",
             "id" : "5176407e132b856177f4c87a",
             "notificationCallbackURL" : "https://some.api.com/endpoint",
             "autoAcceptJob" : false,
             "creationDate" : "2013-04-24 11:21:10",
             "lastModifiedDate" : null,
             "deadline" : null,
             "from" : null,
             "to" : null,
             "price" : 200,
             "currentState" : "inProgress",
             "stateHistory" : [
                {
                   "state" : "pending",
                   "date" : "2013-04-24 11:13:09",
                   "translatorProfileId" : null,
                   "customerProfileId" : null,
                   "comment" : "tihs is a comment",
                   "rating" : 0,
                   "disputeAction" : null,
                   "cancelDispute" : false
               },
                {
                   "state" : "inProgress",
                   "date" : "2013-04-24 11:21:11",
                   "translatorProfileId" : null,
                   "customerProfileId" : null,
                   "comment" : "another comment",
                   "rating" : 0,
                   "disputeAction" : null,
                   "cancelDispute" : false
               },
                {
                   "state" : "pendingReview",
                   "date" : "2013-04-24 12:21:09",
                   "translatorProfileId" : null,
                   "customerProfileId" : null,
                   "comment" : "extra comment",
                   "rating" : 0,
                   "disputeAction" : null,
                   "cancelDispute" : false
               }
            ],
             "sourceFileId" : null,
             "sourceFile" : null,
             "translationFileId" : null,
             "translationFile" : null,
             "translationFileName" : null,
             "projectId" : null,
             "fileDetails" : {
                "fileId" : "120037985fe01ac20407b7fb",
                "xliffFileId" : null,
                "wordCount" : 12312,
                "fileName" : "poetry.doc",
                "size" : 12312,
                "failureCode" : null,
                "note" : null,
                "price" : 200,
                "duration" : 2,
                "formattedPrice" : 0.20,
                "formattedDuration" : 2
            },
             "jobComments" : [
                {
                   "profileId" : "505037985fe01ac20407b7fb",
                   "text" : "this is a comment",
                   "date" : "2013-04-24 11:13:09",
                   "profileType" : "customer",
                   "commenterType" : "customer"
               }
            ],
             "jobIdInOrder" : null,
             "customerProfileId" : "5176407e132b856177f4c87a",
             "quality" : "Q1",
             "dateUntilAutoAcceptJob" : null,
             "translatorProfileId" : null,
             "translatorProfile" : null
         }
      ],
       "sandbox" : false
   },
    "paymentDetails" : {
       "formattedProjectPrice" : "31.37",
       "formattedWalletAmount" : "20.00",
       "formattedRequiredAmount" : "11.73",
       "requiredAmount" : 11730
   },
    "uploadToken" : null,
    "sid" : null

View Projects

HTTP METHOD GET
URL /projects
CONTENT TYPE application/json
DESCRIPTION View Projects

View all projects of the current user

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

Exception to signal lack of authorization for an operation call

Code: 404

The entity you want to process does not exist

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
Sample

View Projects

curl -H "Authorization: LC apiKey=LanguageCloudAPIKey" https://lc-api.sdl.com/projects 
{
    "totalCount" : 1,
    "projects" : [
       {
          "type" : "translationProject",
          "id" : "5176407e132b856177f4c87a",
          "notificationCallbackURL" : "https://some.api.com/endpoint",
          "autoAcceptProject" : null,
          "creationDate" : "2013-04-24 11:13:09",
          "lastModifiedDate" : null,
          "description" : null,
          "projectName" : null,
          "currentState" : null,
          "stateHistory" : [
             {
                "state" : "temporary",
                "date" : "2013-04-24 11:13:09",
                "comment" : null,
                "paymentTimeStamp" : 0
            },
             {
                "state" : "paid",
                "date" : "2013-04-24 11:21:09",
                "comment" : null,
                "paymentTimeStamp" : 0
            },
             {
                "state" : "inProgress",
                "date" : "2013-04-24 12:13:09",
                "comment" : null,
                "paymentTimeStamp" : 0
            }
         ],
          "price" : 200,
          "preApprove" : false,
          "jobs" : null,
          "from" : "505037985fe01ac20407b7fb",
          "to" : "301037985fe01ac20337b7fa",
          "customerProfileId" : "5176407e132b856177f4c87a",
          "quality" : "Q1",
          "paymentAttemptId" : null,
          "paymentTimestamp" : 0,
          "fileDetails" : [
             {
                "fileId" : "120037985fe01ac20407b7fb",
                "xliffFileId" : null,
                "wordCount" : 12312,
                "fileName" : "poetry.doc",
                "size" : 12312,
                "failureCode" : null,
                "note" : null,
                "price" : 200,
                "duration" : null,
                "formattedPrice" : null,
                "formattedDuration" : null
            },
             {
                "fileId" : "887037985fe01ac20407b7fb",
                "xliffFileId" : null,
                "wordCount" : 45312,
                "fileName" : "novel.txt",
                "size" : 11122,
                "failureCode" : null,
                "note" : null,
                "price" : 200,
                "duration" : null,
                "formattedPrice" : null,
                "formattedDuration" : null
            }
         ],
          "sandbox" : false
      }
   ]
}

Cancel a Project

HTTP METHOD DELETE
URL /projects/{projectId}
CONTENT TYPE application/json
DESCRIPTION Cancel a Project

Cancel an existing project by project id
Note: If the project has not been started, the project will be deleted, otherwise project remains in cancelled state.
Note: If the project is in translation process, the project cannot be cancelled.

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

Exception to signal lack of authorization for an operation call

Code: 404

The entity you want to process does not exist

Code: 420

Your call tried to change the state of an entity in an invalid way

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
url projectId Id of the project false
Sample

Cancel a project

curl -X DELETE -H "Authorization: LC apiKey=LanguageCloudAPIKey"
        https://lc-api.sdl.com/projects/5176407e132b856177f4c87a 
{
    "project" : {
       "type" : "translationProject",
       "id" : "5176407e132b856177f4c87a",
       "notificationCallbackURL" : "https://some.api.com/endpoint",
       "autoAcceptProject" : null,
       "creationDate" : "2013-04-24 11:13:09",
       "lastModifiedDate" : null,
       "description" : null,
       "projectName" : null,
       "currentState" : "cancelled",
       "stateHistory" : [
          {
             "state" : "temporary",
             "date" : "2013-04-24 11:13:09",
             "comment" : null,
             "paymentTimeStamp" : 0
         },
          {
             "state" : "",
             "date" : "2013-04-24 11:21:09",
             "comment" : null,
             "paymentTimeStamp" : 0
         },
          {
             "state" : "cancelled",
             "date" : "2013-04-24 12:13:09",
             "comment" : null,
             "paymentTimeStamp" : 0
         }
      ],
       "price" : 200,
       "preApprove" : false,
       "jobs" : null,
       "from" : "505037985fe01ac20407b7fb",
       "to" : "301037985fe01ac20337b7fa",
       "customerProfileId" : "5176407e132b856177f4c87a",
       "quality" : "Q1",
       "paymentAttemptId" : null,
       "paymentTimestamp" : 0,
       "fileDetails" : [
          {
             "fileId" : "120037985fe01ac20407b7fb",
             "xliffFileId" : null,
             "wordCount" : 12312,
             "fileName" : "poetry.doc",
             "size" : 12312,
             "failureCode" : null,
             "note" : null,
             "price" : 200,
             "duration" : null,
             "formattedPrice" : null,
             "formattedDuration" : null
         },
          {
             "fileId" : "887037985fe01ac20407b7fb",
             "xliffFileId" : null,
             "wordCount" : 45312,
             "fileName" : "novel.txt",
             "size" : 11122,
             "failureCode" : null,
             "note" : null,
             "price" : 200,
             "duration" : null,
             "formattedPrice" : null,
             "formattedDuration" : null
         }
      ],
       "sandbox" : false
   },
    "paymentDetails": null,
    "uploadToken" : null,
    "sid" : null
}

File Management


Upload File

HTTP METHOD POST
URL /files
CONTENT TYPE multipart/form-data
DESCRIPTION Upload File

Upload a file in the system and get a handle for it. The request format is multipart/form-data.
Note: If the file is not associated with a paid project it will be deleted after 2 hours.
Note: A file maximum size can be 5MB.
Note: possible extensions: doc, docx, pdf, txt, ppt, pptx, odt, xml, htm, html, its.

EXCEPTIONS Code: 400

Your call is in an invalid format

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
form file the actual file false
form projectId The project to attach to true
form token The upload token returned at project creation true
Sample

Upload File

Upload a file in the system and get a handle for it. The request format is multipart/form-data.

curl -X POST -F "file=@fileName.doc" -F "projectId=75ab8687fa858c" -H "Content-Type: multipart/form-data" -H
        "Authorization: LC apiKey=LanguageCloudAPIKey" https://lc-api.sdl.com/files 
{
    "storedFiles": [
      {
          "id": "527b91164a23790cd7e62581",
          "creationDate": "2013-11-07 13:09:41",
          "lastModifiedDate": "2013-11-07 13:09:41",
          "apiVersion": "1.0",
          "fileName": "test1.txt",
          "status": "TEMP",
          "extension": "txt",
          "encoding": null,
          "size": 21,
          "sandbox": false,
          "associatedFiles": null,
          "temporary": true
      }
   ]
}

Get File Metadata

HTTP METHOD GET
URL /files/{storedFileId}
CONTENT TYPE application/json
DESCRIPTION Get File Metadata

Get a file's metadata by its stored file id

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

You must be authenticated in order to make this call

Code: 401

Exception to signal lack of authorization for an operation call

Code: 404

The entity you want to process does not exist

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
url storedFileId Id of the stored file false
Sample

Get File Metadata

curl -H "Authorization: LC apiKey=LanguageCloudAPIKey" https://lc-api.sdl.com/files/51d34084e4b0d735a06242a4
        
{
    "storedFile" : {
       "id": "527b91164a23790cd7e62581",
       "creationDate": "2013-11-07 13:09:41",
       "lastModifiedDate": "2013-11-07 13:09:41",
       "apiVersion": "1.0",
       "fileName": "test1.txt",
       "status": "TEMP",
       "extension": "txt",
       "encoding": null,
       "size": 21,
       "sandbox": false,
       "associatedFiles": null,
       "temporary": true
   }
}

Download File

HTTP METHOD GET
URL /files/{storedFileId}/file
CONTENT TYPE application/octet-stream
DESCRIPTION Download File

Download a file by its stored file id

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

You must be authenticated in order to make this call

Code: 401

Exception to signal lack of authorization for an operation call

Code: 404

The entity you want to process does not exist

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
url storedFileId Id of the stored file false
Sample

Download File

Note: You should redirect the output to a file

curl -H "Authorization: LC apiKey=LanguageCloudAPIKey" https://lc-api.sdl.com/files/5176407e132b856177f4c87a/file
        
The actual file content will be returned.

Quotes and Orders


Place an Order

HTTP METHOD PUT
URL /projects/{projectId}/orders
CONTENT TYPE application/json
DESCRIPTION Place an Order

Place an order for the project at a specified quality level. All 'files' included in the project become translation 'jobs'.

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

Exception to signal lack of authorization for an operation call

Code: 404

The entity you want to process does not exist

Code: 420

Your call tried to change the state of an entity in an invalid way

Code: 422

Your call contains invalid data

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
url projectId Id of the project to be submitted false
body qualityLevel The translation quality: machine translation 'Q1', domain specific machine translation 'Q2'. false
body domainCode Unique identifier of a machine translation engine which is applicable to particular vertical markets (e.g. Travel, Automotive) or specifically created for one customer true
Samples

Place an Order

curl -X PUT -H "Content-Type: application/json" -H "Content-Type: application/json" -H
        "Authorization: LC apiKey=LanguageCloudAPIKey" -d '{"qualityLevel" : "Q2"}' https://lc-api.sdl.com/projects/5176407e132b856177f4c87a/orders
        
{
    "project" : {
       "type" : "translationProject",
       "id" : "5176407e132b856177f4c87a",
       "notificationCallbackURL" : "https://some.api.com/endpoint",
       "autoAcceptProject" : null,
       "creationDate" : "2013-04-24 11:13:09",
       "lastModifiedDate" : null,
       "description" : null,
       "projectName" : null,
       "currentState" : "paid",
       "stateHistory" : [
          {
             "state" : "temporary",
             "date" : "2013-04-24 11:13:09",
             "comment" : null,
             "paymentTimeStamp" : 0
         },
          {
             "state" : "paid",
             "date" : "2013-04-24 11:21:09",
             "comment" : null,
             "paymentTimeStamp" : 0
         }
      ],
       "price" : 200,
       "jobs" : [
          {
             "type" : "translation",
             "id" : "5176407e132b856177f4c87a",
             "notificationCallbackURL" : "https://some.api.com/endpoint",
             "autoAcceptJob" : false,
             "creationDate" : "2013-04-24 11:21:10",
             "lastModifiedDate" : null,
             "deadline" : null,
             "from" : null,
             "to" : null,
             "price" : 200,
             "currentState" : "pending",
             "stateHistory" : [
                {
                   "state" : "pending",
                   "date" : "2013-04-24 11:13:09",
                   "translatorProfileId" : null,
                   "customerProfileId" : null,
                   "comment" : "tihs is a comment",
                   "rating" : 0,
                   "disputeAction" : null,
                   "cancelDispute" : false
               }
            ],
             "sourceFileId" : null,
             "sourceFile" : null,
             "translationFileId" : null,
             "translationFile" : null,
             "translationFileName" : null,
             "projectId" : null,
             "fileDetails" : {
                "fileId" : "120037985fe01ac20407b7fb",
                "xliffFileId" : null,
                "wordCount" : 12312,
                "fileName" : "poetry.doc",
                "size" : 12312,
                "failureCode" : null,
                "note" : null,
                "price" : 200,
                "duration" : 2,
                "formattedPrice" : 0.20,
                "formattedDuration" : 2
            },
             "jobComments" : null,
             "jobIdInOrder" : null,
             "customerProfileId" : "5176407e132b856177f4c87a",
             "quality" : "Q1",
             "dateUntilAutoAcceptJob" : null,
             "translatorProfileId" : null,
             "translatorProfile" : null
         }
      ],
       "from" : "505037985fe01ac20407b7fb",
       "to" : "301037985fe01ac20337b7fa",
       "customerProfileId" : "5176407e132b856177f4c87a",
       "quality" : "Q1",
       "paymentAttemptId" : null,
       "paymentTimestamp" : 0,
       "fileDetails" : [
          {
             "fileId" : "120037985fe01ac20407b7fb",
             "xliffFileId" : null,
             "wordCount" : 12312,
             "fileName" : "poetry.doc",
             "size" : 12312,
             "failureCode" : null,
             "note" : null,
             "price" : 200,
             "duration" : null,
             "formattedPrice" : null,
             "formattedDuration" : null
         },
          {
             "fileId" : "887037985fe01ac20407b7fb",
             "xliffFileId" : null,
             "wordCount" : 45312,
             "fileName" : "novel.txt",
             "size" : 11122,
             "failureCode" : null,
             "note" : null,
             "price" : 200,
             "duration" : null,
             "formattedPrice" : null,
             "formattedDuration" : null
         }
      ],
       "sandbox" : false
   },
    "paymentDetails": null,
    "uploadToken" : null,
    "sid" : null
}

Place an order fails with a generic error

curl -X PUT -H "Content-Type: application/json" -H "Content-Type: application/json" -H
        "Authorization: LC apiKey=LanguageCloudAPIKey" -d '{"qualityLevel" : "Q2"}' https://lc-api.sdl.com/projects/5176407e132b856177f4c87a/orders
        
{
   "errorCode": "FLOW_EXCEPTION",
    "message": "Failure in processing the payment.",
    "details": [
      "payment.process.failed"
   ]
}

Jobs


View Job

HTTP METHOD GET
URL /jobs/{jobId}
CONTENT TYPE application/json
DESCRIPTION View Job

View job by job id

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

You must be authenticated in order to make this call

Code: 401

Exception to signal lack of authorization for an operation call

Code: 404

The entity you want to process does not exist

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
url jobId Id of the job to view false
Sample

View Job

curl -X GET -H "Content-Type: application/json" -H "Authorization: LC apiKey=LanguageCloudAPIKey"
        https://lc-api.sdl.com/jobs/2326407e132b856177f4c87a 
{
    "job" : {
       "type" : "translation",
       "id" : "2326407e132b856177f4c87a",
       "creationDate" : "2013-04-24 11:13:09",
       "lastModifiedDate" : null,
       "version" : null,
       "deadline" : null,
       "from" : null,
       "to" : null,
       "price" : 12,
       "currentState" : "inProgress",
       "notificationCallbackURL" : "https://some.api.com/endpoint",
       "autoAcceptJob": true,
       "stateHistory" : [
          {
             "state" : "pending",
             "date" : "2013-04-24 11:13:09",
             "translatorProfileId" : null,
             "customerProfileId" : null,
             "comment" : "tihs is a comment",
             "rating" : 0,
             "disputeAction" : null,
             "cancelDispute" : false
         },
          {
             "state" : "inProgress",
             "date" : "2013-04-26 08:00:03",
             "translatorProfileId" : null,
             "customerProfileId" : null,
             "comment" : "another comment",
             "rating" : 0,
             "disputeAction" : null,
             "cancelDispute" : false
         },
          {
             "state" : "pendingReview",
             "date" : "2013-04-26 09:20:00",
             "translatorProfileId" : null,
             "customerProfileId" : null,
             "comment" : "extra comment",
             "rating" : 0,
             "disputeAction" : null,
             "cancelDispute" : false
         },
          {
             "state" : "pendingDispute",
             "date" : "2013-04-26 14:11:00",
             "translatorProfileId" : null,
             "customerProfileId" : null,
             "comment" : "yet another comment",
             "rating" : 0,
             "disputeAction" : null,
             "cancelDispute" : false
         }
      ],
       "sourceFileId" : null,
       "sourceFile" : null,
       "translationFileId" : null,
       "translationFile" : null,
       "translationFileName" : null,
       "projectId" : null,
       "fileDetails" : {
          "fileId" : "120037985fe01ac20407b7fb",
          "xliffFileId" : null,
          "wordCount" : 12312,
          "fileName" : "poetry.doc",
          "size" : 12312,
          "failureCode" : null,
          "note" : null,
          "price" : 200,
          "duration" : null,
          "formattedPrice" : null,
          "formattedDuration" : null
      },
       "jobComments" : [
          {
             "profileId" : "505037985fe01ac20407b7fb",
             "text" : "this is a comment",
             "date" : "2013-04-24 11:13:09",
             "profileType" : "customer",
             "commenterType" : "customer"
         }
      ],
       "jobIdInOrder" : null,
       "customerProfileId" : null,
       "quality" : "Q2",
       "dateUntilAutoAcceptJob" : null,
       "customerProfile" : null,
       "translatorProfileId" : null,
       "translatorProfile" : null
   }
}

Terminology Management


Create a Termbase

HTTP METHOD POST
URL /termbases
CONTENT TYPE application/json
DESCRIPTION Create a Termbase

Create a new Termbase

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

You must be authenticated in order to make this call

Code: 401

Exception to signal lack of authorization for an operation call

Code: 403

You must be authorized in order to make this call

Code: 404

The entity you want to process does not exist

Code: 422

Your call contains invalid data

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
body name The Termbase name false
body description A description for the Termbase true
body languages The list of languages supported by the Termbase false
Sample

Create a Termbase

curl -X POST -H "Content-Type: application/json" -H "Authorization: LC apiKey=LanguageCloudAPIKey" -d '{
        "name" : "MyTermbase", "description" : "This is my first Termbase", "languages" : [ "eng", "fra" ] }'
        https://lc-api.sdl.com/termbases 
{
    "termbase" : {
       "id" : "527919b584ae25278e8cefe8" ,
       "creationDate" : "2013-11-05 16:15:49",
       "lastModifiedDate" : "2013-11-05 16:15:49" ,
       "apiVersion" : "1.0",
       "name" : "MyTermbase",
       "description" : "This is my first Termbase",
       "languages" : [
          "505037985fe01ac20407b7fb",
          "505037985fe01ac20407b804"
      ],
       "numberOfConcepts" : 0
   }

View Termbase

HTTP METHOD GET
URL /termbases/{termbaseId}
CONTENT TYPE application/json
DESCRIPTION View Termbase

View the Termbase by termbase ID

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

You must be authenticated in order to make this call

Code: 401

Exception to signal lack of authorization for an operation call

Code: 403

You must be authorized in order to make this call

Code: 404

The entity you want to process does not exist

Code: 422

Your call contains invalid data

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
url termbaseId ID of the Termbase to view false
Sample

View Termbase by termbase ID

curl -X GET -H "Content-Type: application/json" -H "Authorization: LC apiKey=LanguageCloudAPIKey"
        https://lc-api.sdl.com/termbases/527919b584ae25278e8cefe8
        
{
    "termbase" : {
       "id" : "527919b584ae25278e8cefe8" ,
       "creationDate" : "2013-11-05 16:15:49",
       "lastModifiedDate" : "2013-11-05 16:15:49" ,
       "apiVersion" : "1.0",
       "name" : "MyTermbase",
       "description" : "This is my first Termbase",
       "languages" : [
         "505037985fe01ac20407b7fb",
          "505037985fe01ac20407b804"
      ],
       "numberOfConcepts" : 0
   }

View Termbases

HTTP METHOD GET
URL /termbases
CONTENT TYPE application/json
DESCRIPTION View Termbases

View all Termbases in the current account

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

You must be authenticated in order to make this call

Code: 403

You must be authorized in order to make this call

Code: 422

Your call contains invalid data

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
Sample

View Termbases

curl -X GET -H "Authorization: LC apiKey=LanguageCloudAPIKey"
         https://lc-api.sdl.com/termbases 
{
   "totalCount": 1,
    "termbases": [
      {
          "id": "527919b584ae25278e8cefe8",
          "name": "MyTermbase",
          "description": "This is my first Termbase"
      }
   ]
}

Delete a Termbase

HTTP METHOD DELETE
URL /termbases/{termbaseId}
CONTENT TYPE application/json
DESCRIPTION Delete a Termbase

Delete an existing Termbase

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

You must be authenticated in order to make this call

Code: 403

You must be authorized in order to make this call

Code: 404

The entity you want to process does not exist

Code: 409

A conflict occurred during your request

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
url termbaseId ID of the Termbase to delete false
Sample

Delete a Termbase

curl -X DELETE -H "Authorization: LC apiKey=LanguageCloudAPIKey"
        https://lc-api.sdl.com/termbases/518a390277af5d819d588e0a 
{
    "deletedTermbase": {
       "termbaseId": "52b41083554d51a3af8fb097",
       "termbaseName": "My Termbase"
   },
   "success": true
}

Delete Concepts

HTTP METHOD DELETE
URL /termbases/{termbaseId}/concepts
CONTENT TYPE application/json
DESCRIPTION Delete Concepts

Delete all concepts in a Termbase

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

You must be authenticated in order to make this call

Code: 403

You must be authorized in order to make this call

Code: 404

The entity you want to process does not exist

Code: 409

A conflict occurred during your request

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
url termbaseId ID of the Termbase to delete all concepts false
Sample

Delete Concepts

curl -X DELETE -H "Authorization: LC apiKey=LanguageCloudAPIKey"
        https://lc-api.sdl.com/termbases/518a390277af5d819d588e0a/concepts 
{
    "termbase": {
       "termbaseId": "52b41083554d51a3af8fb097",
       "termbaseName": "My Termbase"
   },
   "success": true
}

Import into Termbase

HTTP METHOD POST
URL /termbases/{termbaseId}/imports
CONTENT TYPE multipart/form-data
DESCRIPTION Import into Termbase

Import concepts into a Termbase. The file to be imported needs to be compliant with the TBX Basic standard. The request format is multipart/form-data.

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

You must be authenticated in order to make this call

Code: 403

You must be authorized in order to make this call

Code: 404

The entity you want to process does not exist

Code: 422

Your call contains invalid data

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
url termbaseId ID of the Termbase to import into false
form fileFormat Format of the file to be imported into the Termbase false
form file The file to be imported into the Termbase false
Sample

Import into Termbase

curl -X POST -H "Content-Type: multipart/form-data" -H "Authorization: LC apiKey=LanguageCloudAPIKey" -d '{
        "file" : "MyFile.tbx"}'
        https://lc-api.sdl.com/termbases/527919b584ae25278e8cefe8/imports?fileFormat=tbx 
{
    "import" : {
       "id" : "5289f52993e7516fad650980" ,
       "status" : "QUEUED"
   }
}

View Import Status

HTTP METHOD GET
URL /termbases/{termbaseId}/imports/{importId}
CONTENT TYPE application/json
DESCRIPTION View Import Status

View the status of a given import on a specific Termbase

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

You must be authenticated in order to make this call

Code: 403

You must be authorized in order to make this call

Code: 404

The entity you want to process does not exist

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
url termbaseId ID of the Termbase that imports were done into false
url importId ID of the import to be queried false
Sample

View import status

curl -X GET -H "Content-Type: application/json" -H "Authorization: LC apiKey=LanguageCloudAPIKey"
        https://lc-api.sdl.com/termbases/527919b584ae25278e8cefe8/imports/528a0a5993e7516fad650bca
        
{
    "import" : {
       "id" : "528a0a5993e7516fad650bca",
       "status" : "QUEUED"
   }
]
}

View all Imports

HTTP METHOD GET
URL /termbases/{termbaseId}/imports
CONTENT TYPE application/json
DESCRIPTION View all Imports

View all imports for a given Termbase

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

You must be authenticated in order to make this call

Code: 403

You must be authorized in order to make this call

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
url termbaseId ID of the Termbase that imports were done into false
Sample

View import status

curl -X GET -H "Content-Type: application/json" -H "Authorization: LC apiKey=LanguageCloudAPIKey"
        https://lc-api.sdl.com/termbases/52ef99f3554d9e05f656aca8/imports
        
{
    "totalCount": 1,
    "imports": [
      {
         "id": "52ef99f3554d9e05f656aca9",
          "status": "FAILED"
      }
   ]
}

Export Termbase

HTTP METHOD GET
URL /termbases/{termbaseId}/exports
CONTENT TYPE application/json
DESCRIPTION Export Termbase

Export all the concepts in the Termbase to a TBX file. The resulted file is compliant with the TBX Basic standard.

EXCEPTIONS Code: 400

Your call is in an invalid format

Code: 401

You must be authenticated in order to make this call

Code: 403

You must be authorized in order to make this call

Code: 500

Checked exception related to application functionality.

PARAMETERS
TYPE NAME DESCRIPTION OPTIONAL
url termbaseId ID of the Termbase to be exported false
Sample

Export Termbase

Note: You should redirect the output to a file

curl -X GET -H "Content-Type: application/json" -H "Authorization: LC apiKey=LanguageCloudAPIKey"
        https://lc-api.sdl.com/termbases/527919b584ae25278e8cefe8/exports
        
{
   
}

Perform Translation

Machine Translation


Inline Text

Now that you've created an account and generated an API Key, let's translate!

Let's translate "Hello Developers" to French by submitting a real-time translation call to the platform.

First, set the API Key (generated from the previous step) in the Authorization header of the HTTP request.
(e.g. "Authorization: LC apiKey=< Your API Key >")

Second, set the following parameter for the call:

    • text = Hello Developers
    • from = eng
    • to = fra

Lastly, translate it!

Example:

Request:

curl -X POST -H "Content-type: application/json" -H "Authorization: LC apiKey=<YOUR API KEY>" -d '{"text":"Hello Developers", "from":"eng", "to":"fra"}' https://lc-api.sdl.com/translate

Response:

{"translation":"Bonjour aux Développeurs","partialTranslation":false}

You can also translate multiple texts using the array of texts machine translation API (see documentation at API Reference -> Machine Translation -> Translate Array of Text).


The translation platform offers a variety of machine translation services to developers.


Files

In order to translate files through machine translation the following steps need to be followed:

  • 1. Call translate file (see the documentation at API Reference -> Machine Translation -> Translate File)

  • 2. Keep checking the file translation status - when the translation completes successfully, the returned status is "finished" (see the documentation at API Reference -> Machine Translation -> File Translation Status)

  • 3. Download the translated file using the downloadURL received in step 2 (see the documentation at API Reference -> Machine Translation -> Download Translated File)


Note: Translate file allows you to translate a single file. If you need to translate more files, repeat the steps above for each file.