API Documentation


Getting Started

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.


Libraries

We maintain the following official REST API libraries:


Authentication

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://api.conversiontools.io/v1/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API Token>"


API URL

Conversion Tools REST API is available at:

https://api.conversiontools.io/v1/

API Requests

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://api.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"
  }
}'


API Response

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

API Reference

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

Step 1. Upload file to the Conversion Tools Server

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:

POST https://api.conversiontools.io/v1/files

Headers:

Authorization: Bearer <API Token>
Content-Type: multipart/form-data

Input parameters:

file(required)A file reference

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://api.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.


Step 2. Run conversion task

Request:

POST https://api.conversiontools.io/v1/tasks

Headers:

Authorization: Bearer <API Token>
Content-Type: application/json

Input parameters:

type(required)Conversion type, for example convert.website_to_pdf. See list of available conversion types.
options(required)Set of options, different for every conversion task, see the tables below.

options parameters generic for every conversion task:

file_id(required, when converting the file uploaded to the server)For conversions which require a file to be uploaded, this is the file_id returned by POST /files request (from Step 1).
url(required, when converting the file from the Internet by link)For conversions which accepts file by URL, this is a place to put it.

options parameters specific per conversion task:

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

convert.epub_to_pdf - Convert ePub to PDF
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.website_to_pdf - Convert HTML to PDF
ParameterRequiredPossible values
file_id(required, when converting the uploaded file)file_id of the file to convert
url(required, when converting the file from url)Internet URL of the file to convert
orientation(optional)Landscape
Portrait
pagesize(optional)A4
B5
Letter
colormode(optional)colored
grayscale
background(optional)yes
no
images(optional)yes
no
javascript(optional)yes
no

For optional parameters the default value highlighted in bold text.

convert.word_to_pdf - Convert Word to PDF
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.powerpoint_to_pdf - Convert PowerPoint to PDF
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.word_to_text - Convert Word to Text
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.powerpoint_to_text - Convert PowerPoint to Text
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.jpg_to_pdf - Convert JPG to PDF
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
orientation(optional)Landscape
Portrait

For optional parameters the default value highlighted in bold text.

convert.png_to_pdf - Convert PNG to PDF
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
orientation(optional)Landscape
Portrait

For optional parameters the default value highlighted in bold text.

convert.website_to_jpg - Convert Website to JPG. Create Website Thumbnail
ParameterRequiredPossible values
url(required)Internet URL of the file to convert
images(optional)yes
no
javascript(optional)yes
no

For optional parameters the default value highlighted in bold text.

convert.website_to_png - Convert Website to PNG. Create Website Thumbnail
ParameterRequiredPossible values
url(required)Internet URL of the file to convert
images(optional)yes
no
javascript(optional)yes
no

For optional parameters the default value highlighted in bold text.

convert.html_table_to_csv - Convert HTML Table to CSV
ParameterRequiredPossible values
file_id(required, when converting the uploaded file)file_id of the file to convert
url(required, when converting the file from url)Internet URL of the file to convert
delimiter(optional)comma
semicolon
vertical_bar
tabulation

For optional parameters the default value highlighted in bold text.

convert.excel_to_pdf - Convert Excel to PDF
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
orientation(optional)Landscape
Portrait

For optional parameters the default value highlighted in bold text.

convert.excel_to_html - Convert Excel to HTML
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.excel_to_csv - Convert Excel to CSV
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
delimiter(optional)comma
semicolon
vertical_bar
tabulation

For optional parameters the default value highlighted in bold text.

convert.ods_to_csv - Convert OpenOffice Calc ODS to CSV
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
delimiter(optional)comma
semicolon
vertical_bar
tabulation

For optional parameters the default value highlighted in bold text.

convert.ods_to_pdf - Convert OpenOffice Calc ODS to PDF
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
orientation(optional)Landscape
Portrait

For optional parameters the default value highlighted in bold text.

convert.ods_to_excel - Convert OpenOffice Calc ODS to Excel
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.csv_to_excel - Convert CSV to Excel
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
delimiter(optional)comma
semicolon
vertical_bar
tabulation
split_excel_rows_limit(optional)yes
no

For optional parameters the default value highlighted in bold text.

convert.csv_to_xml - Convert CSV to XML
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
delimiter(optional)comma
semicolon
vertical_bar
tabulation
header(optional)Use first line of the CSV file as a columns header:
yes
no

For optional parameters the default value highlighted in bold text.

convert.xml_to_csv - XML to CSV Converter - Convert XML to CSV Online
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
delimiter(optional)comma
semicolon
vertical_bar
tabulation

For optional parameters the default value highlighted in bold text.

convert.xml_to_excel - Convert XML to Excel Online
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
split_excel_rows_limit(optional)yes
no

For optional parameters the default value highlighted in bold text.

convert.excel_xml_to_excel_xlsx - Convert Excel XML to Excel XLSX Online
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.pdf_to_excel - Convert PDF to Excel
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.pdf_to_jpg - Convert PDF to JPG
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
image_resolution(optional)values in PPI (pixel per inch):
72
150
300
600
jpeg_quality(optional)0 - 100 (default: 80)
colormode(optional)colored
grayscale
progressive_jpeg(optional)yes
no

For optional parameters the default value highlighted in bold text.

convert.pdf_to_png - Convert PDF to PNG
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
image_resolution(optional)values in PPI (pixel per inch):
72
150
300
600
colormode3(optional)colored
grayscale
monochrome
background_color(optional)white
transparent

For optional parameters the default value highlighted in bold text.

convert.pdf_to_tiff - Convert PDF to TIFF
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
image_resolution(optional)values in PPI (pixel per inch):
72
150
300
600
colormode3(optional)colored
grayscale
monochrome
background_color(optional)white
transparent

For optional parameters the default value highlighted in bold text.

convert.pdf_to_svg - Convert PDF to SVG
ParameterRequiredPossible values
file_id(required)file_id of the file to convert
image_resolution(optional)values in PPI (pixel per inch):
72
150
300
600
pagesize(optional)A4
B5
Letter

For optional parameters the default value highlighted in bold text.

convert.pdf_to_text - Convert PDF to Text
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.png_to_jpg - Convert PNG to JPG
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.jpg_to_png - Convert JPG to PNG
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.

convert.remove_exif - Remove EXIF Data from Photos
ParameterRequiredPossible values
file_id(required)file_id of the file to convert

For optional parameters the default value highlighted in bold text.


The folllowing sample API request creates new conversion task:


curl -sSX POST https://api.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"
}

Step 3. Get conversion task status

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:

GET https://api.conversiontools.io/v1/tasks/<task_id>

Headers:

Authorization: Bearer <API Token>
Content-Type: application/json

URL parameters:

task_id(required)This is the task_id returned in the previous step.

The folllowing sample API request check the conversion task status:


curl -sSX GET https://api.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.


Step 4. Download result file

Request:

GET https://api.conversiontools.io/v1/files/<file_id>

Headers:

Authorization: Bearer <API Token>
Content-Type: application/json

URL parameters:

<file_id>(required)This is the file_id of the file you need to download, for example, file_id returned in the previous step get task status.

Response:

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


Available Conversion Types
Conversion TypeDescription
convert.epub_to_pdfConvert ePub to PDF
convert.website_to_pdfConvert HTML to PDF
convert.word_to_pdfConvert Word to PDF
convert.powerpoint_to_pdfConvert PowerPoint to PDF
convert.word_to_textConvert Word to Text
convert.powerpoint_to_textConvert PowerPoint to Text
convert.jpg_to_pdfConvert JPG to PDF
convert.png_to_pdfConvert PNG to PDF
convert.website_to_jpgConvert Website to JPG. Create Website Thumbnail
convert.website_to_pngConvert Website to PNG. Create Website Thumbnail
convert.html_table_to_csvConvert HTML Table to CSV
convert.excel_to_pdfConvert Excel to PDF
convert.excel_to_htmlConvert Excel to HTML
convert.excel_to_csvConvert Excel to CSV
convert.ods_to_csvConvert OpenOffice Calc ODS to CSV
convert.ods_to_pdfConvert OpenOffice Calc ODS to PDF
convert.ods_to_excelConvert OpenOffice Calc ODS to Excel
convert.csv_to_excelConvert CSV to Excel
convert.csv_to_xmlConvert CSV to XML
convert.xml_to_csvXML to CSV Converter - Convert XML to CSV Online
convert.xml_to_excelConvert XML to Excel Online
convert.excel_xml_to_excel_xlsxConvert Excel XML to Excel XLSX Online
convert.pdf_to_excelConvert PDF to Excel
convert.pdf_to_jpgConvert PDF to JPG
convert.pdf_to_pngConvert PDF to PNG
convert.pdf_to_tiffConvert PDF to TIFF
convert.pdf_to_svgConvert PDF to SVG
convert.pdf_to_textConvert PDF to Text
convert.png_to_jpgConvert PNG to JPG
convert.jpg_to_pngConvert JPG to PNG
convert.remove_exifRemove EXIF Data from Photos

Need help?

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