Introduction

Welcome to the Powerling API API.

This API allows for high performance TM & TB management

Generalities

To automate the translation process of our clients, Powerling has developed a REST API. This document describes the different API calls and the way they should be called.

All the API endpoints reply in JSON format with the application/json content-type header.

The POST calls that do not contain files all have to be made using the application/json format.

The POST calls that do contain files have to be made using the multipart/form-data format (the parameters are serialized using separators and binary files are base64-encoded)

The files that you send for translation and that you receive once the translation is complete must all be in one of the following format:

• XLIFF v1.2
• HTML

Authentication

Every API call must be authenticated by passing an authentication token in the header of the request.

The token must be passed in the Authorization header with the Bearer key like so:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here" \
  -H "Authorization: Bearer ***"

api.authorize('***')

Make sure to replace *** with your API key.

Powerling API uses API keys to allow access to the API. You can register a new Powerling API API key on your admin interface.

Kittn expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: ***

Various

Account info

curl "https://api.powerling-tp.com/v1/account" \
  -H "Authorization: Bearer ***"

api.account()

The above command returns JSON structured like this:

{
  "success": true,
  "data": {
    "name": "My account name"
  }
}

Retrieval of information related to the connected account. This call is mostly used to check connectivity to the webservice.

HTTP Request

Supported langs

curl "https://api.powerling-tp.com/v1/supported-langs" \
  -H "Authorization: Bearer ***"

api.supported_langs()

The above command returns JSON structured like this:

{
  "success":true,
  "data":{
    "fr_FR":["en_US"],
    "en_US":["fr_FR","it_IT"]
  }
}

Retrieval of the list of supported languages.

HTTP Request

Order

Create order

curl -X POST "https://api.powerling-tp.com/v1/order/create" \
  -H "Authorization: Bearer ***" \
  --data-raw '{
     "name": "New order",
     "duedate": "2022-01-20T22:59O",
     "metadata": "Additional information",
     "clientref": "123456-578"
  }'

order = api.create_order({
  "name": "New order",
  "duedate": "2022-01-20T22:59O",
  "metadata": "Additional information",
  "clientref": "123456-578"
})

The above command returns JSON structured like this:

{
  "success": true,
  "orderid": 15
}

Creation of a translation order (first step to submit a content for translation)

HTTP Request

JSON body Parameters

Retrieve order

curl "https://api.powerling-tp.com/v1/order/2" \
  -H "Authorization: Bearer ***"

order = api.get_order_by_id(2)

The above command returns JSON structured like this:

{
  "success": true,
  "data": [{
    "id": 15,
    "state": "pending",
    "clientref": "123456-578",
    "sourcelang": "en_US",
    "targetlang": "es_LA"
  }]
}

Retrieval of information related to a given order.

HTTP Request

URL Parameters

Submit order

curl -X POST "https://api.powerling-tp.com/v1/order/1/submit" \
  -H "Authorization: Bearer ***"

order.submit()

The above command returns JSON structured like this:

{
  "success": true
}

Submit the translation order (once all the files have been submitted)

HTTP Request

URL Parameters

Add callback to order

curl -X POST "https://api.powerling-tp.com/v1/order/1/request-callback" \
  -H "Authorization: Bearer ***" \
  --data-raw '{
     "url": "https://example.com/callback",
  }'

url = "https://example.com/callback"
order.add_callback(url)

The above command returns JSON structured like this:

{
  "success": true
}

Adds a callback URL to the order: URL that will be called when the translation of the order is complete (all files have been translated).

HTTP Request

URL Parameters

JSON body Parameters

Cancel callback on order

order.cancel_callback()

The above command returns JSON structured like this:

{
  "success": true
}

Cancels the callback URL to the order.

HTTP Request

URL Parameters

Get order analysis

curl "https://api.powerling-tp.com/v1/order/2/analysis" \
  -H "Authorization: Bearer ***"

order.get_analysis()

The above command returns JSON structured like this:

[]

Retrieval of information related to a given order.

HTTP Request

URL Parameters

Order file

Upload file (binary)

curl -X POST "https://api.powerling-tp.com/v1/order/1/upload-file" \
  -H "Authorization: Bearer ***" \
  -F sourcelang=fr_FR \
  -F targetlang=en_US \
  -F clientref=12345-678 \
  -F file=@my-file.xlf

form = {
  'sourcelang': 'fr_FR',
  'targetlang': 'de_DE',
  'clientref': '1234-567',
  'file': 'my-file.xlf'
}

order.add_bin_file(form)

The above command returns JSON structured like this:

{
  "success": true,
  "fileid": 15
}

Add a file to translate to a previously created order. You must do one call per file per language couple.

This methods allows to upload the file directly in a multipart payload.

HTTP Request

POST https://api.powerling-tp.com/v1/order/{order_id}/upload-file

URL Parameters

Multipart body Parameters

Upload file (public URL)

curl -X POST "https://api.powerling-tp.com/v1/order/1/add-file" \
  -H "Authorization: Bearer ***" \
  --data-raw '{
    "sourcelang": "fr_FR",
    "targetlang": "en_US",
    "clientref": "12345-678",
    "fileurl": "https://example.com/my-file.xlf"
  }'

form = {
  'sourcelang': 'fr_FR',
  'targetlang': 'de_DE',
  'clientref': '1234-567',
  'fileurl': 'https://example.com/my-file.xlf'
}

order.add_bin_file(form)

The above command returns JSON structured like this:

{
  "success": true,
  "fileid": 15
}

Add a file to translate to a previously created order. You must do one call per file per language couple.

This method works by providing the public URL where the file may be downloaded.

HTTP Request

URL Parameters

JSON body Parameters

Upload json file (binary)

curl -X POST "https://api.powerling-tp.com/v1/order/1/add-file" \
  -H "Authorization: Bearer ***" \
  --data-raw '{
    "sourcelang": "fr_FR",
    "targetlang": "en_US",
    "clientref": "12345-678",
    "json_paths": [
      "path.to.my.json.key"
    ],
    "fileurl": "my-file.json"
  }'

form = {
  'sourcelang': 'fr_FR',
  'targetlang': 'de_DE',
  'clientref': '1234-567',
  'json_paths': [
    'path.to.my.json.key'
  ],
  'fileurl': 'my-file.json'
}

order.add_bin_file(form)

The above command returns JSON structured like this:

{
  "success": true,
  "fileid": 15
}

Add a file to translate to a previously created order. You must do one call per file per language couple.

This method works by providing the public URL where the file may be downloaded.

HTTP Request

URL Parameters

JSON body Parameters

Upload json file (public URL)

curl -X POST "https://api.powerling-tp.com/v1/order/1/add-file/json" \
  -H "Authorization: Bearer ***" \
  --data-raw '{
    "sourcelang": "fr_FR",
    "targetlang": "en_US",
    "clientref": "12345-678",
    "json_paths": [
      "path.to.my.json.key"
    ],
    "fileurl": "https://example.com/my-file.json"
  }'

form = {
  'sourcelang': 'fr_FR',
  'targetlang': 'de_DE',
  'clientref': '1234-567',
  'json_paths': [
    'path.to.my.json.key'
  ],
  'fileurl': 'https://example.com/my-file.json'
}

order.add_bin_file(form)

The above command returns JSON structured like this:

{
  "success": true,
  "fileid": 15
}

Add a file to translate to a previously created order. You must do one call per file per language couple.

This method works by providing the public URL where the file may be downloaded.

HTTP Request

URL Parameters

JSON body Parameters

Order file status

curl "https://api.powerling-tp.com/v1/order/1/file/1/status" \
  -H "Authorization: Bearer ***"

file.get_status()

The above command returns JSON structured like this:

{
  "success": true,
  "status": "complete",
  "clientref": "123456-578",
  "sourcelang": "en_US",
  "targetlang": "es_LA"
}

Retrieval of the status of a given file sent for translation.

HTTP Request

URL Parameters

Order file translation download

curl "https://api.powerling-tp.com/v1/order/1/file/1" \
  -H "Authorization: Bearer ***" \
  -o translated.xlf

file.download()

The above command returns the file in binary format.

Download the translated file (available when the status of the file is “complete”)

HTTP Request

URL Parameters

Add callback to order file

curl -X POST "https://api.powerling-tp.com/v1/order/1/file/1/request-callback" \
  -H "Authorization: Bearer ***" \
  --data-raw '{
     "url": "https://example.com/callback",
  }'

url = "https://example.com/callback"
file.add_callback(url)

The above command returns JSON structured like this:

{
  "success": true
}

Adds a callback URL to the order file: URL that will be called when the translation of the specified file is complete.

HTTP Request

URL Parameters

JSON body Parameters

Cancel callback on file

The above command returns JSON structured like this:

Removes the callback URL from the order file.

HTTP Request

URL Parameters

Get file analysis

curl "https://api.powerling-tp.com/v1/order/2/file/4/analysis" \
  -H "Authorization: Bearer ***"

file.get_analysis()

The above command returns JSON structured like this:

[]

Retrieval of information related to a given order.

HTTP Request

URL Parameters

Errors

The PowerTM API uses the following error codes: