Welcome to the Konbert API documentation!

Introduction

API requests are made to the following endpoint prefix: https://konbert.com/api/v1

The API accepts requests in the following formats:

  • application/x-www-form-urlencoded
  • multipart/form-data
  • application/json

Responses will always be in JSON format, unless otherwise specified.

Example of a success response:

{
  "status": "ok",
  "message": "file created",
  "data": {}
}

Example of an error response:

{
  "status": "error",
  "message": "size required",
  "data": {}
}

Authentication

Head over to the account page to find your API key, you must log in or register if you don't have an account yet.

To authenticate your requests, use the Authorization header:

$ curl https://konbert.com/api/v1/files \
    -H "Authorization: Bearer ${API_KEY}"

Remember to replace ${API_KEY} with your own API key.

Conversion

Convert files using the https://konbert.com/api/v1/convert endpoint.

The convert endpoint accepts an input file (via upload or a URL) and outputs another file.

Examples

Simple synchronous conversion

This example converts file.csv TSV file to CSV, note the option sync=true which makes the conversion happen synchronously, the request will hang until the conversion is done, and then return the result as the response, which we write into the file result.csv:

$ curl https://konbert.com/api/v1/convert \
    -H "Authorization: Bearer ${API_KEY}" \

    -d "input[file]=@file.csv" \
    -d "input[format]=csv" \
    -d "input[options][separator]=\t" \

    -d "output[format]=csv" \
    -d "output[options][separator]=," \

    -d "sync=true" > result.csv

Asynchronous conversion for a bigger file

In the following example we convert the local file myfile.json file to CSV. Because we didn't specify the sync option, it will create a job and return it's ID, so we can check the status, this is useful when converting big files:

$ curl https://konbert.com/api/v1/convert \
    -H "Authorization: Bearer ${API_KEY}" \
    -d "input[file]=@myfile.json" \
    -d "input[format]=json" \
    -d "output[format]=csv"

{
    "status": "ok",
    "data": {
        "run_id": "966065f3-35c1-4f6d-b0f6-f2e960896973"
    }
}

Parameter reference

input required

Configure all options related to the input data.

You must define a file or HTTP input.

input.file file

Define a file to use as an input source. The file should follow the specifications of RFC 2388 (which defines file transfers for the multipart/form-data protocol).

input.http object

Define a HTTP source to use as input.

input.http.url string required

The URL to fetch the data from.

input.http.method string optional

HTTP method to use when requesting the resource. It can be GET (default) or POST.

input.http.headers object optional

HTTP headers to send when requesing the resource.

input.format string optional

Define the format of the input data. It will be automatically detected if not specified.

It can be one of:

json ndjson csv tsv
input.options object optional

Set the parsing preferences for the format. Depending on the chosen format, different options will be accepted.

CSV parsing options

input.options.separator string optional

The separator to use for each value or cell in a row of data. The default value is a comma (,).

output object required

Configure all options related to the output.

output.format string required

Define the output format. The input data will be converted to this format.

It can be one of:

json csv sql
output.options object optional

Set the writing preferences for the format. Depending on the chosen format, different options will be accepted.

CSV output options

input.options.separator string optional

The separator to use for each value or cell in a row of data. The default value is a comma (,).

SQL output options

input.options.flavour string optional

The flavour of SQL to use.

It can be one of:

sqlite mysql postgres
async boolean optional

Enable or disable asynchronous mode. The default value is true

When async is true, the conversion will happen in the background, the response will be a run ID, which you'll have to make a different request to check the conversion status.

When async is false, the request will block until the conversion is finished, then the converted data will be returned in the request itself.