API Documentation

• Getting Started
• Libraries
• Authentication
• API URL
• API Requests
• API Response
• API Reference
• Step 1. Upload file to the server
• Step 2. Run conversion task
• Step 3. Get conversion task status
• Step 4. Download result file
• Available Conversion Types
• Need Help?

We provide access to the Conversion Tools services via the HTTP-based REST API using the token authentication. API request and response are formatted in JSON.

We maintain the following official REST API Client libraries:

• conversiontools-node - Conversion Tools Node.js client
• conversiontools-python - Conversion Tools Python client
• conversiontools-php - Conversion Tools PHP client

When account is created we generate the API Token for accessing the Conversion Tools REST API.

API Token can be found at your Profile.

API Token should be passed to HTTP request in the Authorization HTTP header with the Bearer authentication scheme as follows:

Authorization: Bearer <API Token>

The following sample request checking the access to the Conversion Tools REST API:

curl -sSX GET https://a-%SERVER_NAME%-%REGION_NAME%.conversiontools.io/v1/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API Token>"

Conversion Tools REST API is available at:

API Request should contain the following components:

• The HTTP method, one of GET or POST
• Authorization HTTP header with API Token
• Content-Type HTTP header with type application/json
• A JSON request body which depends on the API command, see list of API commands below

The folllowing sample API request creates new conversion task:

curl -sSX POST https://a-%SERVER_NAME%-%REGION_NAME%.conversiontools.io/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API Token>" \
  -d '{
  "type": "convert.website_to_image",
  "options": {
    "url": "http://google.com",
    "image_format": "jpg"
  }
}'

General format of the API response has error field and some optional <data>:

{
  "error": "<error text>",
  <data>
}

In case of success, <error text> will be empty (null), for example:

{
  "error": null,
  "task_id": "4147c475ffe94ec8a11aff9a6a8f437a"
}

In case of error, <error text> will contain the error description, for example:

{
  "error": "Bad request"
}

File conversion process consists of the following 4 steps:

1. Upload file to the server (optional step when URL is provided)
2. Run conversion task
3. Get conversion task status
4. Download the result file

In case when you providing the file by Internet URL - start with a Step 2.

For file upload use a HTTP POST file upload request with the Content-Type: multipart/form-data header.

See sample request below.

Request:

Headers:

Input parameters:

Response:

Success response will contain file_id field, which contains the identifier of the uploaded file:

{
  "error": null,
  "file_id": "be87de1a680c4451a49a72df3fecd3fd"
}

This file_id value should be used in the following step (Run conversion task).

Sample request using curl:

curl -sSX POST https://a-%SERVER_NAME%-%REGION_NAME%.conversiontools.io/v1/files \
  -H "Authorization: Bearer <API Token>" \
  -F "file=@/home/user/Desktop/test.xml"

Please note: -F parameter of curl automatically adding header Content-Type: multipart/form-data to the request.

Request:

Headers:

Input parameters:

options parameters generic for every conversion task:

options parameters specific per conversion task:

Please click on the conversion type to see the list of available options.

The folllowing sample API request creates new conversion task:

curl -sSX POST https://a-%SERVER_NAME%-%REGION_NAME%.conversiontools.io/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API Token>" \
  -d '{
  "type": "convert.website_to_image",
  "options": {
    "url": "http://google.com",
    "image_format": "jpg"
  }
}'

Response:

{
  "error": "<error text>",
  "task_id": "<task_id>"
}

In case of error, <error text> will be any not null text value, it will contain the description of error.

{
  "error": "Bad type",
}

In case of success, it will return <task_id>. You should use Get conversion task status request to find out when conversion task will be finished.

{
  "error": null,
  "task_id": "4147c475ffe94ec8a11aff9a6a8f437a"
}

You should perform this check in a loop, until task will be finished (see status field).

Important! Please send this request not more often than every 5-10 seconds.

Request:

Headers:

URL parameters:

The folllowing sample API request check the conversion task status:

curl -sSX GET https://a-%SERVER_NAME%-%REGION_NAME%.conversiontools.io/v1/tasks/d9b5369bfc6541d88581d4ff80954917 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API Token>"

Response:

{
  "error": "<error text>",
  "status": "<status>",
  "file_id": "<file_id>"
}

In case of error, <error text> will be any not null text value, it will contain the description of error.

status is one of the following:

• PENDING - task is queued and waiting to be processed
• RUNNING - task is running
• SUCCESS - task is finished successfully
• ERROR - task is finished with an error

When status is PENDING or RUNNING, response will have an empty file_id field, for example:

{
  "error": null,
  "status": "RUNNING",
  "file_id": null
}

When status is SUCCESS, response will have file_id of the result file, for example:

{
  "error": null,
  "status": "SUCCESS",
  "file_id": "ce87de1a680c4451a49a72df3fecd3fe"
}

When status is ERROR, response will have error field with description of the error:

{
  "error": "Wrong file format",
  "status": "ERROR",
  "file_id": null
}

When status returned as SUCCESS or ERROR - this means that the conversion process is finished and you can download the result file using file_id (request is described in the next step) or analyse the error.

Request:

Headers:

URL parameters:

Response:

The response will contain a Content-Disposition: attachment; HTTP header, which should trigger the file download process (if you're using a browser).

If you have any questions regarding the use of the Conversion Tools REST API - feel free to contact us.