FreeConvert.com API v1.0.5

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Welcome to FreeConvert.com API V1! On this documentation you will find how to send API requests to convert, merge, or optimize your files using FreeConvert.com.

Our API uses API keys to authenticate requests. You can view and manage your API keys in the User Dashboard.

Your API keys can be used to consume your account credits, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests to protected routes without authentication will also fail.

Base URLs:

https://api.freeconvert.com/v1

Email: Support

Getting Started

FreeConvert.com is an online tool to convert audio, video, image, or document files.

Simply drag and drop your files, convert and download/export the file. There is no software to install or account registrations.

Most of our file conversions have advanced options for you to control the output file. For example:

Audio conversions (cut audio, select audio codec, bit rate, select channels..etc)
Video conversions (cut video, select target audio/video codec, bit rate, video aspect ratio, and resolution)
Image conversions (set image dimensions, compression level)
Document conversions (Set orientation, margins, compression level)

This guide leads you through a typical implementation of the FreeConvert API. It contains creating a task, job and handling the result. For more in depth documentation please use the menu on the left to directly jump to specific api endpoints. Please refer to API code examples for more use cases.

Terminology

Tasks

Tasks are individual activities you can perform in FreeConvert.

Import Tasks

Import tasks are used to upload files into FreeConvert for using them later in other tasks. Example: Downloading files from device, URL or a S3 bucket. FreeConvert stores the imported files only for 4 hours. See Import Files from left menu to find different ways to import files into FreeConvert.

Processing Tasks

Processing tasks are used to perform file transformation activities in FreeConvert. Processing tasks subjects the files imported by Import tasks into modification according to the type of the processing task. See Convert, Compress and Merge operations from left menu to find more info.

Export Tasks

Export tasks are used to export one or multiple output files from FreeConvert, for example by generating public URLs or by storing them on your S3 bucket. See Export Files from left menu to find different ways to export files from FreeConvert.

Jobs

Job is a collection of tasks. A job can have import tasks, processing tasks and export tasks defining a workflow that FreeConvert should follow. For example, The first task of a job could be importing the file from your device. The second task could be converting this file into a different format and the final task of the job could be exporting the file to a S3 bucket or exporting the download URL.

It's also possible to have multiple processing tasks and multiple export tasks within a single job. This is useful if you want to convert a file and create a thumbnail at the same time, for example.

We can convert a file using a Job in which we define all the tasks that the Job is comprised of. Or we can execute individual tasks step by step. Following sections explain how to execute individual tasks before explaining how to submit a Job containing multiple tasks.

Import File - From device

Import / Upload

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/import/upload \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}'

POST https://api.freeconvert.com/v1/process/import/upload HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

const headers = {
  "Content-Type": "application/json",
  Accept: "application/json",
  Authorization: `Bearer ${access_token}`,
};

fetch("https://api.freeconvert.com/v1/process/import/upload", {
  method: "POST",
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

import requests

headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer' + access_token
}

result = requests.post(
  'https://api.freeconvert.com/v1/process/import/upload',
  headers = headers
)

print(result.json())

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer' + access_token
}

result = RestClient.post(
  'https://api.freeconvert.com/v1/process/import/upload',
  headers: headers
)

JSON.parse(result)

<?php

require 'vendor/autoload.php';

$headers = array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer ' $access_token,
);

$client = new \GuzzleHttp\Client();

try {
  $response = $client->request(
    'POST',
    'https://api.freeconvert.com/v1/process/import/upload',
    array(
      'headers' => $headers,
    )
  );
  print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

// ...

URL obj = new URL("https://api.freeconvert.com/v1/process/import/upload");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");

int responseCode = con.getResponseCode();

BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream())
);

String inputLine;
StringBuffer response = new StringBuffer();

while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();

System.out.println(response.toString());

package main

import (
  "bytes"
  "net/http"
)

func main() {
  headers := map[string][]string{
    "Content-Type": string{"application/json"},
    "Accept": string{"application/json"},
    "Authorization": string{"Bearer" + access_token},
  }

  req, err := http.NewRequest(
    "POST",
    "https://api.freeconvert.com/v1/process/import/upload"
  )
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
  // ...
}

Upload Task Response

{
    ...
    "result": {
        "form": {
            "url": "https://server100.freeconvert.com/api/upload/625e27e075ae740013481967",
            "parameters": {
                "signature": "503808ac1738adbd"
            }
        }
    },
    ...
}

Upload File to the Server

# You can also use wget
# URL will be dynamic and will differ from task to task
curl -L "https://server100.freeconvert.com/api/upload/625e27e075ae740013481967/" \
  -F "signature=503808ac1738adbd" \
  -F "file=@/path/to/file.ext" \

# URL will be dynamic and will differ from task to task
POST https://server100.freeconvert.com/api/upload/625e27e075ae740013481967 HTTP/1.1
Host: server301.freeconvert.com
Content-Type: multipart/form-data;boundary="boundary"

# value1
--boundary
Content-Disposition: form-data; name="file"; filename="example.mp3"
Content-Type: audio/mpeg

# value2
--boundary
Content-Disposition: form-data; name="signature" signature_value

const formData = new FormData();

for (const parameter in task.result.form.parameters) {
  formData.append(parameter, task.result.form.parameters[parameter]);
}

formData.append("file", /*file stream or blob*/);

fetch(task.result.form.url, {
  method: "POST",
  body: formData,
  headers: {
    "Content-Type": "multipart/form-data"
  }
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

import requests

payload = {
  'signature': '9c5db43ce428c4c4'
}
files= [('file',(file_name ,open(file_path,'rb'),'audio/mpeg'))]

headers = {
  'Authorization': 'Bearer' + access_token
}

# URL will be dynamic and will differ from task to task
result = requests.request('POST', task.result.form.url, headers=headers, data=payload, files=files)

print(result.json())

require 'uri'
require 'net/http'
require 'json'

url = URI(task.result.form.url)

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)

request["Authorization"] = 'Bearer' + access_token

form_data = [
  ['file', File.open(file_path)],
  ['signature', '9c5db43ce428c4c4']
]

request.set_form form_data, 'multipart/form-data'

result = https.request(request)

JSON.parse(result)

<?php
$client = new Client();

$headers = [
  'Authorization' => 'Bearer ' $access_token
];

$options = [
  'multipart' => [
    [
      'name' => 'file',
      'contents' => Utils::tryFopen($file_path, 'r'),
      'filename' => $file_name,
      'headers'  => [
        'Content-Type' => '<Content-type header>'
      ]
    ],
    [
      'name' => 'signature',
      'contents' => '9c5db43ce428c4c4'
    ]
]];

try {
  $request = new Request(
    'POST',
    $task->result->form->url,
    $headers
  );

  $response = $client->sendAsync($request, $options)->wait();

  print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

// ...

Unirest.setTimeouts(0, 0);
HttpResponse<String> response = Unirest.post(task.result.form.url)
  .header("Authorization", String.format("Bearer %s", access_token))
  .field("file", new File(file_path))
  .field("signature", "9c5db43ce428c4c4")
  .asString();

package main

import (
  "fmt"
  "bytes"
  "mime/multipart"
  "os"
  "path/filepath"
  "io"
  "net/http"
  "io/ioutil"
)

func main() {
  url := task[result[form[url]]]
  method := "POST"

  payload := &bytes.Buffer{}
  writer := multipart.NewWriter(payload)
  file, errFile1 := os.Open(file_path)
  defer file.Close()

  part1, errFile1 := writer.CreateFormFile("file",filepath.Base(file_path))
  _, errFile1 = io.Copy(part1, file)

  if errFile1 != nil {
    fmt.Println(errFile1)
    return
  }
  _ = writer.WriteField("signature", "9c5db43ce428c4c4")
  err := writer.Close()

  if err != nil {
    fmt.Println(err)
    return
  }

  client := &http.Client {}
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }

  req.Header.Add("Authorization", "Bearer" + access_token)

  req.Header.Set("Content-Type", writer.FormDataContentType())
  res, err := client.Do(req)

  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

If you want to upload a file from your device storage, you have to use the import/upload API endpoint. This is a two-step process.

The first request will provide you a response which contains details about uploading the actual file from your device. The response contains the url that the file must be uploaded to and other paramaters that should be submitted.

The second request is to actually upload the file using the information we got from the first request. Please see API code examples for more examples of this.

Import File - From URL

Import / URL

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/import/url \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}'

# Body Parameter
{
  "url": "https://example.com/some.jpg",
  "filename": "some.jpg", # optional
}

POST https://api.freeconvert.com/v1/process/import/url HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

# Body Parameter
{
  "url": "https://example.com/some.jpg",
  "filename": "some.jpg", // optional
}

const inputBody = {
  url: "https://example.com/some.jpg",
  filename: "some.jpg", // optional
};
const headers = {
  "Content-Type": "application/json",
  Accept: "application/json",
  Authorization: `Bearer ${access_token}`,
};

fetch("https://api.freeconvert.com/v1/process/import/url", {
  method: "POST",
  body: JSON.stringify(inputBody),
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

import requests

request_body = {
  'url': 'https://example.com/some.jpg',
  'filename': 'some.jpg', # optional
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer' + access_token
}

result = requests.post(
  'https://api.freeconvert.com/v1/process/import/url',
  data = request_body,
  headers = headers
)

print(result.json())

require 'rest-client'
require 'json'

request_body = {
  'url' => "https://example.com/some.jpg",
  'filename' => "some.jpg", # optional
}
headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer' + access_token
}

result = RestClient.post(
  'https://api.freeconvert.com/v1/process/import/url',
  body: request_body,
  headers: headers
)

JSON.parse(result)

<?php

require 'vendor/autoload.php';

$headers = array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer ' $access_token,
);

$client = new \GuzzleHttp\Client();

$request_body = array(
  'url' => "https://example.com/some.jpg",
  'filename' => "some.jpg", # optional
)

try {
  $response = $client->request(
    'POST',
    'https://api.freeconvert.com/v1/process/import/url',
    array(
      'headers' => $headers,
      'content' => json_encode($request_body),
    )
  );
  print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

// ...

URL obj = new URL("https://api.freeconvert.com/v1/process/import/url");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");

int responseCode = con.getResponseCode();

BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream())
);

String inputLine;
StringBuffer response = new StringBuffer();

while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();

System.out.println(response.toString());

package main

import (
  "bytes"
  "net/http"
)

func main() {
  jsonReq := map[string][]string{
    "url": string{"https://example.com/some.jpg"},
    "filename": string{"some.jpg"}, // optional
  }
  headers := map[string][]string{
    "Content-Type": string{"application/json"},
    "Accept": string{"application/json"},
    "Authorization": string{"Bearer" + access_token},
  }

  data := bytes.NewBuffer([]byte{jsonReq})

  req, err := http.NewRequest(
    "POST",
    "https://api.freeconvert.com/v1/process/import/url",
    data
  )
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
  // ...
}

If uploading a file directly from a URL, it will take only one step. FreeConvert will fetch the file from the URL you have specified in the url field.

We have a bunch of other options available for importing files into FreeConvert.

Convert File

Convert Task

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/convert \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}'

# Body Parameter
{
  "input": "import_task_id",
  "input_format": "jpg",
  "output_format": "png",
  "options": {
    # …advanced options…
  },
}

POST https://api.freeconvert.com/v1/process/convert HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

# Body Parameter
{
  "input": "import_task_id",
  "input_format": "jpg",
  "output_format": "png",
  "options": {
    <!-- …advanced options… -->
  },
}

const inputBody = {
  input: import_task_id,
  input_format: "jpg",
  output_format: "png",
  options: {
    // …advanced options…
  },
};
const headers = {
  "Content-Type": "application/json",
  Accept: "application/json",
  Authorization: `Bearer ${access_token}`,
};

fetch("https://api.freeconvert.com/v1/process/convert", {
  method: "POST",
  body: inputBody,
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

import requests

request_body = {
  'input': import_task_id,
  'input_format': 'jpg',
  'output_format': 'png',
  'options': {
    # …advanced options…
  }
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer' + access_token
}

result = requests.post(
  'https://api.freeconvert.com/v1/process/convert',
  data = request_body,
  headers = headers
)

print(result.json())

require 'rest-client'
require 'json'

request_body = {
  'input' => import_task_id,
  'input_format' => 'jpg',
  'output_format' => 'png',
  'options': {
    # …advanced options…
  }
}
headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer' + access_token
}

result = RestClient.post(
  'https://api.freeconvert.com/v1/process/convert',
  body: request_body,
  headers: headers
)

JSON.parse(result)

<?php

require 'vendor/autoload.php';

$headers = array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer ' $access_token,
);

$client = new \GuzzleHttp\Client();

$request_body = array(
  'input' => import_task_id,
  'input_format' => 'jpg',
  'output_format' => 'png',
  'options' => {
    // …advanced options…
  },
)

try {
  $response = $client->request(
    'POST',
    'https://api.freeconvert.com/v1/process/convert',
    array(
      'headers' => $headers,
      'content' => json_encode($request_body),
    )
  );
  print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

// ...

URL obj = new URL("https://api.freeconvert.com/v1/process/convert");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");

int responseCode = con.getResponseCode();

BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream())
);

String inputLine;
StringBuffer response = new StringBuffer();

while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();

System.out.println(response.toString());

package main

import (
  "bytes"
  "net/http"
)

func main() {
  jsonReq := map[string][]string{
    "input": string{import_task_id},
    "input_format": string{"jpg"},
    "output_format": string{"png"},
    "options": map[string[]]string{
      // …advanced options…
    }
  }
  headers := map[string][]string{
    "Content-Type": string{"application/json"},
    "Accept": string{"application/json"},
    "Authorization": string{"Bearer" + access_token},
  }

  data := bytes.NewBuffer([]byte{jsonReq})

  req, err := http.NewRequest(
    "POST",
    "https://api.freeconvert.com/v1/process/convert",
    data
  )
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
  // ...
}

In this example, we convert an imported file from jpg to png. We must provide the import task id as the input so FreeConvert will use that imported file for the conversion.

You can get the possible conversion formats for an operation from the following API endpoint: GET /query/view/options

See Tasks > List Operations from the left menu to find the parameters and the use of this endpoint.

Most of our file conversions have advanced options that let you control the output file. You'll get the possible advanced options for a specific input and output combination including the hints.

Compress File

Compress Task

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/compress \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}'

# Body Parameter
{
  "input": "import_task_id",
  "input_format": "jpg",
  "options": {
    # …advanced options…
  },
}

POST https://api.freeconvert.com/v1/process/compress HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

# Body Parameter
{
  "input": "import_task_id",
  "input_format": "jpg",
  "options": {
    <!-- …advanced options… -->
  },
}

const inputBody = {
  input: import_task_id,
  input_format: "jpg",
  options: {
    // …advanced options…
  },
};
const headers = {
  "Content-Type": "application/json",
  Accept: "application/json",
  Authorization: `Bearer ${access_token}`,
};

fetch("https://api.freeconvert.com/v1/process/compress", {
  method: "POST",
  body: inputBody,
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

import requests

request_body = {
  'input': import_task_id,
  'input_format': 'jpg',
  'options': {
    # …advanced options…
  }
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer' + access_token
}

result = requests.post(
  'https://api.freeconvert.com/v1/process/compress',
  data = request_body,
  headers = headers
)

print(result.json())

require 'rest-client'
require 'json'

request_body = {
  'input' => import_task_id,
  'input_format' => 'jpg',
  'options': {
    # …advanced options…
  }
}
headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer' + access_token
}

result = RestClient.post(
  'https://api.freeconvert.com/v1/process/compress',
  body: request_body,
  headers: headers
)

JSON.parse(result)

<?php

require 'vendor/autoload.php';

$headers = array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer ' $access_token,
);

$client = new \GuzzleHttp\Client();

$request_body = array(
  'input' => import_task_id,
  'input_format' => 'jpg',
  'options' => {
    // …advanced options…
  },
)

try {
  $response = $client->request(
    'POST',
    'https://api.freeconvert.com/v1/process/compress',
    array(
      'headers' => $headers,
      'content' => json_encode($request_body),
    )
  );
  print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

// ...

URL obj = new URL("https://api.freeconvert.com/v1/process/compress");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");

int responseCode = con.getResponseCode();

BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream())
);

String inputLine;
StringBuffer response = new StringBuffer();

while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();

System.out.println(response.toString());

package main

import (
  "bytes"
  "net/http"
)

func main() {
  jsonReq := map[string][]string{
    "input": string{import_task_id},
    "input_format": string{"jpg"},
    "options": map[string[]]string{
      // …advanced options…
    }
  }
  headers := map[string][]string{
    "Content-Type": string{"application/json"},
    "Accept": string{"application/json"},
    "Authorization": string{"Bearer" + access_token},
  }

  data := bytes.NewBuffer([]byte{jsonReq})

  req, err := http.NewRequest(
    "POST",
    "https://api.freeconvert.com/v1/process/compress",
    data
  )
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
  // ...
}

In this example, we are going to compress an imported jpg file. We must provide the import task id as the input so FreeConvert will use that imported file for the compression.

Depending on the input file format, we have different kinds of compression options, which is a part of our advanced options that let you control the output file. You'll get the possible advanced options for a specific input and output combination including the hints.

Merge File

Merge Task

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/merge \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}'

# Body Parameter
{
  "input": [
    "task_id_1",
    "task_id_2"
  ],
  "output_format": "pdf",
  "filename": "some.pdf", # optional
  "options": {
    # …advanced options…
  },
}

POST https://api.freeconvert.com/v1/process/merge HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

# Body Parameter
{
  "input": [
    "task_id_1",
    "task_id_2"
  ],
  "output_format": "pdf",
  "filename": "some.pdf", // optional
  "options": {
    <!-- …advanced options… -->
  },
}

inputBody = {
  input: [task_id_1, task_id_2],
  output_format: "pdf",
  filename: "some.pdf", // optional
  options: {
    // …advanced options…
  },
};
const headers = {
  "Content-Type": "application/json",
  Accept: "application/json",
  Authorization: `Bearer ${access_token}`,
};

fetch("https://api.freeconvert.com/v1/process/merge", {
  method: "POST",
  body: inputBody,
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

import requests

request_body = {
  'input': [task_id_1, task_id_2],
  'output_format': 'pdf',
  'filename': 'some.pdf', # optional
  'options': {
    # …advanced options…
  }
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer' + access_token
}

result = requests.post(
  'https://api.freeconvert.com/v1/process/merge',
  data = request_body,
  headers = headers
)

print(result.json())

require 'rest-client'
require 'json'

request_body = {
  'input' => [task_id_1, task_id_2],
  'output_format' => 'pdf',
  'filename' => 'some.pdf', # optional
  'options': {
    # …advanced options…
  }
}
headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer' + access_token
}

result = RestClient.post(
  'https://api.freeconvert.com/v1/process/merge',
  body: request_body,
  headers: headers
)

JSON.parse(result)

<?php

require 'vendor/autoload.php';

$headers = array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer ' $access_token,
);

$client = new \GuzzleHttp\Client();

$request_body = array(
  'input' => array(task_id_1, task_id_2),
  'output_format': 'pdf',
  'filename': 'some.pdf', # optional
  'options' => {
    // …advanced options…
  },
)

try {
  $response = $client->request(
    'POST',
    'https://api.freeconvert.com/v1/process/merge',
    array(
      'headers' => $headers,
      'content' => json_encode($request_body),
    )
  );
  print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

// ...

URL obj = new URL("https://api.freeconvert.com/v1/process/merge");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");

int responseCode = con.getResponseCode();

BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream())
);

String inputLine;
StringBuffer response = new StringBuffer();

while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();

System.out.println(response.toString());

package main

import (
  "bytes"
  "net/http"
)

func main() {
  jsonReq := map[string][]string{
    "input": []string{task_id_1, task_id_2},
    "output_format": string{"pdf"},
    "filename": string{"some.zip"}, // optional
    "options": map[string[]]string{
      // …advanced options…
    }
  }
  headers := map[string][]string{
    "Content-Type": string{"application/json"},
    "Accept": string{"application/json"},
    "Authorization": string{"Bearer" + access_token},
  }

  data := bytes.NewBuffer([]byte{jsonReq})

  req, err := http.NewRequest(
    "POST",
    "https://api.freeconvert.com/v1/process/merge",
    data
  )
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
  // ...
}

We are going to merge two (or as many as you want) imported or converted image files (jpg, png, etc...) into a single PDF or GIF file. We must provide the task ids as the input so FreeConvert will use those files for the merge task.

You can use this merge task according to your needs.

For example, say you have several files and the only requirement is to merge those into a single PDF or GIF. In this case, all you need to do is just upload or import those files into FreeConvert and then start the merge task by including the import task ids from the previous step.

If you also need to decrease the size of your input files before merging them, then you have to perform one more step which is the compress task before starting the merge task.

In summary, all the tasks in FreeConvert are independent from each other, you can decide the flow and order of tasks as you want.

FreeConvert also supports a few advanced options while merging files, right now we only allow merging images and pdf files.

Export File - From URL

Export Task

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/export/url \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}'

# Body Parameter
{
  "input": [
    "import_task_id_1",
    "import_task_id_2"
  ],
  "filename": "some.zip", # optional
  "archive_multiple_files": true
}

POST https://api.freeconvert.com/v1/process/export/url HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

# Body Parameter
{
  "input": [
    "import_task_id_1",
    "import_task_id_2"
  ],
  "filename": "some.zip", // optional
  "archive_multiple_files": true
}

inputBody = {
  input: [import_task_id_1, import_task_id_2],
  filename: "some.zip", // optional
  archive_multiple_files: true,
};
const headers = {
  "Content-Type": "application/json",
  Accept: "application/json",
  Authorization: `Bearer ${access_token}`,
};

fetch("https://api.freeconvert.com/v1/process/export/url", {
  method: "POST",
  body: inputBody,
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

import requests

request_body = {
  'input': [import_task_id_1, import_task_id_2],
  'filename': 'some.zip', # optional
  'archive_multiple_files': true,
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer' + access_token
}

result = requests.post(
  'https://api.freeconvert.com/v1/process/export/url',
  data = request_body,
  headers = headers
)

print(result.json())

require 'rest-client'
require 'json'

request_body = {
  'input' => [import_task_id_1, import_task_id_2],
  'filename' => 'some.zip', # optional
  'archive_multiple_files' => true,
}
headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer' + access_token
}

result = RestClient.post(
  'https://api.freeconvert.com/v1/process/export/url',
  body: request_body,
  headers: headers
)

JSON.parse(result)

<?php

require 'vendor/autoload.php';

$headers = array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer ' $access_token,
);

$client = new \GuzzleHttp\Client();

$request_body = array(
  'input' => array(import_task_id_1, import_task_id_2),
  'filename' => 'some.zip', # optional
  'archive_multiple_files' => true,
)

try {
  $response = $client->request(
    'POST',
    'https://api.freeconvert.com/v1/process/export/url',
    array(
      'headers' => $headers,
      'content' => json_encode($request_body),
    )
  );
  print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

// ...

URL obj = new URL("https://api.freeconvert.com/v1/process/export/url");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");

int responseCode = con.getResponseCode();

BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream())
);

String inputLine;
StringBuffer response = new StringBuffer();

while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();

System.out.println(response.toString());

package main

import (
  "bytes"
  "net/http"
)

func main() {
  jsonReq := map[string][]string{
    "input": []string{import_task_id_1, import_task_id_2}
    "filename": string{"some.zip"}, // optional
    "archive_multiple_files": bool{"true"},
  }
  headers := map[string][]string{
    "Content-Type": string{"application/json"},
    "Accept": string{"application/json"},
    "Authorization": string{"Bearer" + access_token},
  }

  data := bytes.NewBuffer([]byte{jsonReq})

  req, err := http.NewRequest(
    "POST",
    "https://api.freeconvert.com/v1/process/export/url",
    data
  )
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
  // ...
}

Like import files, we have several ways to export a file from FreeConvert. Here, we're going to use export/url in order to retrieve a download link to the converted file.

We have a bunch of other options available for exporting files into FreeConvert.

Jobs

Job definition

{
  tag: "conversion",
  tasks: {
    import: {
      operation: "import/url",
      url: "https://example.com/some.jpg",
      filename: "some.jpg", // optional
    },
    convert: {
      operation: "convert",
      input: "import",
      output_format: "png",
      options: {
        png_compression_quality: 70,
      },
    },
    export: {
      operation: "export/url",
      input: "convert",
      filename: "some.zip",
    },
  },
}

Submit Job

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/jobs \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}'

# Body Parameter
{
  ...
  # follow the sample job definition above
}

POST https://api.freeconvert.com/v1/process/jobs HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

# Body Parameter
{
  ...
  # follow the sample job definition above
}

inputBody = {
  ...
  // follow the sample job definition above
};
const headers = {
  "Content-Type": "application/json",
  Accept: "application/json",
  Authorization: `Bearer ${access_token}`,
};

fetch("https://api.freeconvert.com/v1/process/jobs", {
  method: "POST",
  body: inputBody,
  headers: headers,
})
  .then(function (res) {
    return res.json();
  })
  .then(function (body) {
    console.log(body);
  });

import requests

request_body = {
  ...
  # follow the sample job definition above
}
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer' + access_token
}

result = requests.post(
  'https://api.freeconvert.com/v1/process/jobs',
  data = request_body,
  headers = headers
)

print(result.json())

require 'rest-client'
require 'json'

request_body = {
  ...
  # follow the sample job definition above
}
headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer' + access_token
}

result = RestClient.post(
  'https://api.freeconvert.com/v1/process/jobs',
  body: request_body,
  headers: headers
)

JSON.parse(result)

<?php

require 'vendor/autoload.php';

$headers = array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer ' $access_token,
);

$client = new \GuzzleHttp\Client();

$request_body = array(
  ...
  // follow the sample job definition above
)

try {
  $response = $client->request(
    'POST',
    'https://api.freeconvert.com/v1/process/jobs',
    array(
      'headers' => $headers,
      'content' => json_encode($request_body),
    )
  );
  print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
  // handle exception or api errors.
  print_r($e->getMessage());
}

// ...

URL obj = new URL("https://api.freeconvert.com/v1/process/jobs");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");

int responseCode = con.getResponseCode();

BufferedReader in = new BufferedReader(
  new InputStreamReader(con.getInputStream())
);

String inputLine;
StringBuffer response = new StringBuffer();

while ((inputLine = in.readLine()) != null) {
  response.append(inputLine);
}
in.close();

System.out.println(response.toString());

package main

import (
  "bytes"
  "net/http"
)

func main() {
  jsonReq := map[string][]string{
    ...
    // follow the sample job definition above
  }
  headers := map[string][]string{
    "Content-Type": string{"application/json"},
    "Accept": string{"application/json"},
    "Authorization": string{"Bearer" + access_token},
  }

  data := bytes.NewBuffer([]byte{jsonReq})

  req, err := http.NewRequest(
    "POST",
    "https://api.freeconvert.com/v1/process/jobs",
    data
  )
  req.Header = headers

  client := &http.Client{}
  resp, err := client.Do(req)
  // ...
}

Instead of executing Tasks individually as shown earlier, we can define the whole conversion process using a single Job. The Job shown here defines three tasks.

Import a jpg file from a specified URL.
Convert the file to png format.
Export a download URL.

Advanced Options

Convert (JPG to PDF) Advanced Options

{
  "sourceExt": "jpg",
  "targetExt": "pdf",
  "operation": "convert",
  "options": [
    {
      "name": "strip",
      "hint": "Strip the image of any profiles, EXIF, and comments to reduce size",
      "data_type": "boolean",
      "default_value": "true"
    },
    {
      "name": "pdf_page_size",
      "hint": "",
      "data_type": "string",
      "type": "enum",
      "enum_values": [
        {
          "value": "1240.2x1753.95",
          "hint": "A4"
        },
        {
          "value": "same-as-image",
          "hint": "Same as image"
        },
        {
          "value": "1753.95x2480.25",
          "hint": "A3"
        },
        ...
      ]
    },
    {
      "name": "enlarge_images_to_fit",
      "hint": "Use this option if you want to enlarge small images to fit the PDF page size.",
      "data_type": "boolean",
      "default_value": "true",
      "conditions": [
        {
          "name": "pdf_page_size",
          "required": true,
          "meta": [
            {
              "value": "1240.2x1753.95",
              "label": "A4"
            },
            {
              "value": "1753.95x2480.25",
              "label": "A3"
            },
            ...
          ]
        }
      ]
    },
    ...
  ]
}

FreeConvert supports some outstanding advanced options in terms of converting, compressing, and merging files that make us the number one file converter in the web world. We are now making them available to our API users as well.

From the advanced options endpoint, you can generate all the possible options based on your operation and file types. Here, we'll share an example of how to use those options.

Let's say, you want to convert a JPG to a PDF. Now if you make a GET request to our convert advanced options API like below:

https://api.freeconvert.com/v1/query/options/convert?input_format=jpg&output_format=pdf

Then you'll get a response like this:

From this response, we can see an array named options that includes all the possible advanced options for your operation. Each options contains some common fields.

name - The name of the option that should be specified in the job.
hint - The use case of the option.
data_type - Data type that our engine allows for this option.
default_value - If the option is not included in the job, this value will be used.

We can see another field type: enum when the data_type is a string but only allow some specific values. In that case, you can also see the enum_values field that will give you a list of the possible values for that option.

Some of the options require certain conditions to be met to be effective. On the example response, enlarge_images_to_fit option requires one of the values of pdf_page_size to also be included in the job. Conditions can include:

name - Name of the other option that this option is dependent on.
meta - What are the values that the condition option must have, in order for the dependent option to be effective.
required - Whether the condition option must be included in the job or not. If this is false, that means the dependent option can exist on its own. However, if the condition option is also present in the job, then it must have one of the values specified in condition meta.

Now let's say I want to convert my JPG file to PDF, and I want the PDF page to be A4 in size and I need images in original size without scaling. So, my options that should be specified in the job will be like:

{ pdf_page_size: "1240.2x1753.95", enlarge_images_to_fit: false }

Errors

This section is to introduce to users possible errors and response codes that our API returns.

Response Codes:

FreeConvert.com API responds with the following standard HTTP status codes when encountered with an error:

Error Code	Meaning
400	Bad Request -- Your request parameter is invalid.
401	Unauthorized -- Your API key is invalid.
403	Forbidden -- Your access is denied.
404	Not Found -- The specified content could not be found.
405	Method Not Allowed -- You tried to access with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
409	Already exists -- You're requesting to create something that already exists.
429	Too Many Requests -- You're sending too many requests.
500	Internal Server Error -- We had a problem with our server. Try again later.

Rate Limits

FreeConvert API is rate limited. If your API requests are rate limited, you will receive a 429 HTTP response code.

Error Info

If a Job or Task has a status failed we provide additional info about the error in errorCode and msg(optional) attributes of the Job's or Task's result object.

// errorCode indicated on Task or Job object
{
  ....
  result: {
    errorCode: 'specific error code',
    msg: 'additional message about the error'
  }
  ...
}

Possible errorCodes of Task:

errorCode	Meaning
upload_timeout	File upload timeout exceeded.
engine_timeout	Conversion timeout exceeded due to our internal server issue.
out_of_conversion_minutes	Available conversion minutes are finished for this user.
out_of_conversion_minutes_per_task	Available conversion minutes are finished for this task.
user_deleted_task	Task failed due to the deletion operation of the user.
insufficient_permission	Task failed due to insufficient permission.
invalid_credentials	Task failed due to invalid credentials.
processing_failed	Task failed due to internal process failure.

A job can fail if one of its tasks is failed/canceled/deleted.

Possible errorCodes of Job:

errorCode	Meaning
task_failed	Job failed due to the failure of one of its task.
task_deleted	Job failed due to the deletion of one of its task.
task_canceled	Job failed due to the cancelation of one of its task.

Authentication

HTTP Authentication, scheme: bearer

Every request to a protected route in FreeConvert API must include an API Key so that we can identify you. Once you have signed up for an account, you can generate an API key by visiting the API keys page from your User Dashboard.

API requests are authenticated using the Authorization: Bearer API_KEY in the header.

API keys do not expire unless you delete them.

File Formats

List All Formats

Code samples

# You can also use wget
curl -X GET https://api.freeconvert.com/v1/query/formats \
  -H 'Accept: application/json'

GET https://api.freeconvert.com/v1/query/formats HTTP/1.1
Host: api.freeconvert.com
Accept: application/json


const headers = {
  'Accept':'application/json'
};

fetch('https://api.freeconvert.com/v1/query/formats',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://api.freeconvert.com/v1/query/formats',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.freeconvert.com/v1/query/formats', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.freeconvert.com/v1/query/formats', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/query/formats");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.freeconvert.com/v1/query/formats", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }

    /// Make a dummy request
    public async Task MakeGetRequest()
    {
      string url = "https://api.freeconvert.com/v1/query/formats";
      var result = await GetAsync(url);
    }

    /// Performs a GET Request
    public async Task GetAsync(string url)
    {
        //Start the request
        HttpResponseMessage response = await Client.GetAsync(url);

        //Validate result
        response.EnsureSuccessStatusCode();

    }




    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

GET /query/formats

Fetch all supported file formats by FreeConvert.com.

Example responses

200 Response

{
  "formats": [
    {
      "ext": "nrw"
    },
    {
      "ext": "png"
    },
    {
      "ext": "rm"
    },
    {
      "ext": "ape"
    },
    {
      "ext": "mobi"
    },
    {
      "ext": "pcx"
    },
    {
      "ext": "jfif"
    },
    {
      "ext": "rmi"
    },
    {
      "ext": "f4p"
    },
    {
      "ext": "flv"
    },
    {
      "ext": "nef"
    },
    {
      "ext": "m4r"
    },
    {
      "ext": "caf"
    },
    {
      "ext": "arw"
    },
    {
      "ext": "ptx"
    },
    {
      "ext": "dcr"
    },
    {
      "ext": "mp4"
    },
    {
      "ext": "m4a"
    },
    {
      "ext": "srw"
    },
    {
      "ext": "wmz"
    },
    {
      "ext": "amr"
    },
    {
      "ext": "djv"
    },
    {
      "ext": "x3f"
    },
    {
      "ext": "mp3"
    },
    {
      "ext": "dds"
    },
    {
      "ext": "mp1"
    },
    {
      "ext": "odt"
    },
    {
      "ext": "azw4"
    },
    {
      "ext": "svg"
    },
    {
      "ext": "asf"
    },
    {
      "ext": "dng"
    },
    {
      "ext": "mp4"
    },
    {
      "ext": "mid"
    },
    {
      "ext": "vsdx"
    },
    {
      "ext": "drf"
    },
    {
      "ext": "cbz"
    },
    {
      "ext": "raw"
    },
    {
      "ext": "ogv"
    },
    {
      "ext": "psb"
    },
    {
      "ext": "csv"
    },
    {
      "ext": "tgz"
    },
    {
      "ext": "jxl"
    },
    {
      "ext": "orf"
    },
    {
      "ext": "mxf"
    },
    {
      "ext": "dwg"
    },
    {
      "ext": "cgm"
    },
    {
      "ext": "sk"
    },
    {
      "ext": "sk1"
    },
    {
      "ext": "svgz"
    },
    {
      "ext": "wmf"
    },
    {
      "ext": "psd"
    },
    {
      "ext": "docm"
    },
    {
      "ext": "bmp"
    },
    {
      "ext": "midi"
    },
    {
      "ext": "azw3"
    },
    {
      "ext": "srf"
    },
    {
      "ext": "oga"
    },
    {
      "ext": "ppsx"
    },
    {
      "ext": "xlsx"
    },
    {
      "ext": "3gpp"
    },
    {
      "ext": "m2ts"
    },
    {
      "ext": "wav"
    },
    {
      "ext": "jpeg"
    },
    {
      "ext": "mov"
    },
    {
      "ext": "rmvb"
    },
    {
      "ext": "m4p"
    },
    {
      "ext": "nef"
    },
    {
      "ext": "raw"
    },
    {
      "ext": "f4v"
    },
    {
      "ext": "mts"
    },
    {
      "ext": "m4b"
    },
    {
      "ext": "eml"
    },
    {
      "ext": "xls"
    },
    {
      "ext": "opus"
    },
    {
      "ext": "k25"
    },
    {
      "ext": "kdc"
    },
    {
      "ext": "mp4"
    },
    {
      "ext": "tiff"
    },
    {
      "ext": "wtv"
    },
    {
      "ext": "wma"
    },
    {
      "ext": "dib"
    },
    {
      "ext": "sr2"
    },
    {
      "ext": "xvid"
    },
    {
      "ext": "xml"
    },
    {
      "ext": "tar"
    },
    {
      "ext": "gz"
    },
    {
      "ext": "hwp"
    },
    {
      "ext": "ai"
    },
    {
      "ext": "vsd"
    },
    {
      "ext": "xlsm"
    },
    {
      "ext": "dotx"
    },
    {
      "ext": "pdf"
    },
    {
      "ext": "pef"
    },
    {
      "ext": "wps"
    },
    {
      "ext": "m4a"
    },
    {
      "ext": "docx"
    },
    {
      "ext": "ppt"
    },
    {
      "ext": "x3f"
    },
    {
      "ext": "rw2"
    },
    {
      "ext": "cbr"
    },
    {
      "ext": "rtf"
    },
    {
      "ext": "webp"
    },
    {
      "ext": "azw"
    },
    {
      "ext": "3g2"
    },
    {
      "ext": "avi"
    },
    {
      "ext": "swf"
    },
    {
      "ext": "webm"
    },
    {
      "ext": "divx"
    },
    {
      "ext": "aac"
    },
    {
      "ext": "wave"
    },
    {
      "ext": "htm"
    },
    {
      "ext": "m4a"
    },
    {
      "ext": "ods"
    },
    {
      "ext": "fb2"
    },
    {
      "ext": "wmv"
    },
    {
      "ext": "gif"
    },
    {
      "ext": "tif"
    },
    {
      "ext": "crw"
    },
    {
      "ext": "rwl"
    },
    {
      "ext": "mpeg"
    },
    {
      "ext": "ppm"
    },
    {
      "ext": "emz"
    },
    {
      "ext": "qt"
    },
    {
      "ext": "mp4"
    },
    {
      "ext": "pages"
    },
    {
      "ext": "heic"
    },
    {
      "ext": "mp4"
    },
    {
      "ext": "epub"
    },
    {
      "ext": "aif"
    },
    {
      "ext": "odp"
    },
    {
      "ext": "3gp"
    },
    {
      "ext": "aifc"
    },
    {
      "ext": "lit"
    },
    {
      "ext": "targz"
    },
    {
      "ext": "zip"
    },
    {
      "ext": "avif"
    },
    {
      "ext": "cr3"
    },
    {
      "ext": "dxf"
    },
    {
      "ext": "heif"
    },
    {
      "ext": "pot"
    },
    {
      "ext": "pptm"
    },
    {
      "ext": "crw"
    },
    {
      "ext": "pef"
    },
    {
      "ext": "vsd"
    },
    {
      "ext": "vob"
    },
    {
      "ext": "m4a"
    },
    {
      "ext": "html"
    },
    {
      "ext": "txt"
    },
    {
      "ext": "dcs"
    },
    {
      "ext": "dcs"
    },
    {
      "ext": "emf"
    },
    {
      "ext": "raw"
    },
    {
      "ext": "3ga"
    },
    {
      "ext": "doc"
    },
    {
      "ext": "chm"
    },
    {
      "ext": "mp2"
    },
    {
      "ext": "rwl"
    },
    {
      "ext": "m4a"
    },
    {
      "ext": "mpg"
    },
    {
      "ext": "srw"
    },
    {
      "ext": "ico"
    },
    {
      "ext": "m4v"
    },
    {
      "ext": "m1v"
    },
    {
      "ext": "cr2"
    },
    {
      "ext": "docx"
    },
    {
      "ext": "mp4"
    },
    {
      "ext": "aiff"
    },
    {
      "ext": "xps"
    },
    {
      "ext": "arw"
    },
    {
      "ext": "jpg"
    },
    {
      "ext": "ogg"
    },
    {
      "ext": "pptx"
    },
    {
      "ext": "tga"
    },
    {
      "ext": "dvr-ms"
    },
    {
      "ext": "flac"
    },
    {
      "ext": "eps"
    },
    {
      "ext": "mpv"
    },
    {
      "ext": "pps"
    },
    {
      "ext": "mp4"
    },
    {
      "ext": "mp3"
    },
    {
      "ext": "ps"
    },
    {
      "ext": "djvu"
    },
    {
      "ext": "dpx"
    },
    {
      "ext": "mkv"
    },
    {
      "ext": "mp4"
    },
    {
      "ext": "pub"
    },
    {
      "ext": "raf"
    },
    {
      "ext": "rar"
    },
    {
      "ext": "7z"
    },
    {
      "ext": "ts"
    },
    {
      "ext": "mod"
    },
    {
      "ext": "webpage"
    },
    {
      "ext": "cdr"
    },
    {
      "ext": "odd"
    },
    {
      "ext": "potx"
    },
    {
      "ext": "dot"
    },
    {
      "ext": "txt"
    },
    {
      "ext": "art"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully get list of possible formats	None
400	Bad Request	Bad Request	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Convert Formats

Code samples

# You can also use wget
curl -X GET https://api.freeconvert.com/v1/query/formats/convert \
  -H 'Accept: application/json'

GET https://api.freeconvert.com/v1/query/formats/convert HTTP/1.1
Host: api.freeconvert.com
Accept: application/json


const headers = {
  'Accept':'application/json'
};

fetch('https://api.freeconvert.com/v1/query/formats/convert',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://api.freeconvert.com/v1/query/formats/convert',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.freeconvert.com/v1/query/formats/convert', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.freeconvert.com/v1/query/formats/convert', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/query/formats/convert");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.freeconvert.com/v1/query/formats/convert", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }

    /// Make a dummy request
    public async Task MakeGetRequest()
    {
      string url = "https://api.freeconvert.com/v1/query/formats/convert";
      var result = await GetAsync(url);
    }

    /// Performs a GET Request
    public async Task GetAsync(string url)
    {
        //Start the request
        HttpResponseMessage response = await Client.GetAsync(url);

        //Validate result
        response.EnsureSuccessStatusCode();

    }




    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

GET /query/formats/convert

If input_format is specified, returns supported output formats for the specified input_format. If output_format is specified, returns supported input formats for the specified output_format. Either input_format or output_format can be specified at a time. Not both.

Parameters

Name	In	Type	Required	Description
input_format	query	string	false	Input file extension. Specify `*` to indicate all formats.
output_format	query	string	false	Output file extension. Specify `*` to indicate all formats.

Example responses

200 Response

{
  "formats": [
    {
      "ext": "bmp"
    },
    {
      "ext": "eps"
    },
    {
      "ext": "gif"
    },
    {
      "ext": "ico"
    },
    {
      "ext": "jpg"
    },
    {
      "ext": "odd"
    },
    {
      "ext": "pdf"
    },
    {
      "ext": "png"
    },
    {
      "ext": "ps"
    },
    {
      "ext": "psd"
    },
    {
      "ext": "svg"
    },
    {
      "ext": "text"
    },
    {
      "ext": "tga"
    },
    {
      "ext": "tiff"
    },
    {
      "ext": "txt"
    },
    {
      "ext": "webp"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully get list of possible formats for convert operation	None
400	Bad Request	Bad Request	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Compress Formats

Code samples

# You can also use wget
curl -X GET https://api.freeconvert.com/v1/query/formats/compress \
  -H 'Accept: application/json'

GET https://api.freeconvert.com/v1/query/formats/compress HTTP/1.1
Host: api.freeconvert.com
Accept: application/json


const headers = {
  'Accept':'application/json'
};

fetch('https://api.freeconvert.com/v1/query/formats/compress',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://api.freeconvert.com/v1/query/formats/compress',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.freeconvert.com/v1/query/formats/compress', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.freeconvert.com/v1/query/formats/compress', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/query/formats/compress");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.freeconvert.com/v1/query/formats/compress", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }

    /// Make a dummy request
    public async Task MakeGetRequest()
    {
      string url = "https://api.freeconvert.com/v1/query/formats/compress";
      var result = await GetAsync(url);
    }

    /// Performs a GET Request
    public async Task GetAsync(string url)
    {
        //Start the request
        HttpResponseMessage response = await Client.GetAsync(url);

        //Validate result
        response.EnsureSuccessStatusCode();

    }




    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

GET /query/formats/compress

Parameters

Name	In	Type	Required	Description
input_format	query	string	false	Input file extension. Specify `*` to indicate all formats.
output_format	query	string	false	Output file extension. Specify `*` to indicate all formats.

Example responses

200 Response

{
  "formats": [
    {
      "ext": "3gp"
    },
    {
      "ext": "avi"
    },
    {
      "ext": "flv"
    },
    {
      "ext": "mkv"
    },
    {
      "ext": "mov"
    },
    {
      "ext": "mp4"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully get list of possible formats for compress operation.	None
400	Bad Request	Bad Request	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Merge Formats

Code samples

# You can also use wget
curl -X GET https://api.freeconvert.com/v1/query/formats/merge \
  -H 'Accept: application/json'

GET https://api.freeconvert.com/v1/query/formats/merge HTTP/1.1
Host: api.freeconvert.com
Accept: application/json


const headers = {
  'Accept':'application/json'
};

fetch('https://api.freeconvert.com/v1/query/formats/merge',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://api.freeconvert.com/v1/query/formats/merge',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.freeconvert.com/v1/query/formats/merge', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.freeconvert.com/v1/query/formats/merge', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/query/formats/merge");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.freeconvert.com/v1/query/formats/merge", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }

    /// Make a dummy request
    public async Task MakeGetRequest()
    {
      string url = "https://api.freeconvert.com/v1/query/formats/merge";
      var result = await GetAsync(url);
    }

    /// Performs a GET Request
    public async Task GetAsync(string url)
    {
        //Start the request
        HttpResponseMessage response = await Client.GetAsync(url);

        //Validate result
        response.EnsureSuccessStatusCode();

    }




    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

GET /query/formats/merge

Parameters

Name	In	Type	Required	Description
input_format	query	string	false	Input file extension. Specify `*` to indicate all formats.
output_format	query	string	false	Output file extension. Specify `*` to indicate all formats.

Example responses

200 Response

{
  "formats": [
    {
      "ext": "gif"
    },
    {
      "ext": "pdf"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully get list of possible formats for merge operation.	None
400	Bad Request	Bad Request	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Crop Formats

Code samples

# You can also use wget
curl -X GET https://api.freeconvert.com/v1/query/formats/crop \
  -H 'Accept: application/json'

GET https://api.freeconvert.com/v1/query/formats/crop HTTP/1.1
Host: api.freeconvert.com
Accept: application/json


const headers = {
  'Accept':'application/json'
};

fetch('https://api.freeconvert.com/v1/query/formats/crop',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://api.freeconvert.com/v1/query/formats/crop',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.freeconvert.com/v1/query/formats/crop', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.freeconvert.com/v1/query/formats/crop', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/query/formats/crop");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.freeconvert.com/v1/query/formats/crop", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }

    /// Make a dummy request
    public async Task MakeGetRequest()
    {
      string url = "https://api.freeconvert.com/v1/query/formats/crop";
      var result = await GetAsync(url);
    }

    /// Performs a GET Request
    public async Task GetAsync(string url)
    {
        //Start the request
        HttpResponseMessage response = await Client.GetAsync(url);

        //Validate result
        response.EnsureSuccessStatusCode();

    }




    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

GET /query/formats/crop

Parameters

Name	In	Type	Required	Description
input_format	query	string	false	Input file extension. Specify `*` to indicate all formats.
output_format	query	string	false	Output file extension. Specify `*` to indicate all formats.

Example responses

200 Response

{
  "formats": [
    {
      "ext": "mkv"
    },
    {
      "ext": "flv"
    },
    {
      "ext": "mov"
    },
    {
      "ext": "avi"
    },
    {
      "ext": "webm"
    },
    {
      "ext": "wmv"
    },
    {
      "ext": "ogv"
    },
    {
      "ext": "3gp"
    },
    {
      "ext": "mp4"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully get list of possible formats for crop operation	None
400	Bad Request	Bad Request	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Trim Formats

Code samples

# You can also use wget
curl -X GET https://api.freeconvert.com/v1/query/formats/trim \
  -H 'Accept: application/json'

GET https://api.freeconvert.com/v1/query/formats/trim HTTP/1.1
Host: api.freeconvert.com
Accept: application/json


const headers = {
  'Accept':'application/json'
};

fetch('https://api.freeconvert.com/v1/query/formats/trim',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://api.freeconvert.com/v1/query/formats/trim',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.freeconvert.com/v1/query/formats/trim', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.freeconvert.com/v1/query/formats/trim', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/query/formats/trim");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.freeconvert.com/v1/query/formats/trim", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }

    /// Make a dummy request
    public async Task MakeGetRequest()
    {
      string url = "https://api.freeconvert.com/v1/query/formats/trim";
      var result = await GetAsync(url);
    }

    /// Performs a GET Request
    public async Task GetAsync(string url)
    {
        //Start the request
        HttpResponseMessage response = await Client.GetAsync(url);

        //Validate result
        response.EnsureSuccessStatusCode();

    }




    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

GET /query/formats/trim

Parameters

Name	In	Type	Required	Description
input_format	query	string	false	Input file extension. Specify `*` to indicate all formats.
output_format	query	string	false	Output file extension. Specify `*` to indicate all formats.

Example responses

200 Response

{
  "formats": [
    {
      "ext": "ogv"
    },
    {
      "ext": "flv"
    },
    {
      "ext": "avi"
    },
    {
      "ext": "mov"
    },
    {
      "ext": "mkv"
    },
    {
      "ext": "webm"
    },
    {
      "ext": "mp4"
    },
    {
      "ext": "3gp"
    },
    {
      "ext": "wmv"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully get list of possible formats for trim operation	None
400	Bad Request	Bad Request	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Tasks

Tasks are the building blocks of FreeConvert.com API. A job, such as converting a file, usually involves several tasks. For example, for a file conversion job, you would typically create a file import task, convert task, and finally an export task.

Different tasks have their own API endpoints. For example, for converting a file you can use the convert task endpoint.

List Tasks

Code samples

# You can also use wget
curl -X GET https://api.freeconvert.com/v1/process/tasks \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET https://api.freeconvert.com/v1/process/tasks HTTP/1.1
Host: api.freeconvert.com
Accept: application/json


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/tasks',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://api.freeconvert.com/v1/process/tasks',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.freeconvert.com/v1/process/tasks', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.freeconvert.com/v1/process/tasks', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/tasks");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.freeconvert.com/v1/process/tasks", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }

    /// Make a dummy request
    public async Task MakeGetRequest()
    {
      string url = "https://api.freeconvert.com/v1/process/tasks";
      var result = await GetAsync(url);
    }

    /// Performs a GET Request
    public async Task GetAsync(string url)
    {
        //Start the request
        HttpResponseMessage response = await Client.GetAsync(url);

        //Validate result
        response.EnsureSuccessStatusCode();

    }




    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

GET /process/tasks

Get a list of all tasks for the current user with their payload, results, and status.

Parameters

Name	In	Type	Required	Description
status	query	string	false	List tasks matching the specified status [`created`, `processing`, `completed`, `canceled`, `failed`, `deleted`]
operation	query	string	false	FIlter the list to only show tasks with a given operation (for example, `import/url`, `convert...etc.)`
job	query	string	false	Show a list of tasks for the specified job id.
per_page	query	integer	false	Number of tasks per page, defaults to 50. Limited at 200.
page	query	integer	false	If the list of tasks include multiple pages, this specify which page to show.

Example responses

200 Response

{
  "docs": [
    {
      "id": "64e81136fb3a03d26709a152",
      "name": "mytask1",
      "operation": "convert",
      "status": "completed",
      "payload": {
        "options": {
          "image_custom_width": 450,
          "image_custom_height": 300
        }
      },
      "dependsOn": [
        "64ec4fee50e994476de7846d"
      ],
      "job": "64de4d4bc4f617b95a2e4ac0",
      "user": "620deb73617adb001968c8eb",
      "result": {
        "url": "https://s1.freeconvert.com/task/64e5785d555d3b23720c4fd3/tm_logo.jpg"
      },
      "createdAt": "2016-08-29T09:12:33.001Z",
      "startedAt": "2016-08-29T09:12:33.001Z",
      "endedAt": "2016-08-29T09:12:33.001Z",
      "updatedAt": "2016-08-29T09:12:33.001Z",
      "expiresAt": "2016-08-29T09:12:33.001Z"
    }
  ],
  "totalDocs": 150,
  "limit": 10,
  "totalPages": 15,
  "page": 1,
  "pagingCounter": 16,
  "hasPrevPage": false,
  "hasNextPage": true,
  "prevPage": null,
  "nextPage": 2
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful tasks lookup, returns a list of tasks in the response body.	Inline
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Show a Task

Code samples

# You can also use wget
curl -X GET https://api.freeconvert.com/v1/process/tasks/{taskId} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET https://api.freeconvert.com/v1/process/tasks/{taskId} HTTP/1.1
Host: api.freeconvert.com
Accept: application/json


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/tasks/{taskId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://api.freeconvert.com/v1/process/tasks/{taskId}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.freeconvert.com/v1/process/tasks/{taskId}', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.freeconvert.com/v1/process/tasks/{taskId}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/tasks/{taskId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.freeconvert.com/v1/process/tasks/{taskId}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }

    /// Make a dummy request
    public async Task MakeGetRequest()
    {
      string url = "https://api.freeconvert.com/v1/process/tasks/{taskId}";
      var result = await GetAsync(url);
    }

    /// Performs a GET Request
    public async Task GetAsync(string url)
    {
        //Start the request
        HttpResponseMessage response = await Client.GetAsync(url);

        //Validate result
        response.EnsureSuccessStatusCode();

    }




    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

GET /process/tasks/{taskId}

Show details of a task using its task Id.

Parameters

Name	In	Type	Required	Description
taskId	path	string(ObjectID)	true	ID of the task to show.
include	query	string	false	Use this option to include `payload`, and `job` details in the result. You can seperate multiple inlude values with a comma.

Example responses

200 Response

{
  "id": "64e81136fb3a03d26709a152",
  "name": "mytask1",
  "operation": "convert",
  "status": "completed",
  "payload": {
    "options": {
      "image_custom_width": 450,
      "image_custom_height": 300
    }
  },
  "dependsOn": [
    "64ec4fee50e994476de7846d"
  ],
  "job": "64de4d4bc4f617b95a2e4ac0",
  "user": "620deb73617adb001968c8eb",
  "result": {
    "url": "https://s1.freeconvert.com/task/64e5785d555d3b23720c4fd3/tm_logo.jpg"
  },
  "createdAt": "2016-08-29T09:12:33.001Z",
  "startedAt": "2016-08-29T09:12:33.001Z",
  "endedAt": "2016-08-29T09:12:33.001Z",
  "updatedAt": "2016-08-29T09:12:33.001Z",
  "expiresAt": "2016-08-29T09:12:33.001Z"
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful lookup. Task details are returned in the response body.	Task
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
404	Not Found	Content not found	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Delete a Task

Code samples

# You can also use wget
curl -X DELETE https://api.freeconvert.com/v1/process/tasks/{taskId} \
  -H 'Authorization: Bearer {access-token}'

DELETE https://api.freeconvert.com/v1/process/tasks/{taskId} HTTP/1.1
Host: api.freeconvert.com


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/tasks/{taskId}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.delete 'https://api.freeconvert.com/v1/process/tasks/{taskId}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('https://api.freeconvert.com/v1/process/tasks/{taskId}', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('DELETE','https://api.freeconvert.com/v1/process/tasks/{taskId}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/tasks/{taskId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api.freeconvert.com/v1/process/tasks/{taskId}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }




    /// Make a dummy request
    public async Task MakeDeleteRequest()
    {
      int id = 1;
      string url = "https://api.freeconvert.com/v1/process/tasks/{taskId}";

      await DeleteAsync(id, url);
    }

    /// Performs a DELETE Request
    public async Task DeleteAsync(int id, string url)
    {
        //Execute DELETE request
        HttpResponseMessage response = await Client.DeleteAsync(url + $"/{id}");

        //Return response
        await DeserializeObject(response);
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

DELETE /process/tasks/{taskId}

Deleting a task also deletes its files.

All tasks are automatically removed after 24 hours of creation. Files from a task are deleted 4 hours after the task creation.

Parameters

Name	In	Type	Required	Description
taskId	path	string(ObjectID)	true	ID of the task to delete.

Responses

Status	Meaning	Description	Schema
200	OK	Task successfully deleted (empty response body).	None
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
404	Not Found	Content not found	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Cancel a Task

Code samples

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/tasks/{taskId}/cancel \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.freeconvert.com/v1/process/tasks/{taskId}/cancel HTTP/1.1
Host: api.freeconvert.com
Accept: application/json


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/tasks/{taskId}/cancel',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.freeconvert.com/v1/process/tasks/{taskId}/cancel',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.freeconvert.com/v1/process/tasks/{taskId}/cancel', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.freeconvert.com/v1/process/tasks/{taskId}/cancel', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/tasks/{taskId}/cancel");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.freeconvert.com/v1/process/tasks/{taskId}/cancel", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }


    /// Make a dummy request
    public async Task MakePostRequest()
    {
      string url = "https://api.freeconvert.com/v1/process/tasks/{taskId}/cancel";


      await PostAsync(null, url);

    }

    /// Performs a POST Request
    public async Task PostAsync(undefined content, string url)
    {
        //Serialize Object
        StringContent jsonContent = SerializeObject(content);

        //Execute POST request
        HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
    }



    /// Serialize an object to Json
    private StringContent SerializeObject(undefined content)
    {
        //Serialize Object
        string jsonObject = JsonConvert.SerializeObject(content);

        //Create Json UTF8 String Content
        return new StringContent(jsonObject, Encoding.UTF8, "application/json");
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

POST /process/tasks/{taskId}/cancel

Cancel a task that has a status of created or processing. If you cancel a task, all tasks that depends on it will also fail.

Parameters

Name	In	Type	Required	Description
taskId	path	string(ObjectID)	true	ID of task to cancel

Example responses

200 Response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "mytask1",
  "operation": "convert",
  "status": "canceled",
  "payload": {
    "options": {
      "image_custom_width": 450,
      "image_custom_height": 300
    }
  },
  "job": "4bbaedb0-902b-4b27-8218-8f40d3470a54",
  "result": {
    "url": "https://s1.freeconvert.com/task/64e5785d555d3b23720c4fd3/tm_logo.jpg"
  },
  "createdAt": "2016-08-29T09:12:33.001Z",
  "startedAt": "2016-08-29T09:12:33.001Z",
  "endedAt": "2016-08-29T09:12:33.001Z",
  "updatedAt": "2016-08-29T09:12:33.001Z",
  "expiresAt": "2016-08-29T09:12:33.001Z"
}

Responses

Status	Meaning	Description	Schema
200	OK	Returns the updated task details (status, operation...etc)	None
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
404	Not Found	Content not found	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Jobs

List Jobs

Code samples

# You can also use wget
curl -X GET https://api.freeconvert.com/v1/process/jobs \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET https://api.freeconvert.com/v1/process/jobs HTTP/1.1
Host: api.freeconvert.com
Accept: application/json


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/jobs',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://api.freeconvert.com/v1/process/jobs',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.freeconvert.com/v1/process/jobs', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.freeconvert.com/v1/process/jobs', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/jobs");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.freeconvert.com/v1/process/jobs", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }

    /// Make a dummy request
    public async Task MakeGetRequest()
    {
      string url = "https://api.freeconvert.com/v1/process/jobs";
      var result = await GetAsync(url);
    }

    /// Performs a GET Request
    public async Task GetAsync(string url)
    {
        //Start the request
        HttpResponseMessage response = await Client.GetAsync(url);

        //Validate result
        response.EnsureSuccessStatusCode();

    }




    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

GET /process/jobs

Get a list of all jobs for the current user

Parameters

Name	In	Type	Required	Description
status	query	string	false	List jobs matching the specified status. Possible statuses are [`created`, `processing`, `completed`, `failed`]
tag	query	string	false	Show a list of jobs containing the specified tag.
include	query	string	false	Include additional info in the returned Job data. Possible values: `tasks`
per_page	query	integer	false	Number of jobs per page, defaults to 50. Limited at 200.
page	query	integer	false	If the list of jobs include multiple pages, this specify which page to show.

Example responses

200 Response

{
  "docs": [
    {
      "id": "5ff3e22059136b0023324b1f",
      "tag": "my-job",
      "createdAt": "2016-08-29T09:12:33.001Z",
      "updatedAt": "2016-08-29T09:12:33.001Z",
      "startedAt": "2016-08-29T09:12:33.001Z",
      "status": "created",
      "tasks": [
        {
          "name": "import-1",
          "operation": "import/upload",
          "status": "processing",
          "job": "5ff3e22059136b0023324b1f",
          "user": "620deb73617adb001968c8eb",
          "createdAt": "2021-01-05T03:50:56.067Z",
          "updatedAt": "2021-01-05T03:50:56.115Z",
          "expiresAt": "2021-01-05T03:50:56.115Z",
          "endedAt": null,
          "result": {
            "form": {
              "url": "https://server1.freeconvert.com/api/upload/5ff3e7337e69c10060706883",
              "parameters": {
                "signature": "46d0fab9c3534661"
              }
            }
          },
          "id": "64ec4fef50e994476de78470"
        },
        {
          "name": "convert-1",
          "operation": "convert",
          "status": "processing",
          "job": "5ff3e22059136b0023324b1f",
          "user": "620deb73617adb001968c8eb",
          "payload": {
            "input_format": "jpg",
            "output_format": "png",
            "options": {
              "quality": 75
            }
          },
          "dependsOn": [
            "64ec4fef50e994476de78470"
          ],
          "createdAt": "2021-01-05T03:50:56.067Z",
          "updatedAt": "2021-01-05T03:50:56.115Z",
          "expiresAt": "2021-01-05T03:50:56.115Z",
          "endedAt": null,
          "id": "64ec5b3750e994476de786e7"
        },
        {
          "name": "export-1",
          "operation": "export/url",
          "status": "processing",
          "job": "5ff3e22059136b0023324b1f",
          "user": "620deb73617adb001968c8eb",
          "payload": {
            "filename": "some.pdf",
            "archive_multiple_files": true
          },
          "dependsOn": [
            "64ec5b3750e994476de786e7"
          ],
          "createdAt": "2021-01-05T03:50:56.067Z",
          "updatedAt": "2021-01-05T03:50:56.115Z",
          "expiresAt": "2021-01-05T03:50:56.115Z",
          "endedAt": null,
          "id": "64ec4fef50e994476de78475"
        }
      ]
    }
  ],
  "totalDocs": 150,
  "limit": 10,
  "totalPages": 15,
  "page": 1,
  "pagingCounter": 16,
  "hasPrevPage": false,
  "hasNextPage": true,
  "prevPage": null,
  "nextPage": 2
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful jobs lookup, returns a list of jobs in the response body. You can get more details on the response format by referring to Show a Job endpoint	Inline
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Create Job

Code samples

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/jobs \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.freeconvert.com/v1/process/jobs HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "tag": "custom-tag",
  "tasks": {
    "my-upload-1": {
      "operation": "import/upload"
    },
    "convert-task-1": {
      "operation": "convert",
      "input": "my-upload-1",
      "output_format": "png"
    },
    "export-task-1": {
      "operation": "export/url",
      "input": "convert-task-1",
      "filename": "output-file.png"
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/jobs',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.freeconvert.com/v1/process/jobs',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.freeconvert.com/v1/process/jobs', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.freeconvert.com/v1/process/jobs', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/jobs");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.freeconvert.com/v1/process/jobs", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }


    /// Make a dummy request
    public async Task MakePostRequest()
    {
      string url = "https://api.freeconvert.com/v1/process/jobs";


      await PostAsync(null, url);

    }

    /// Performs a POST Request
    public async Task PostAsync(undefined content, string url)
    {
        //Serialize Object
        StringContent jsonContent = SerializeObject(content);

        //Execute POST request
        HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
    }



    /// Serialize an object to Json
    private StringContent SerializeObject(undefined content)
    {
        //Serialize Object
        string jsonObject = JsonConvert.SerializeObject(content);

        //Create Json UTF8 String Content
        return new StringContent(jsonObject, Encoding.UTF8, "application/json");
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

POST /process/jobs

Creates a new job along with all of its tasks. A job cretaion request must include at least one task.

When you initiate a job with the Create job API, you would receive real-time updates of your tasks and jobs via WebSocket. Please see API code examples.

Body parameter

{
  "tag": "custom-tag",
  "tasks": {
    "my-upload-1": {
      "operation": "import/upload"
    },
    "convert-task-1": {
      "operation": "convert",
      "input": "my-upload-1",
      "output_format": "png"
    },
    "export-task-1": {
      "operation": "export/url",
      "input": "convert-task-1",
      "filename": "output-file.png"
    }
  }
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	CODE SAMPLES at the right panel
» tag	body	string	false	An abitrary string which has no effect. It can be used to identify a job with an ID in your system/application.
» tasks	body	object	true	A job consists of one or more tasks. For example, the example shown inludes an import, conversion, and a export task. Task names should only contain alphanumerals, dash (-), and underscore (_).
»» operation	body	string	true	Specify the endpoint for the given task. For example, `import/upload`, `convert`, `export/s3`...etc.
»» input	body	string or array	false	Specify the names of the input tasks for the task. For example, in a `convert` task, you can enter the `import` task's name to convert that specific imported file. You can also enter multiple input task names in an array.
»» Other	body	string	false	List of available properties for a task depending on the task's `operation`.

Example responses

201 Response

{
  "id": "5ff3e22059136b0023324b1f",
  "tag": "my-job",
  "createdAt": "2016-08-29T09:12:33.001Z",
  "updatedAt": "2016-08-29T09:12:33.001Z",
  "startedAt": "2016-08-29T09:12:33.001Z",
  "status": "created",
  "tasks": [
    {
      "name": "import-1",
      "operation": "import/upload",
      "status": "processing",
      "job": "5ff3e22059136b0023324b1f",
      "user": "620deb73617adb001968c8eb",
      "createdAt": "2021-01-05T03:50:56.067Z",
      "updatedAt": "2021-01-05T03:50:56.115Z",
      "expiresAt": "2021-01-05T03:50:56.115Z",
      "endedAt": null,
      "result": {
        "form": {
          "url": "https://server1.freeconvert.com/api/upload/5ff3e7337e69c10060706883",
          "parameters": {
            "signature": "46d0fab9c3534661"
          }
        }
      },
      "id": "64ec4fef50e994476de78470"
    },
    {
      "name": "convert-1",
      "operation": "convert",
      "status": "processing",
      "job": "5ff3e22059136b0023324b1f",
      "user": "620deb73617adb001968c8eb",
      "payload": {
        "input_format": "jpg",
        "output_format": "png",
        "options": {
          "quality": 75
        }
      },
      "dependsOn": [
        "64ec4fef50e994476de78470"
      ],
      "createdAt": "2021-01-05T03:50:56.067Z",
      "updatedAt": "2021-01-05T03:50:56.115Z",
      "expiresAt": "2021-01-05T03:50:56.115Z",
      "endedAt": null,
      "id": "64ec5b3750e994476de786e7"
    },
    {
      "name": "export-1",
      "operation": "export/url",
      "status": "processing",
      "job": "5ff3e22059136b0023324b1f",
      "user": "620deb73617adb001968c8eb",
      "payload": {
        "filename": "some.pdf",
        "archive_multiple_files": true
      },
      "dependsOn": [
        "64ec5b3750e994476de786e7"
      ],
      "createdAt": "2021-01-05T03:50:56.067Z",
      "updatedAt": "2021-01-05T03:50:56.115Z",
      "expiresAt": "2021-01-05T03:50:56.115Z",
      "endedAt": null,
      "id": "64ec4fef50e994476de78475"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
201	Created	Job succesfully created. Returns details of the created job as per the Show jobs endpoint.	Job
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Show a Job

Code samples

# You can also use wget
curl -X GET https://api.freeconvert.com/v1/process/jobs/{jobId} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET https://api.freeconvert.com/v1/process/jobs/{jobId} HTTP/1.1
Host: api.freeconvert.com
Accept: application/json


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/jobs/{jobId}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://api.freeconvert.com/v1/process/jobs/{jobId}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://api.freeconvert.com/v1/process/jobs/{jobId}', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.freeconvert.com/v1/process/jobs/{jobId}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/jobs/{jobId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.freeconvert.com/v1/process/jobs/{jobId}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }

    /// Make a dummy request
    public async Task MakeGetRequest()
    {
      string url = "https://api.freeconvert.com/v1/process/jobs/{jobId}";
      var result = await GetAsync(url);
    }

    /// Performs a GET Request
    public async Task GetAsync(string url)
    {
        //Start the request
        HttpResponseMessage response = await Client.GetAsync(url);

        //Validate result
        response.EnsureSuccessStatusCode();

    }




    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

GET /process/jobs/{jobId}

Show details of a job using its job ID.

Parameters

Name	In	Type	Required	Description
jobId	path	string(ObjectID)	true	ID of the job to show

Example responses

200 Response

{
  "id": "5ff3e22059136b0023324b1f",
  "tag": "my-job",
  "createdAt": "2016-08-29T09:12:33.001Z",
  "updatedAt": "2016-08-29T09:12:33.001Z",
  "startedAt": "2016-08-29T09:12:33.001Z",
  "status": "created",
  "tasks": [
    {
      "name": "import-1",
      "operation": "import/upload",
      "status": "processing",
      "job": "5ff3e22059136b0023324b1f",
      "user": "620deb73617adb001968c8eb",
      "createdAt": "2021-01-05T03:50:56.067Z",
      "updatedAt": "2021-01-05T03:50:56.115Z",
      "expiresAt": "2021-01-05T03:50:56.115Z",
      "endedAt": null,
      "result": {
        "form": {
          "url": "https://server1.freeconvert.com/api/upload/5ff3e7337e69c10060706883",
          "parameters": {
            "signature": "46d0fab9c3534661"
          }
        }
      },
      "id": "64ec4fef50e994476de78470"
    },
    {
      "name": "convert-1",
      "operation": "convert",
      "status": "processing",
      "job": "5ff3e22059136b0023324b1f",
      "user": "620deb73617adb001968c8eb",
      "payload": {
        "input_format": "jpg",
        "output_format": "png",
        "options": {
          "quality": 75
        }
      },
      "dependsOn": [
        "64ec4fef50e994476de78470"
      ],
      "createdAt": "2021-01-05T03:50:56.067Z",
      "updatedAt": "2021-01-05T03:50:56.115Z",
      "expiresAt": "2021-01-05T03:50:56.115Z",
      "endedAt": null,
      "id": "64ec5b3750e994476de786e7"
    },
    {
      "name": "export-1",
      "operation": "export/url",
      "status": "processing",
      "job": "5ff3e22059136b0023324b1f",
      "user": "620deb73617adb001968c8eb",
      "payload": {
        "filename": "some.pdf",
        "archive_multiple_files": true
      },
      "dependsOn": [
        "64ec5b3750e994476de786e7"
      ],
      "createdAt": "2021-01-05T03:50:56.067Z",
      "updatedAt": "2021-01-05T03:50:56.115Z",
      "expiresAt": "2021-01-05T03:50:56.115Z",
      "endedAt": null,
      "id": "64ec4fef50e994476de78475"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful lookup. Job details returned in the response body.	Job
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
404	Not Found	Content not found	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Delete a Job

Code samples

# You can also use wget
curl -X DELETE https://api.freeconvert.com/v1/process/jobs/{jobId} \
  -H 'Authorization: Bearer {access-token}'

DELETE https://api.freeconvert.com/v1/process/jobs/{jobId} HTTP/1.1
Host: api.freeconvert.com


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/jobs/{jobId}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.delete 'https://api.freeconvert.com/v1/process/jobs/{jobId}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('https://api.freeconvert.com/v1/process/jobs/{jobId}', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('DELETE','https://api.freeconvert.com/v1/process/jobs/{jobId}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/jobs/{jobId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api.freeconvert.com/v1/process/jobs/{jobId}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }




    /// Make a dummy request
    public async Task MakeDeleteRequest()
    {
      int id = 1;
      string url = "https://api.freeconvert.com/v1/process/jobs/{jobId}";

      await DeleteAsync(id, url);
    }

    /// Performs a DELETE Request
    public async Task DeleteAsync(int id, string url)
    {
        //Execute DELETE request
        HttpResponseMessage response = await Client.DeleteAsync(url + $"/{id}");

        //Return response
        await DeserializeObject(response);
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

DELETE /process/jobs/{jobId}

Deleting a job would delete all the tasks and files of that job.

All files that belongs to a task within a job are automatically deleted 4 hours after task creation. Job entries are deleted after 24 hours of creation.

Parameters

Name	In	Type	Required	Description
jobId	path	string(ObjectID)	true	ID of the job to delete.

Responses

Status	Meaning	Description	Schema
200	OK	Job succesfully deleted (empty response body).	None
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
404	Not Found	Content not found	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Import Files

URL

Code samples

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/import/url \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.freeconvert.com/v1/process/import/url HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "url": "https://example.com/some.jpg",
  "filename": "some.jpg"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/import/url',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.freeconvert.com/v1/process/import/url',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.freeconvert.com/v1/process/import/url', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.freeconvert.com/v1/process/import/url', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/import/url");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.freeconvert.com/v1/process/import/url", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }


    /// Make a dummy request
    public async Task MakePostRequest()
    {
      string url = "https://api.freeconvert.com/v1/process/import/url";


      await PostAsync(null, url);

    }

    /// Performs a POST Request
    public async Task PostAsync(undefined content, string url)
    {
        //Serialize Object
        StringContent jsonContent = SerializeObject(content);

        //Execute POST request
        HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
    }



    /// Serialize an object to Json
    private StringContent SerializeObject(undefined content)
    {
        //Serialize Object
        string jsonObject = JsonConvert.SerializeObject(content);

        //Create Json UTF8 String Content
        return new StringContent(jsonObject, Encoding.UTF8, "application/json");
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

POST /process/import/url

Creates a new task to import a file into FreeConvert from a URL. See Getting Started - Import file from URL

Body parameter

{
  "url": "https://example.com/some.jpg",
  "filename": "some.jpg"
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	CODE SAMPLES at the right panel
» url	body	string	true	The URL of the remote file
» filename	body	string	false	Override the name of the imported file

Example responses

201 Response

{
  "status": "processing",
  "job": "5ff3e22059136b0023324b1f",
  "payload": {
    "filename": "logo.jpg",
    "url": "https://example.com/icon.jpg",
    "operation": "import/url"
  },
  "operation": "import/url",
  "user": "620deb73617adb001968c8eb",
  "createdAt": "2021-01-05T03:50:56.067Z",
  "updatedAt": "2021-01-05T03:50:56.115Z",
  "expiresAt": "2021-01-05T03:50:56.115Z",
  "endedAt": null,
  "id": "5ff3e22059136b0023324b20"
}

Responses

Status	Meaning	Description	Schema
201	Created	Task succesfully created. Returns details of the created task as per the show tasks	None
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Upload

Code samples

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/import/upload \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.freeconvert.com/v1/process/import/upload HTTP/1.1
Host: api.freeconvert.com
Accept: application/json


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/import/upload',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.freeconvert.com/v1/process/import/upload',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.freeconvert.com/v1/process/import/upload', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.freeconvert.com/v1/process/import/upload', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/import/upload");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.freeconvert.com/v1/process/import/upload", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }


    /// Make a dummy request
    public async Task MakePostRequest()
    {
      string url = "https://api.freeconvert.com/v1/process/import/upload";


      await PostAsync(null, url);

    }

    /// Performs a POST Request
    public async Task PostAsync(undefined content, string url)
    {
        //Serialize Object
        StringContent jsonContent = SerializeObject(content);

        //Execute POST request
        HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
    }



    /// Serialize an object to Json
    private StringContent SerializeObject(undefined content)
    {
        //Serialize Object
        string jsonObject = JsonConvert.SerializeObject(content);

        //Create Json UTF8 String Content
        return new StringContent(jsonObject, Encoding.UTF8, "application/json");
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

POST /process/import/upload

Creates an upload task to submit one file to FreeConvert.com. You can also use this method to directly send your user's files to FreeConvert without storing them on your application. See Getting Started - Import file from device

For example, you could use the form object in the result key of the response to allow browser-based file uploading.

Here is a Form Upload Example (in the right panel) on how to utilize the url and other post parameters from our response to create a file upload form. Please see API code examples for more.

Form Upload Example

<form action="https://server1.freeconvert.com/api/upload/5ff3e7337e69c10060706883/"
  method="POST"
  enctype="multipart/form-data">    
    <input type="hidden" name="signature" value="46d0fab9c3534661">
    <input type="file" name="file">
    <input type="submit">
</form>

IMPORTANT parameters (both keys and values) are dynamically generated. Do not hardcode them in your application.

Task status change to completed as soon as the upload finishes.

Example responses

201 Response

{
  "status": "processing",
  "job": "5ff3e22059136b0023324b1f",
  "operation": "import/upload",
  "user": "620deb73617adb001968c8eb",
  "createdAt": "2021-01-05T03:50:56.067Z",
  "updatedAt": "2021-01-05T03:50:56.115Z",
  "expiresAt": "2021-01-05T03:50:56.115Z",
  "endedAt": null,
  "result": {
    "form": {
      "url": "https://server1.freeconvert.com/api/upload/5ff3e7337e69c10060706883",
      "parameters": {
        "signature": "46d0fab9c3534661"
      }
    }
  },
  "id": "5ff3e22059136b0023324b20"
}

Responses

Status	Meaning	Description	Schema
201	Created	File successfully imported.	None
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Google Cloud Storage

Code samples

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/import/googlecloud \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.freeconvert.com/v1/process/import/googlecloud HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "project_id": "demo_project_id",
  "bucket": "bucket-demo",
  "client_email": "demo@1234.iam.gserviceaccount.com",
  "private_key": "private key",
  "file": "demo.pdf"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/import/googlecloud',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.freeconvert.com/v1/process/import/googlecloud',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.freeconvert.com/v1/process/import/googlecloud', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.freeconvert.com/v1/process/import/googlecloud', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/import/googlecloud");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.freeconvert.com/v1/process/import/googlecloud", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }


    /// Make a dummy request
    public async Task MakePostRequest()
    {
      string url = "https://api.freeconvert.com/v1/process/import/googlecloud";


      await PostAsync(null, url);

    }

    /// Performs a POST Request
    public async Task PostAsync(undefined content, string url)
    {
        //Serialize Object
        StringContent jsonContent = SerializeObject(content);

        //Execute POST request
        HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
    }



    /// Serialize an object to Json
    private StringContent SerializeObject(undefined content)
    {
        //Serialize Object
        string jsonObject = JsonConvert.SerializeObject(content);

        //Create Json UTF8 String Content
        return new StringContent(jsonObject, Encoding.UTF8, "application/json");
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

POST /process/import/googlecloud

Creates a new task to import a file form google cloud storage into FreeConvert

Body parameter

{
  "project_id": "demo_project_id",
  "bucket": "bucket-demo",
  "client_email": "demo@1234.iam.gserviceaccount.com",
  "private_key": "private key",
  "file": "demo.pdf"
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	CODE SAMPLES at the right panel
» project_id	body	string	true	The Google Cloud Project ID (api-project-...).
» bucket	body	string	true	The Google Cloud Storage Bucket name.
» client_email	body	string	true	The client email of the service account to use (...@api-project-....iam.gserviceaccount.com).
» private_key	body	string	true	The private key of the service account.
» file	body	string	true	Filename of the input file (the filename in the bucket, including path).
» filename	body	string	false	Override the filename of the imported file. Otherwise filename will be extracted from the file parameter.

Example responses

201 Response

{
  "status": "processing",
  "startedAt": "2021-12-19T09:53:11.330Z",
  "endedAt": null,
  "expiresAt": "2021-12-19T07:02:15.724Z",
  "payload": {
    "project_id": "vast-cogency-329405",
    "bucket": "demo",
    "client_email": "demo@1234.iam.gserviceaccount.com",
    "private_key": "",
    "file": "demo.pdf"
  },
  "job": "61bf0107e39b480011724973",
  "name": "import",
  "operation": "import/googlecloud",
  "user": "620deb73617adb001968c8eb",
  "createdAt": "2021-12-19T09:53:11.148Z",
  "updatedAt": "2021-12-19T09:53:11.331Z",
  "id": "61bf0107e39b480011724974"
}

Responses

Status	Meaning	Description	Schema
201	Created	Task succesfully created. Returns details of the created task as per the show tasks	None
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Azure Blob

Code samples

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/import/azureblob \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.freeconvert.com/v1/process/import/azureblob HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "container": "container_name",
  "storage_account": "storage_account_name",
  "storage_access_key": "storage_access_key",
  "blob": "blob name"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/import/azureblob',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.freeconvert.com/v1/process/import/azureblob',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.freeconvert.com/v1/process/import/azureblob', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.freeconvert.com/v1/process/import/azureblob', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/import/azureblob");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.freeconvert.com/v1/process/import/azureblob", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }


    /// Make a dummy request
    public async Task MakePostRequest()
    {
      string url = "https://api.freeconvert.com/v1/process/import/azureblob";


      await PostAsync(null, url);

    }

    /// Performs a POST Request
    public async Task PostAsync(undefined content, string url)
    {
        //Serialize Object
        StringContent jsonContent = SerializeObject(content);

        //Execute POST request
        HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
    }



    /// Serialize an object to Json
    private StringContent SerializeObject(undefined content)
    {
        //Serialize Object
        string jsonObject = JsonConvert.SerializeObject(content);

        //Create Json UTF8 String Content
        return new StringContent(jsonObject, Encoding.UTF8, "application/json");
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

POST /process/import/azureblob

Creates a new task to import a file form azure blob storage into FreeConvert

Body parameter

{
  "container": "container_name",
  "storage_account": "storage_account_name",
  "storage_access_key": "storage_access_key",
  "blob": "blob name"
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	CODE SAMPLES at the right panel
» container	body	string	true	Azure container name.
» storage_account	body	string	true	The name of the Azure storage account (This is the string before.blob.core.windows.net).
» storage_access_key	body	string	true	The Azure secret key. Only required alternatively, if you are not providing a SAS token.
» blob	body	string	true	Azure blob name of the input file (the filename in the bucket, including path).
» sas_token	body	string	false	The Azure SAS token
» filename	body	string	false	Override the filename of the imported file. Otherwise filename will be extracted from the file parameter.

Example responses

201 Response

{
  "status": "processing",
  "startedAt": "2021-12-19T06:06:24.740Z",
  "endedAt": null,
  "expiresAt": "2021-12-19T07:02:15.724Z",
  "payload": {
    "container": "*****",
    "storage_account": "*****",
    "storage_access_key": "*****",
    "blob": "railway.pdf",
    "operation": "import/azureblob"
  },
  "job": "61becbe0e39b480011724969",
  "operation": "import/azureblob",
  "user": "612f012d0c9c43393c424ab6",
  "createdAt": "2021-12-19T06:06:24.689Z",
  "updatedAt": "2021-12-19T06:06:24.741Z",
  "id": "61becbe0e39b48001172496a"
}

Responses

Status	Meaning	Description	Schema
201	Created	Task succesfully created. Returns details of the created task as per the show tasks	None
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

S3

Code samples

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/import/s3 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.freeconvert.com/v1/process/import/s3 HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "bucket": "your_bucket_name",
  "region": "us-east-2",
  "access_key_id": "your_access_key_id",
  "secret_access_key": "the_secret_access_key_of_your_account",
  "key": "file.jpg"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/import/s3',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.freeconvert.com/v1/process/import/s3',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.freeconvert.com/v1/process/import/s3', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.freeconvert.com/v1/process/import/s3', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/import/s3");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.freeconvert.com/v1/process/import/s3", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }


    /// Make a dummy request
    public async Task MakePostRequest()
    {
      string url = "https://api.freeconvert.com/v1/process/import/s3";


      await PostAsync(null, url);

    }

    /// Performs a POST Request
    public async Task PostAsync(undefined content, string url)
    {
        //Serialize Object
        StringContent jsonContent = SerializeObject(content);

        //Execute POST request
        HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
    }



    /// Serialize an object to Json
    private StringContent SerializeObject(undefined content)
    {
        //Serialize Object
        string jsonObject = JsonConvert.SerializeObject(content);

        //Create Json UTF8 String Content
        return new StringContent(jsonObject, Encoding.UTF8, "application/json");
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

POST /process/import/s3

Creates a new task to import a file form S3 bucket into FreeConvert

Body parameter

{
  "bucket": "your_bucket_name",
  "region": "us-east-2",
  "access_key_id": "your_access_key_id",
  "secret_access_key": "the_secret_access_key_of_your_account",
  "key": "file.jpg"
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	CODE SAMPLES at the right panel
» bucket	body	string	true	The Amazon S3 bucket where to download the file
» region	body	string	true	Specify the Amazon S3 endpoint, e.g. us-west-2 or eu-west-1
» access_key_id	body	string	true	AWS access key id
» secret_access_key	body	string	true	AWS secret access key
» key	body	string	true	S3 key of the input file's relative path
» key_prefix	body	string	false	Alternatively to using key, you can specify a key prefix for importing multiple files at once. key_prefix is supported inside Jobs only.
» endpoint	body	string	false	Use a custom S3 API endpoint. The default endpoint is built from the configured region

Example responses

201 Response

{
  "status": "processing",
  "job": "5ff3e22059136b0023324b1f",
  "payload": {
    "bucket": "your_bucket_name",
    "region": "us-east-2",
    "access_key_id": "your_access_key_id",
    "secret_access_key": "the_secret_access_key_of_your_account",
    "key": "file.jpg"
  },
  "operation": "import/s3",
  "user": "620deb73617adb001968c8eb",
  "createdAt": "2021-01-05T03:50:56.067Z",
  "updatedAt": "2021-01-05T03:50:56.115Z",
  "expiresAt": "2021-01-05T03:50:56.115Z",
  "endedAt": null,
  "id": "5ff3e22059136b0023324b20"
}

Responses

Status	Meaning	Description	Schema
201	Created	Task succesfully created. Returns details of the created task as per the show tasks	None
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

SFTP

Code samples

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/import/sftp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.freeconvert.com/v1/process/import/sftp HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "host": "your_sftp_domain_name_or_ip",
  "port": 33,
  "username": "your_sftp_username",
  "password": "your_sftp_password",
  "file_string": "dir/file.jpg"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/import/sftp',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.freeconvert.com/v1/process/import/sftp',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.freeconvert.com/v1/process/import/sftp', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.freeconvert.com/v1/process/import/sftp', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/import/sftp");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.freeconvert.com/v1/process/import/sftp", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }


    /// Make a dummy request
    public async Task MakePostRequest()
    {
      string url = "https://api.freeconvert.com/v1/process/import/sftp";


      await PostAsync(null, url);

    }

    /// Performs a POST Request
    public async Task PostAsync(undefined content, string url)
    {
        //Serialize Object
        StringContent jsonContent = SerializeObject(content);

        //Execute POST request
        HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
    }



    /// Serialize an object to Json
    private StringContent SerializeObject(undefined content)
    {
        //Serialize Object
        string jsonObject = JsonConvert.SerializeObject(content);

        //Create Json UTF8 String Content
        return new StringContent(jsonObject, Encoding.UTF8, "application/json");
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

POST /process/import/sftp

Creates a new task to import a file form SFTP server into FreeConvert

Body parameter

{
  "host": "your_sftp_domain_name_or_ip",
  "port": 33,
  "username": "your_sftp_username",
  "password": "your_sftp_password",
  "file_string": "dir/file.jpg"
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	CODE SAMPLES at the right panel
» host	body	number	true	The SFTP server hostname or ip
» port	body	string	false	The SFTP port. Defaults to 22
» username	body	string	true	The SFTP username
» password	body	string	true	The SFTP password
» private_key	body	string	false	Alternatively to using password, you can provide a private key
» file_string	body	string	true	File name of the input file (the filename on the server, including path)

Example responses

201 Response

{
  "status": "processing",
  "job": "5ff3e22059136b0023324b1f",
  "payload": {
    "host": "your_sftp_domain_name_or_ip",
    "port": 33,
    "username": "your_sftp_username",
    "password": "your_sftp_password",
    "file_string": "dir/file.jpg"
  },
  "operation": "import/sftp",
  "user": "620deb73617adb001968c8eb",
  "createdAt": "2021-01-05T03:50:56.067Z",
  "updatedAt": "2021-01-05T03:50:56.115Z",
  "expiresAt": "2021-01-05T03:50:56.115Z",
  "endedAt": null,
  "id": "5ff3e22059136b0023324b20"
}

Responses

Status	Meaning	Description	Schema
201	Created	Task succesfully created. Returns details of the created task as per the show tasks	None
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Base64

Code samples

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/import/base64 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.freeconvert.com/v1/process/import/base64 HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEKjAqMAAD/2wBDAAoHBwgHBgoICAgLCgoLDhgQDg0NDh0VFhEYIx8lJCIfIiEmKzcvJik0KSEiMEExNDk7Pj4+JS5ESUM8SDc9Pjv/.....",
  "filename": "some.jpg"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/import/base64',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.freeconvert.com/v1/process/import/base64',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.freeconvert.com/v1/process/import/base64', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.freeconvert.com/v1/process/import/base64', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/import/base64");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.freeconvert.com/v1/process/import/base64", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }


    /// Make a dummy request
    public async Task MakePostRequest()
    {
      string url = "https://api.freeconvert.com/v1/process/import/base64";


      await PostAsync(null, url);

    }

    /// Performs a POST Request
    public async Task PostAsync(undefined content, string url)
    {
        //Serialize Object
        StringContent jsonContent = SerializeObject(content);

        //Execute POST request
        HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
    }



    /// Serialize an object to Json
    private StringContent SerializeObject(undefined content)
    {
        //Serialize Object
        string jsonObject = JsonConvert.SerializeObject(content);

        //Create Json UTF8 String Content
        return new StringContent(jsonObject, Encoding.UTF8, "application/json");
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

POST /process/import/base64

Creates a new task to import a file as base64 encoded string into FreeConvert.

Note: The maximum size of base64 encoded file content must be 1.5 MB

Body parameter

{
  "file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEKjAqMAAD/2wBDAAoHBwgHBgoICAgLCgoLDhgQDg0NDh0VFhEYIx8lJCIfIiEmKzcvJik0KSEiMEExNDk7Pj4+JS5ESUM8SDc9Pjv/.....",
  "filename": "some.jpg"
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	CODE SAMPLES at the right panel
» file	body	string	true	The base64 encoded file content
» filename	body	string	true	The filename of the input file, including extension

Example responses

201 Response

{
  "status": "processing",
  "job": "5ff3e22059136b0023324b1f",
  "payload": {
    "file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEKjAqMAAD/2wBDAAoHBwgHBgoICAgLCgoLDhgQDg0NDh0VFhEYIx8lJCIfIiEmKzcvJik0KSEiMEExNDk7Pj4+JS5ESUM8SDc9Pjv/.....",
    "filename": "some.jpg"
  },
  "operation": "import/base64",
  "user": "620deb73617adb001968c8eb",
  "createdAt": "2021-01-05T03:50:56.067Z",
  "updatedAt": "2021-01-05T03:50:56.115Z",
  "expiresAt": "2021-01-05T03:50:56.115Z",
  "endedAt": null,
  "id": "5ff3e22059136b0023324b20"
}

Responses

Status	Meaning	Description	Schema
201	Created	Task succesfully created. Returns details of the created task as per the show tasks	None
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Webpage

Code samples

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/import/webpage \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.freeconvert.com/v1/process/import/webpage HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "url": "https://example.com"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/import/webpage',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.freeconvert.com/v1/process/import/webpage',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.freeconvert.com/v1/process/import/webpage', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.freeconvert.com/v1/process/import/webpage', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/import/webpage");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.freeconvert.com/v1/process/import/webpage", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }


    /// Make a dummy request
    public async Task MakePostRequest()
    {
      string url = "https://api.freeconvert.com/v1/process/import/webpage";


      await PostAsync(null, url);

    }

    /// Performs a POST Request
    public async Task PostAsync(undefined content, string url)
    {
        //Serialize Object
        StringContent jsonContent = SerializeObject(content);

        //Execute POST request
        HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
    }



    /// Serialize an object to Json
    private StringContent SerializeObject(undefined content)
    {
        //Serialize Object
        string jsonObject = JsonConvert.SerializeObject(content);

        //Create Json UTF8 String Content
        return new StringContent(jsonObject, Encoding.UTF8, "application/json");
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

POST /process/import/webpage

Creates a new task to import a webpage into FreeConvert from a URL

Body parameter

{
  "url": "https://example.com"
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	CODE SAMPLES at the right panel
» url	body	string	true	The URL of the webpage

Example responses

201 Response

{
  "status": "processing",
  "job": "5ff3e22059136b0023324b1f",
  "payload": {
    "url": "https://example.com",
    "operation": "import/webpage"
  },
  "operation": "import/webpage",
  "user": "620deb73617adb001968c8eb",
  "createdAt": "2021-01-05T03:50:56.067Z",
  "updatedAt": "2021-01-05T03:50:56.115Z",
  "expiresAt": "2021-01-05T03:50:56.115Z",
  "endedAt": null,
  "id": "5ff3e22059136b0023324b20"
}

Responses

Status	Meaning	Description	Schema
201	Created	Task succesfully created. Returns details of the created task as per the show tasks	None
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Export Files

Export URL

Code samples

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/export/url \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.freeconvert.com/v1/process/export/url HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "input": [
    "task_id_1",
    "task_id_2"
  ],
  "filename": "some.zip",
  "archive_multiple_files": true
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/export/url',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.freeconvert.com/v1/process/export/url',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.freeconvert.com/v1/process/export/url', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.freeconvert.com/v1/process/export/url', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/export/url");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.freeconvert.com/v1/process/export/url", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }


    /// Make a dummy request
    public async Task MakePostRequest()
    {
      string url = "https://api.freeconvert.com/v1/process/export/url";


      await PostAsync(null, url);

    }

    /// Performs a POST Request
    public async Task PostAsync(undefined content, string url)
    {
        //Serialize Object
        StringContent jsonContent = SerializeObject(content);

        //Execute POST request
        HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
    }



    /// Serialize an object to Json
    private StringContent SerializeObject(undefined content)
    {
        //Serialize Object
        string jsonObject = JsonConvert.SerializeObject(content);

        //Create Json UTF8 String Content
        return new StringContent(jsonObject, Encoding.UTF8, "application/json");
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

POST /process/export/url

Creates a temporary URL to download the file (Please note that files are automatically deleted 4-hours after the task creation). Files can also be manually deleted by deleting the task.

Body parameter

{
  "input": [
    "task_id_1",
    "task_id_2"
  ],
  "filename": "some.zip",
  "archive_multiple_files": true
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	CODE SAMPLES at the right panel
» input	body	[string]	true	The ID of the task to create temporary URLs for. Multiple task IDs can be provided as an array.
» filename	body	string	false	Override the filename of the exported file. Otherwise the filename will be based on the input task.
» archive_multiple_files	body	boolean	false	By default multiple files are exported individually, enabling this option will create a single ZIP file URL for all of the exported files.

Example responses

201 Response

{
  "status": "processing",
  "job": "5ff3e22059136b0023324b1f",
  "payload": {
    "filename": "some.pdf",
    "archive_multiple_files": true
  },
  "operation": "export/url",
  "user": "620deb73617adb001968c8eb",
  "createdAt": "2021-01-05T03:50:56.067Z",
  "updatedAt": "2021-01-05T03:50:56.115Z",
  "expiresAt": "2021-01-05T03:50:56.115Z",
  "endedAt": null,
  "id": "5ff3e22059136b0023324b20"
}

Responses

Status	Meaning	Description	Schema
201	Created	Returns the newly created task object	None
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Export to Google Cloud Storage

Code samples

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/export/googlecloud \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.freeconvert.com/v1/process/export/googlecloud HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "input": "task_id",
  "project_id": "vast-cogency-329405",
  "bucket": "fc-demo",
  "client_email": "fc-demo@1234.iam.gserviceaccount.com",
  "private_key": "private_key"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/export/googlecloud',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.freeconvert.com/v1/process/export/googlecloud',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.freeconvert.com/v1/process/export/googlecloud', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.freeconvert.com/v1/process/export/googlecloud', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/export/googlecloud");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.freeconvert.com/v1/process/export/googlecloud", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }


    /// Make a dummy request
    public async Task MakePostRequest()
    {
      string url = "https://api.freeconvert.com/v1/process/export/googlecloud";


      await PostAsync(null, url);

    }

    /// Performs a POST Request
    public async Task PostAsync(undefined content, string url)
    {
        //Serialize Object
        StringContent jsonContent = SerializeObject(content);

        //Execute POST request
        HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
    }



    /// Serialize an object to Json
    private StringContent SerializeObject(undefined content)
    {
        //Serialize Object
        string jsonObject = JsonConvert.SerializeObject(content);

        //Create Json UTF8 String Content
        return new StringContent(jsonObject, Encoding.UTF8, "application/json");
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

POST /process/export/googlecloud

Creates a new task to export a file form FreeConvert into google cloud storage

Body parameter

{
  "input": "task_id",
  "project_id": "vast-cogency-329405",
  "bucket": "fc-demo",
  "client_email": "fc-demo@1234.iam.gserviceaccount.com",
  "private_key": "private_key"
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	CODE SAMPLES at the right panel
» input	body	string	true	The ID of the task to export. Multiple task IDs can be provided as an array.
» project_id	body	string	true	The Google Cloud Project ID (api-project-...).
» bucket	body	string	true	The Google Cloud Storage Bucket name.
» client_email	body	string	true	The client email of the service account to use (...@api-project-....iam.gserviceaccount.com).
» private_key	body	string	true	The private key of the service account.
» file	body	string	false	Filename of the file to create (the filename in the bucket, including path).
» file_prefix	body	string	false	Alternatively to using file, you can specify a file prefix for exporting files.

Example responses

201 Response

{
  "status": "created",
  "startedAt": null,
  "endedAt": null,
  "expiresAt": "2021-12-19T07:02:15.724Z",
  "payload": {
    "project_id": "demo_project_id",
    "bucket": "demo",
    "client_email": "fc-demo@1234.iam.gserviceaccount.com",
    "private_key": ""
  },
  "job": "61bf0107e39b480011724973",
  "name": "export",
  "operation": "export/googlecloud",
  "user": "113.11.39.191",
  "createdAt": "2021-12-19T09:53:11.266Z",
  "updatedAt": "2021-12-19T09:53:11.266Z",
  "id": "61bf0107e39b480011724976"
}

Responses

Status	Meaning	Description	Schema
201	Created	Task succesfully created. Returns details of the created task as per the show tasks	None
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Export to Azure

Code samples

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/export/azureblob \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.freeconvert.com/v1/process/export/azureblob HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "input": "task_id",
  "container": "container_name",
  "storage_account": "storage_account_name",
  "storage_access_key": "storage_access_key",
  "filename": "fc.jpg",
  "metadata": {
    "ContentType": "image/jpeg"
  },
  "blob_prefix": ""
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/export/azureblob',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.freeconvert.com/v1/process/export/azureblob',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.freeconvert.com/v1/process/export/azureblob', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.freeconvert.com/v1/process/export/azureblob', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/export/azureblob");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.freeconvert.com/v1/process/export/azureblob", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }


    /// Make a dummy request
    public async Task MakePostRequest()
    {
      string url = "https://api.freeconvert.com/v1/process/export/azureblob";


      await PostAsync(null, url);

    }

    /// Performs a POST Request
    public async Task PostAsync(undefined content, string url)
    {
        //Serialize Object
        StringContent jsonContent = SerializeObject(content);

        //Execute POST request
        HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
    }



    /// Serialize an object to Json
    private StringContent SerializeObject(undefined content)
    {
        //Serialize Object
        string jsonObject = JsonConvert.SerializeObject(content);

        //Create Json UTF8 String Content
        return new StringContent(jsonObject, Encoding.UTF8, "application/json");
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

POST /process/export/azureblob

Creates a new task to export a file form FreeConvert into azure blob storage

Body parameter

{
  "input": "task_id",
  "container": "container_name",
  "storage_account": "storage_account_name",
  "storage_access_key": "storage_access_key",
  "filename": "fc.jpg",
  "metadata": {
    "ContentType": "image/jpeg"
  },
  "blob_prefix": ""
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	CODE SAMPLES at the right panel
» input	body	string	true	The ID of the task to export. Multiple task IDs can be provided as an array.
» storage_account	body	string	true	The name of the Azure storage account (This is the string before.blob.core.windows.net).
» container	body	string	true	Azure container name.
» blob	body	string	false	Blob name for storing the file (the filename in the container, including path). If unspecified filename will be based on the input task.
» blob_prefix	body	string	false	Is specified, the prefix will be added to the exporeted filename.
» storage_access_key	body	string	true	The Azure secret key. Only required alternatively, if you are not providing a SAS token.
» sas_token	body	string	false	The Azure SAS token.
» metadata	body	string	false	Object of additional Azure meta data.

Example responses

201 Response

{
  "status": "processing",
  "job": "5ff3e22059136b0023324b1f",
  "payload": {
    "bucket": "your_bucket_name",
    "region": "us-east-2",
    "access_key_id": "your_access_key_id",
    "secret_access_key": "the_secret_access_key_of_your_account",
    "key": "file.jpg"
  },
  "operation": "import/s3",
  "user": "620deb73617adb001968c8eb",
  "createdAt": "2021-01-05T03:50:56.067Z",
  "updatedAt": "2021-01-05T03:50:56.115Z",
  "expiresAt": "2021-01-05T03:50:56.115Z",
  "endedAt": null,
  "id": "5ff3e22059136b0023324b20"
}

Responses

Status	Meaning	Description	Schema
201	Created	Task succesfully created. Returns details of the created task as per the show tasks	None
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Export to S3

Code samples

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/export/s3 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.freeconvert.com/v1/process/export/s3 HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "input": [
    "task_id_1",
    "task_id_2"
  ],
  "bucket": "your_bucket_name",
  "region": "us-east-2",
  "access_key_id": "your_access_key_id",
  "secret_access_key": "the_secret_access_key_of_your_account",
  "key": "file.jpg",
  "acl": "private"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/export/s3',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.freeconvert.com/v1/process/export/s3',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.freeconvert.com/v1/process/export/s3', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.freeconvert.com/v1/process/export/s3', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/export/s3");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.freeconvert.com/v1/process/export/s3", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }


    /// Make a dummy request
    public async Task MakePostRequest()
    {
      string url = "https://api.freeconvert.com/v1/process/export/s3";


      await PostAsync(null, url);

    }

    /// Performs a POST Request
    public async Task PostAsync(undefined content, string url)
    {
        //Serialize Object
        StringContent jsonContent = SerializeObject(content);

        //Execute POST request
        HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
    }



    /// Serialize an object to Json
    private StringContent SerializeObject(undefined content)
    {
        //Serialize Object
        string jsonObject = JsonConvert.SerializeObject(content);

        //Create Json UTF8 String Content
        return new StringContent(jsonObject, Encoding.UTF8, "application/json");
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

POST /process/export/s3

This endpoint will allow users to export their files to AWS S3 using our API (Please note that files are automatically deleted 4-hours after the task creation). Files can also be manually deleted by deleting the task.

Body parameter

{
  "input": [
    "task_id_1",
    "task_id_2"
  ],
  "bucket": "your_bucket_name",
  "region": "us-east-2",
  "access_key_id": "your_access_key_id",
  "secret_access_key": "the_secret_access_key_of_your_account",
  "key": "file.jpg",
  "acl": "private"
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	CODE SAMPLES at the right panel
» input	body	[string]	true	The ID of the task to create temporary URLs for. Multiple task IDs can be provided as an array.
» bucket	body	string	true	The Amazon S3 bucket where to store the file
» region	body	string	true	Specify the Amazon S3 endpoint, e.g. us-west-2 or eu-west-1
» access_key_id	body	string	true	AWS access key id
» secret_access_key	body	string	true	AWS secret access key
» key	body	string	true	S3 key for storing the file (the filename in the bucket, including path)
» acl	body	string	false	S3 ACL for storing the file. Possible values like private, public-read , public-read-write, authenticated-read, bucket-owner-read, bucket-owner-full-control
» endpoint	body	string	false	Use a custom S3 API endpoint. The default endpoint is built from the configured region

Example responses

201 Response

{
  "status": "processing",
  "job": "5ff3e22059136b0023324b1f",
  "payload": {
    "bucket": "your_bucket_name",
    "region": "us-east-2",
    "access_key_id": "your_access_key_id",
    "secret_access_key": "the_secret_access_key_of_your_account",
    "key": "file.jpg",
    "acl": "private"
  },
  "operation": "export/s3",
  "user": "620deb73617adb001968c8eb",
  "createdAt": "2021-01-05T03:50:56.067Z",
  "updatedAt": "2021-01-05T03:50:56.115Z",
  "expiresAt": "2021-01-05T03:50:56.115Z",
  "endedAt": null,
  "id": "5ff3e22059136b0023324b20"
}

Responses

Status	Meaning	Description	Schema
201	Created	Returns the newly created task object	None
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Export to SFTP

Code samples

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/export/sftp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.freeconvert.com/v1/process/export/sftp HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "input": [
    "task_id_1",
    "task_id_2"
  ],
  "host": "your_sftp_domain_name_or_ip",
  "port": 33,
  "username": "your_sftp_username",
  "password": "your_sftp_password",
  "file_string": "dir/file.jpg"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/export/sftp',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.freeconvert.com/v1/process/export/sftp',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.freeconvert.com/v1/process/export/sftp', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.freeconvert.com/v1/process/export/sftp', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/export/sftp");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.freeconvert.com/v1/process/export/sftp", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }


    /// Make a dummy request
    public async Task MakePostRequest()
    {
      string url = "https://api.freeconvert.com/v1/process/export/sftp";


      await PostAsync(null, url);

    }

    /// Performs a POST Request
    public async Task PostAsync(undefined content, string url)
    {
        //Serialize Object
        StringContent jsonContent = SerializeObject(content);

        //Execute POST request
        HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
    }



    /// Serialize an object to Json
    private StringContent SerializeObject(undefined content)
    {
        //Serialize Object
        string jsonObject = JsonConvert.SerializeObject(content);

        //Create Json UTF8 String Content
        return new StringContent(jsonObject, Encoding.UTF8, "application/json");
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

POST /process/export/sftp

This endpoint will allow our users to export processed files into an sftp account using our API

Body parameter

{
  "input": [
    "task_id_1",
    "task_id_2"
  ],
  "host": "your_sftp_domain_name_or_ip",
  "port": 33,
  "username": "your_sftp_username",
  "password": "your_sftp_password",
  "file_string": "dir/file.jpg"
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	CODE SAMPLES at the right panel
» input	body	[string]	true	The ID of the task to create temporary URLs for. Multiple task IDs can be provided as an array.
» host	body	number	true	The SFTP server hostname or ip
» port	body	string	false	The SFTP port. Defaults to 22
» username	body	string	true	The SFTP username
» password	body	string	false	The SFTP password
» private_key	body	string	false	Alternatively to using password, you can provide a private key
» file_string	body	string	true	File name of the file to create (the filename on the server, including path)

Example responses

201 Response

{
  "status": "processing",
  "job": "5ff3e22059136b0023324b1f",
  "payload": {
    "host": "your_sftp_domain_name_or_ip",
    "port": 33,
    "username": "your_sftp_username",
    "password": "your_sftp_password",
    "file_string": "dir/file.jpg"
  },
  "operation": "import/sftp",
  "user": "620deb73617adb001968c8eb",
  "createdAt": "2021-01-05T03:50:56.067Z",
  "updatedAt": "2021-01-05T03:50:56.115Z",
  "expiresAt": "2021-01-05T03:50:56.115Z",
  "endedAt": null,
  "id": "5ff3e22059136b0023324b20"
}

Responses

Status	Meaning	Description	Schema
201	Created	Task succesfully created. Returns details of the created task as per the show tasks	None
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Convert

Convert Task

Code samples

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/convert \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.freeconvert.com/v1/process/convert HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "input": "import_task_id",
  "input_format": "jpg",
  "output_format": "png",
  "options": {
    "image_custom_width": 450,
    "image_custom_height": 300
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/convert',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.freeconvert.com/v1/process/convert',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.freeconvert.com/v1/process/convert', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.freeconvert.com/v1/process/convert', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/convert");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.freeconvert.com/v1/process/convert", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }


    /// Make a dummy request
    public async Task MakePostRequest()
    {
      string url = "https://api.freeconvert.com/v1/process/convert";


      await PostAsync(null, url);

    }

    /// Performs a POST Request
    public async Task PostAsync(undefined content, string url)
    {
        //Serialize Object
        StringContent jsonContent = SerializeObject(content);

        //Execute POST request
        HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
    }



    /// Serialize an object to Json
    private StringContent SerializeObject(undefined content)
    {
        //Serialize Object
        string jsonObject = JsonConvert.SerializeObject(content);

        //Create Json UTF8 String Content
        return new StringContent(jsonObject, Encoding.UTF8, "application/json");
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

POST /process/convert

Creates a task to convert one input file from an input_format to outut_format

Body parameter

{
  "input": "import_task_id",
  "input_format": "jpg",
  "output_format": "png",
  "options": {
    "image_custom_width": 450,
    "image_custom_height": 300
  }
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	CODE SAMPLES at the right panel
» input	body	string	true	The ID of the task that needs to perform in this compress task, in general, will be the task id of import / upload task or any other task.
» input_format	body	string	false	Extension of the input file
» output_format	body	string	true	Extension of the output file
» options	body	object	false	Options depend on the type of conversion. See 'Advanced Options' section.

Example responses

201 Response

{
  "status": "processing",
  "job": "5ff3e22059136b0023324b1f",
  "payload": {
    "input_format": "jpg",
    "output_format": "png",
    "options": {
      "image_custom_width": 450,
      "image_custom_height": 300
    },
    "operation": "convert"
  },
  "operation": "convert",
  "user": "620deb73617adb001968c8eb",
  "createdAt": "2021-01-05T03:50:56.067Z",
  "updatedAt": "2021-01-05T03:50:56.115Z",
  "expiresAt": "2021-01-05T03:50:56.115Z",
  "endedAt": null,
  "id": "5ff3e22059136b0023324b20"
}

Responses

Status	Meaning	Description	Schema
201	Created	Returns the newly created task object	None
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Compress

Compress Task

Code samples

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/compress \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.freeconvert.com/v1/process/compress HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "input": "import_task_id",
  "input_format": "mkv",
  "output_format": "mkv",
  "options": {
    "video_codec_compress": "libx265",
    "compress_video": "by_video_quality",
    "video_compress_crf_x265": "28",
    "video_compress_speed": "veryfast"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/compress',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.freeconvert.com/v1/process/compress',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.freeconvert.com/v1/process/compress', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.freeconvert.com/v1/process/compress', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/compress");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.freeconvert.com/v1/process/compress", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }


    /// Make a dummy request
    public async Task MakePostRequest()
    {
      string url = "https://api.freeconvert.com/v1/process/compress";


      await PostAsync(null, url);

    }

    /// Performs a POST Request
    public async Task PostAsync(undefined content, string url)
    {
        //Serialize Object
        StringContent jsonContent = SerializeObject(content);

        //Execute POST request
        HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
    }



    /// Serialize an object to Json
    private StringContent SerializeObject(undefined content)
    {
        //Serialize Object
        string jsonObject = JsonConvert.SerializeObject(content);

        //Create Json UTF8 String Content
        return new StringContent(jsonObject, Encoding.UTF8, "application/json");
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

POST /process/compress

Creates a task to compress one input file

Body parameter

{
  "input": "import_task_id",
  "input_format": "mkv",
  "output_format": "mkv",
  "options": {
    "video_codec_compress": "libx265",
    "compress_video": "by_video_quality",
    "video_compress_crf_x265": "28",
    "video_compress_speed": "veryfast"
  }
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	CODE SAMPLES at the right panel
» input	body	string	true	The ID of the task that contains the file to be compressed. In general, will be the task id of import/upload task or any other task.
» input_format	body	string	false	Extension of the input file.
» output_format	body	string	true	Extension of the output file.
» options	body	object	false	Options depend on the type of compress. See 'Advanced Options' section.

Example responses

201 Response

{
  "status": "processing",
  "job": "5ff3e22059136b0023324b1f",
  "payload": {
    "input_format": "pdf",
    "filename": "sample.pdf",
    "options": {
      "pdf_compression_level": "strong",
      "pdf_convert_to_gray": true
    },
    "operation": "compress"
  },
  "operation": "compress",
  "user": "620deb73617adb001968c8eb",
  "createdAt": "2021-01-05T03:50:56.067Z",
  "updatedAt": "2021-01-05T03:50:56.115Z",
  "expiresAt": "2021-01-05T03:50:56.115Z",
  "endedAt": null,
  "id": "5ff3e22059136b0023324b20"
}

Responses

Status	Meaning	Description	Schema
201	Created	Returns the newly created task object	None
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Merge

Merge Task

Code samples

# You can also use wget
curl -X POST https://api.freeconvert.com/v1/process/merge \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST https://api.freeconvert.com/v1/process/merge HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "input": [
    "import_task_id_1",
    "import_task_id_2"
  ],
  "output_format": "pdf",
  "filename": "some.pdf",
  "options": {
    "pdf_page_size": "1240.2x1753.95",
    "pdf_orientation": "portrait",
    "pdf_margin": "1",
    "pdf_image_alignment": "Center"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://api.freeconvert.com/v1/process/merge',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://api.freeconvert.com/v1/process/merge',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://api.freeconvert.com/v1/process/merge', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.freeconvert.com/v1/process/merge', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/process/merge");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.freeconvert.com/v1/process/merge", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }


    /// Make a dummy request
    public async Task MakePostRequest()
    {
      string url = "https://api.freeconvert.com/v1/process/merge";


      await PostAsync(null, url);

    }

    /// Performs a POST Request
    public async Task PostAsync(undefined content, string url)
    {
        //Serialize Object
        StringContent jsonContent = SerializeObject(content);

        //Execute POST request
        HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
    }



    /// Serialize an object to Json
    private StringContent SerializeObject(undefined content)
    {
        //Serialize Object
        string jsonObject = JsonConvert.SerializeObject(content);

        //Create Json UTF8 String Content
        return new StringContent(jsonObject, Encoding.UTF8, "application/json");
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

POST /process/merge

Use this endpoint to merge two or more files. For example, you can convert multiple JPG or PNG files to a single PDF or GIF file.

Body parameter

{
  "input": [
    "import_task_id_1",
    "import_task_id_2"
  ],
  "output_format": "pdf",
  "filename": "some.pdf",
  "options": {
    "pdf_page_size": "1240.2x1753.95",
    "pdf_orientation": "portrait",
    "pdf_margin": "1",
    "pdf_image_alignment": "Center"
  }
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	CODE SAMPLES at the right panel
» input	body	[string]	true	The ID of the task that needs to perform in this merge task, in general, will be the task id of import / upload task or any other task.
» output_format	body	string	true	Extension of the output file
» filename	body	string	false	Name of the output file
» options	body	object	false	Options depend on the type of merge. See 'Advanced Options' section.

Example responses

201 Response

{
  "status": "processing",
  "job": "5ff3e22059136b0023324b1f",
  "payload": {
    "output_format": "pdf",
    "filename": "some.pdf",
    "operation": "merge"
  },
  "operation": "merge",
  "user": "620deb73617adb001968c8eb",
  "createdAt": "2021-01-05T03:50:56.067Z",
  "updatedAt": "2021-01-05T03:50:56.115Z",
  "expiresAt": "2021-01-05T03:50:56.115Z",
  "endedAt": null,
  "id": "5ff3e22059136b0023324b20"
}

Responses

Status	Meaning	Description	Schema
201	Created	Returns the newly created task object	None
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Advanced Options

Convert Options

Code samples

# You can also use wget
curl -X GET https://api.freeconvert.com/v1/query/options/convert?input_format=string&output_format=string \
  -H 'Accept: application/json'

GET https://api.freeconvert.com/v1/query/options/convert?input_format=string&output_format=string HTTP/1.1
Host: api.freeconvert.com
Accept: application/json


const headers = {
  'Accept':'application/json'
};

fetch('https://api.freeconvert.com/v1/query/options/convert?input_format=string&output_format=string',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://api.freeconvert.com/v1/query/options/convert',
  params: {
  'input_format' => 'string',
'output_format' => 'string'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.freeconvert.com/v1/query/options/convert', params={
  'input_format': 'string',  'output_format': 'string'
}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.freeconvert.com/v1/query/options/convert', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/query/options/convert?input_format=string&output_format=string");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.freeconvert.com/v1/query/options/convert", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }

    /// Make a dummy request
    public async Task MakeGetRequest()
    {
      string url = "https://api.freeconvert.com/v1/query/options/convert";
      var result = await GetAsync(url);
    }

    /// Performs a GET Request
    public async Task GetAsync(string url)
    {
        //Start the request
        HttpResponseMessage response = await Client.GetAsync(url);

        //Validate result
        response.EnsureSuccessStatusCode();

    }




    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

GET /query/options/convert

Use this endpoint to generate convert advanced options. Our getting started section can help grab a general idea of how to use the advanced options.

Parameters

Name	In	Type	Required	Description
input_format	query	string	true	input file extension
output_format	query	string	true	output file extension

Example responses

200 Response

{
  "sourceExt": "png",
  "targetExt": "gif",
  "operation": "convert",
  "options": [
    {
      "name": "resize_type_image",
      "label": "Resize Type",
      "hint": "Choose a method if you want to resize the output image. This parameter has no effect but it's options may help you identify sub-options.",
      "data_type": "string",
      "type": "enum",
      "enum_values": [
        {
          "value": "keep_original",
          "label": "Keep original size"
        },
        {
          "value": "by_width_keep_ar",
          "label": "Enter Width (px)"
        },
        {
          "value": "by_height_keep_ar",
          "label": "Enter Height (px)"
        },
        {
          "value": "dimension",
          "label": "Enter Width X Height (px)"
        },
        {
          "value": "percent",
          "label": "As a percentage"
        }
      ]
    },
    {
      "name": "image_custom_width",
      "label": "Enter Width (px)",
      "hint": "Enter target width in pixels. If no height is specified, we will keep the image's aspect ratio intact to avoid stretching",
      "data_type": "number",
      "depends_on": {
        "name": "resize_type_image",
        "meta": [
          {
            "value": "dimension",
            "label": "Enter Width X Height (px)"
          },
          {
            "value": "by_width_keep_ar",
            "label": "Enter Width (px)"
          }
        ]
      }
    },
    {
      "name": "image_resize_percentage",
      "label": "Enter Percentage (%)",
      "hint": "For example, 25 will make both width and height 25% of the original (1/4 of the original). Use this option when you want to resize output image \"As a percentage\" of original.",
      "data_type": "number",
      "default_value": "100",
      "depends_on": {
        "name": "resize_type_image",
        "meta": [
          {
            "value": "percent",
            "label": "As a percentage"
          }
        ]
      }
    },
    {
      "name": "image_custom_height",
      "label": "Enter Height (px)",
      "hint": "Enter target height in pixels. If no width is specified, we will keep the image's aspect ratio intact to avoid stretching",
      "data_type": "number",
      "depends_on": {
        "name": "resize_type_image",
        "meta": [
          {
            "value": "by_height_keep_ar",
            "label": "Enter Height (px)"
          },
          {
            "value": "dimension",
            "label": "Enter Width X Height (px)"
          }
        ]
      }
    },
    {
      "name": "strip",
      "label": "Strip",
      "hint": "Strip the image of any profiles, EXIF, and comments to reduce size",
      "data_type": "boolean",
      "default_value": "true"
    },
    {
      "name": "auto-orient",
      "label": "Auto Orient",
      "hint": "Correctly orient the image using the gravity sensor data stored in EXIF",
      "data_type": "boolean",
      "default_value": "true"
    },
    {
      "name": "trim_image",
      "label": "Trim Image",
      "hint": "Trim tall images from top & bottom to fit GIF width",
      "data_type": "boolean",
      "default_value": "true"
    },
    {
      "name": "gif_trim_image_in_pixel",
      "label": "GIF width",
      "hint": "Enter GIF width in pixels",
      "data_type": "number",
      "default_value": "480"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully get list of possible options	None
400	Bad Request	Bad Request	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Compress Options

Code samples

# You can also use wget
curl -X GET https://api.freeconvert.com/v1/query/options/compress?input_format=string&output_format=string \
  -H 'Accept: application/json'

GET https://api.freeconvert.com/v1/query/options/compress?input_format=string&output_format=string HTTP/1.1
Host: api.freeconvert.com
Accept: application/json


const headers = {
  'Accept':'application/json'
};

fetch('https://api.freeconvert.com/v1/query/options/compress?input_format=string&output_format=string',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://api.freeconvert.com/v1/query/options/compress',
  params: {
  'input_format' => 'string',
'output_format' => 'string'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.freeconvert.com/v1/query/options/compress', params={
  'input_format': 'string',  'output_format': 'string'
}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.freeconvert.com/v1/query/options/compress', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/query/options/compress?input_format=string&output_format=string");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.freeconvert.com/v1/query/options/compress", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }

    /// Make a dummy request
    public async Task MakeGetRequest()
    {
      string url = "https://api.freeconvert.com/v1/query/options/compress";
      var result = await GetAsync(url);
    }

    /// Performs a GET Request
    public async Task GetAsync(string url)
    {
        //Start the request
        HttpResponseMessage response = await Client.GetAsync(url);

        //Validate result
        response.EnsureSuccessStatusCode();

    }




    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

GET /query/options/compress

Use this endpoint to generate compress advanced options. Our getting started section can help grab a general idea of how to use the advanced options.

Parameters

Name	In	Type	Required	Description
input_format	query	string	true	input file extension
output_format	query	string	true	output file extension

Example responses

200 Response

{
  "sourceExt": "gif",
  "targetExt": "gif",
  "operation": "compress",
  "options": [
    {
      "name": "gif_undo_optimization",
      "label": "Undo Optimizations",
      "hint": "May increase file size. Better for fixing buggy GIFs",
      "data_type": "boolean",
      "default_value": "false"
    },
    {
      "name": "gif_compress_reduce_frames",
      "label": "Drop Frames to reduce the file size?",
      "hint": "For certain types of GIFs, you maybe able to reduce file size further by dropping frames. Not available when \"Undo optimization\" is set to \"true\"",
      "data_type": "string",
      "type": "enum",
      "enum_values": [
        {
          "value": "no-change",
          "label": "None"
        },
        {
          "value": "duplicate",
          "label": " Remove Duplicate Frames"
        },
        {
          "value": "n2",
          "label": " Drop every 2nd frame"
        },
        {
          "value": "n3",
          "label": " Drop every 3rd frame"
        },
        {
          "value": "n4",
          "label": " Drop every 4th frame"
        },
        {
          "value": "n5",
          "label": " Drop every 5th frame"
        }
      ],
      "depends_on": {
        "name": "gif_undo_optimization",
        "meta": [
          {
            "value": false,
            "label": ""
          }
        ]
      }
    },
    {
      "name": "gif_compress_match_frames_fuzz_factor",
      "label": "Match Frames With Similar Colors?",
      "hint": "This option lets you match identical frames with ‘similar’ colors. Higher values match more similar colors as identical. Available when \"Remove Duplicate Frames\" option is used along with gif_undo_optimization set to false.",
      "data_type": "number",
      "default_value": "5",
      "units": "%",
      "depends_on": {
        "name": "gif_compress_reduce_frames",
        "meta": [
          {
            "value": "duplicate",
            "label": " Remove Duplicate Frames"
          }
        ]
      }
    },
    {
      "name": "gif_color",
      "label": "Reduce colors?",
      "hint": "This parameter is not used in operations but it's options may help you identify sub-options.",
      "data_type": "number",
      "default_value": "75",
      "type": "enum",
      "enum_values": [
        {
          "value": "no-change",
          "label": "None"
        },
        {
          "value": "reduce",
          "label": " Reduce the number of colors"
        },
        {
          "value": "reduce_dither",
          "label": " Reduce the number of colors and dither"
        },
        {
          "value": "single",
          "label": " Use a single color table"
        }
      ],
      "depends_on": {
        "name": "gif_undo_optimization",
        "meta": [
          {
            "value": false,
            "label": ""
          }
        ]
      }
    },
    {
      "name": "gif_compress_number_of_colors",
      "label": "Number of colors?",
      "hint": "GIF files support up to 256 different colors. Reducing the number of colors in colormap can reduce GIF file size. You can choose to reduce colors up to just 2 colors.",
      "data_type": "number",
      "default_value": "256",
      "depends_on": {
        "name": "gif_color",
        "meta": [
          {
            "value": "reduce",
            "label": " Reduce the number of colors"
          },
          {
            "value": "reduce_dither",
            "label": " Reduce the number of colors and dither"
          }
        ]
      }
    },
    {
      "name": "gif_compression_level",
      "label": "Compression level",
      "hint": "Applies lossy LZW compression. Default (75) is a good balance between compression & quality. Higher values compress more. Not available with the \"Undo optimizations\" method.",
      "data_type": "number",
      "default_value": "75",
      "depends_on": {
        "name": "gif_undo_optimization",
        "meta": [
          {
            "value": false,
            "label": ""
          }
        ]
      }
    },
    {
      "name": "gif_optimize_transparency",
      "label": "Optimize Transparency",
      "hint": "Replace repeating/duplicate color pixels with transparency for better compression. Available when gif_undo_optimization set to false.",
      "data_type": "boolean",
      "default_value": "false",
      "depends_on": {
        "name": "gif_undo_optimization",
        "meta": [
          {
            "value": false,
            "label": ""
          }
        ]
      }
    },
    {
      "name": "gif_optimize_transparency_fuzz_factor",
      "label": "Fuzz Factor",
      "hint": "Match similar colors as equal. Available when \"gif_optimize_transparency\" is set to \"true\" and \"gif_undo_optimization\" set to \"false\".",
      "data_type": "number",
      "default_value": "5",
      "units": "%",
      "depends_on": {
        "name": "gif_optimize_transparency",
        "meta": [
          {
            "value": true,
            "label": ""
          }
        ]
      }
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully get list of possible options	None
400	Bad Request	Bad Request	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Merge Options

Code samples

# You can also use wget
curl -X GET https://api.freeconvert.com/v1/query/options/merge?output_format=gif \
  -H 'Accept: application/json'

GET https://api.freeconvert.com/v1/query/options/merge?output_format=gif HTTP/1.1
Host: api.freeconvert.com
Accept: application/json


const headers = {
  'Accept':'application/json'
};

fetch('https://api.freeconvert.com/v1/query/options/merge?output_format=gif',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://api.freeconvert.com/v1/query/options/merge',
  params: {
  'output_format' => 'string'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.freeconvert.com/v1/query/options/merge', params={
  'output_format': 'gif'
}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.freeconvert.com/v1/query/options/merge', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/query/options/merge?output_format=gif");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.freeconvert.com/v1/query/options/merge", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }

    /// Make a dummy request
    public async Task MakeGetRequest()
    {
      string url = "https://api.freeconvert.com/v1/query/options/merge";
      var result = await GetAsync(url);
    }

    /// Performs a GET Request
    public async Task GetAsync(string url)
    {
        //Start the request
        HttpResponseMessage response = await Client.GetAsync(url);

        //Validate result
        response.EnsureSuccessStatusCode();

    }




    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

GET /query/options/merge

Use this endpoint to generate merge advanced options. Our getting started section can help grab a general idea of how to use the advanced options."

Parameters

Name	In	Type	Required	Description
output_format	query	string	true	Output file extension matching the specified file types [`gif`, `pdf`]

Example responses

200 Response

{
  "sourceExt": "png",
  "targetExt": "gif",
  "operation": "merge",
  "options": [
    {
      "name": "gif_loop_count",
      "label": "Loop Count",
      "hint": "Leave empty (0) to loop infinitely. Only applies when creating a GIF from multiple images.",
      "data_type": "number"
    },
    {
      "name": "gif_frame_speed",
      "label": "Frame Speed",
      "hint": "Delay between frames (in 1/100 of a second). Only applies when creating a GIF from multiple images.",
      "data_type": "number",
      "default_value": "100"
    },
    {
      "name": "trim_image",
      "label": "Trim images ?",
      "hint": "Trim tall images from top & bottom to fit GIF width",
      "data_type": "boolean",
      "default_value": "true"
    },
    {
      "name": "gif_fill_color_smaller_image",
      "label": "Fill color for smaller images",
      "hint": "Fill color for smaller images",
      "data_type": "string",
      "default_value": "#000000",
      "depends_on": {
        "name": "trim_image",
        "meta": [
          {
            "value": false,
            "label": ""
          }
        ]
      }
    },
    {
      "name": "gif_trim_image_in_pixel",
      "label": "GIF width",
      "hint": "Enter GIF width in pixels",
      "data_type": "number",
      "default_value": "480"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully get list of possible options	None
400	Bad Request	Bad Request	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Crop Options

Code samples

# You can also use wget
curl -X GET https://api.freeconvert.com/v1/query/options/crop?input_format=mp4&output_format=mov \
  -H 'Accept: application/json'

GET https://api.freeconvert.com/v1/query/options/crop?input_format=mp4&output_format=mov HTTP/1.1
Host: api.freeconvert.com
Accept: application/json


const headers = {
  'Accept':'application/json'
};

fetch('https://api.freeconvert.com/v1/query/options/crop?input_format=mp4&output_format=mov',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://api.freeconvert.com/v1/query/options/crop',
  params: {
  'input_format' => 'string',
'output_format' => 'string'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.freeconvert.com/v1/query/options/crop', params={
  'input_format': 'mp4',  'output_format': 'mov'
}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.freeconvert.com/v1/query/options/crop', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/query/options/crop?input_format=mp4&output_format=mov");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.freeconvert.com/v1/query/options/crop", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }

    /// Make a dummy request
    public async Task MakeGetRequest()
    {
      string url = "https://api.freeconvert.com/v1/query/options/crop";
      var result = await GetAsync(url);
    }

    /// Performs a GET Request
    public async Task GetAsync(string url)
    {
        //Start the request
        HttpResponseMessage response = await Client.GetAsync(url);

        //Validate result
        response.EnsureSuccessStatusCode();

    }




    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

GET /query/options/crop

Use this endpoint to generate crop advanced options. Our getting started section can help grab a general idea of how to use the advanced options.

Parameters

Name	In	Type	Required	Description
input_format	query	string	true	input file extension
output_format	query	string	true	output file extension

Example responses

200 Response

{
  "sourceExt": "mp4",
  "targetExt": "mov",
  "operation": "crop",
  "options": [
    {
      "name": "crop-position-x",
      "label": "Position-X",
      "data_type": "float"
    },
    {
      "name": "crop-position-y",
      "label": "Position-Y",
      "data_type": "float",
      "default_value": "0"
    },
    {
      "name": "video_crop",
      "label": "Crop Video",
      "hint": "Specify the video crop settings. Format is width:height:offset_x:offset_y. Where, width and height is that of the crop rectangle. Offset_x and y specify the crop rectangle position on original video.",
      "data_type": "string",
      "default_value": "0:0:0:0"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully get list of possible options	None
400	Bad Request	Bad Request	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Trim Options

Code samples

# You can also use wget
curl -X GET https://api.freeconvert.com/v1/query/options/trim?input_format=mp4&output_format=mov \
  -H 'Accept: application/json'

GET https://api.freeconvert.com/v1/query/options/trim?input_format=mp4&output_format=mov HTTP/1.1
Host: api.freeconvert.com
Accept: application/json


const headers = {
  'Accept':'application/json'
};

fetch('https://api.freeconvert.com/v1/query/options/trim?input_format=mp4&output_format=mov',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.get 'https://api.freeconvert.com/v1/query/options/trim',
  params: {
  'input_format' => 'string',
'output_format' => 'string'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://api.freeconvert.com/v1/query/options/trim', params={
  'input_format': 'mp4',  'output_format': 'mov'
}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.freeconvert.com/v1/query/options/trim', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.freeconvert.com/v1/query/options/trim?input_format=mp4&output_format=mov");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.freeconvert.com/v1/query/options/trim", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }

    /// Make a dummy request
    public async Task MakeGetRequest()
    {
      string url = "https://api.freeconvert.com/v1/query/options/trim";
      var result = await GetAsync(url);
    }

    /// Performs a GET Request
    public async Task GetAsync(string url)
    {
        //Start the request
        HttpResponseMessage response = await Client.GetAsync(url);

        //Validate result
        response.EnsureSuccessStatusCode();

    }




    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

GET /query/options/trim

Use this endpoint to generate trim advanced options. Our getting started section can help grab a general idea of how to use the advanced options.

Parameters

Name	In	Type	Required	Description
input_format	query	string	true	input file extension
output_format	query	string	true	output file extension

Example responses

200 Response

{
  "sourceExt": "mp4",
  "targetExt": "mov",
  "operation": "trim",
  "options": [
    {
      "name": "cut_start_trim",
      "label": "Trim start",
      "hint": "Specify trim start position in the video. Format is hh:mm:ss",
      "data_type": "float",
      "default_value": "0"
    },
    {
      "name": "cut_end_trim",
      "label": "Trim end",
      "hint": "Specify trim end position in the video. Format is hh:mm:ss",
      "data_type": "float",
      "default_value": "5"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Successfully get list of possible options	None
400	Bad Request	Bad Request	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Webhooks

Webhook lets you receive status updates for your jobs and tasks. You can create webhooks using the User Dashboard

Events

event	description
`job.created`	Emitted upon creating a new job
`job.success`	Emitted when a job completes successfully.
`job.failed`	Emits when a job has failed.

In all 3 cases, the payload includes the Job. See an example on the right side.

Failing Webhooks

If your webhook endpoint returns a 4XX or 5XX HTTP status code, we will re-try sending the webhook event up to 3 times (in 30-minute intervals. If you have enabled the "Webhook unreachable" notification from your user dashboard, we will also send you an email when a webhook fails.

If the webhook endpoint returns 410 status code, we will automatically disable this webhook. You can always re-enable it manually from the User Dashboard.

Signing Webhooks

For verifying that the webhook is actually coming from FreeConvert.com, you should validate it. When we send a webhook, we cryptographically sign it using a unique signing secret use this key to make sure the webhook is coming from us. You can get this secret by clicking the edit icon next to your webhook.

The FreeConvert-Signature header contains a hash-based message authentication code (HMAC) with SHA-256. Here is a PHP example on how to calculate this signature for validation:

$signature = hash_hmac('sha256', $payload, $signingSecret);

$signingSecret can be found in the user dashboard's webhook settings (Click show on the SECRET column of the webhook). $payload is the full request body (the JSON string) that we sent to your webhook endpoint.

List Webhooks

Code samples

# You can also use wget
curl -X GET https://notification.freeconvert.com/webhooks \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET https://notification.freeconvert.com/webhooks HTTP/1.1
Host: api.freeconvert.com
Accept: application/json


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://notification.freeconvert.com/webhooks',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get 'https://notification.freeconvert.com/webhooks',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('https://notification.freeconvert.com/webhooks', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://notification.freeconvert.com/webhooks', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://notification.freeconvert.com/webhooks");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://notification.freeconvert.com/webhooks", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }

    /// Make a dummy request
    public async Task MakeGetRequest()
    {
      string url = "https://notification.freeconvert.com/webhooks";
      var result = await GetAsync(url);
    }

    /// Performs a GET Request
    public async Task GetAsync(string url)
    {
        //Start the request
        HttpResponseMessage response = await Client.GetAsync(url);

        //Validate result
        response.EnsureSuccessStatusCode();

    }




    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

GET https://notification.freeconvert.com/webhooks

Lists all webhooks for the user

Parameters

Name	In	Type	Required	Description
url	query	string	false	List webhooks matching the specified url.
per_page	query	integer	false	Number of webhooks per page, defaults to 50. Limited at 200.
page	query	integer	false	If the list of webhooks include multiple pages, this specify which page to show.

Example responses

200 Response

{
  "docs": [
    {
      "id": "5ff3e22059136b0023424b20",
      "name": "example-webhook",
      "status": "active",
      "events": [
        "job.created",
        "job.success"
      ],
      "url": "http://your-domain.com/webhook-url",
      "signingSecret": "XXXXXXXXXXXX",
      "createdAt": "2020-07-17T07:14:56.004Z",
      "updatedAt": "2020-08-29T07:15:23.005Z",
      "lastErrorAt": "2020-07-21T02:16:03.000Z",
      "lastResponseCode": "NETWORK_ERROR"
    }
  ],
  "totalDocs": 150,
  "limit": 10,
  "totalPages": 15,
  "page": 1,
  "pagingCounter": 16,
  "hasPrevPage": false,
  "hasNextPage": true,
  "prevPage": null,
  "nextPage": 2
}

Responses

Status	Meaning	Description	Schema
200	OK	Successful jobs lookup, returns a list of jobs in the response body. You can get more details on the response format by referring to Show a Job endpoint	Inline
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Create a Webhook

Code samples

# You can also use wget
curl -X POST https://notification.freeconvert.com/webhooks \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST https://notification.freeconvert.com/webhooks HTTP/1.1
Host: api.freeconvert.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "url": "string",
  "events": [
    "job.created"
  ],
  "apiKeys": [],
  "description": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('https://notification.freeconvert.com/webhooks',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post 'https://notification.freeconvert.com/webhooks',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('https://notification.freeconvert.com/webhooks', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://notification.freeconvert.com/webhooks', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://notification.freeconvert.com/webhooks");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://notification.freeconvert.com/webhooks", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }


    /// Make a dummy request
    public async Task MakePostRequest()
    {
      string url = "https://notification.freeconvert.com/webhooks";


      await PostAsync(null, url);

    }

    /// Performs a POST Request
    public async Task PostAsync(undefined content, string url)
    {
        //Serialize Object
        StringContent jsonContent = SerializeObject(content);

        //Execute POST request
        HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
    }



    /// Serialize an object to Json
    private StringContent SerializeObject(undefined content)
    {
        //Serialize Object
        string jsonObject = JsonConvert.SerializeObject(content);

        //Create Json UTF8 String Content
        return new StringContent(jsonObject, Encoding.UTF8, "application/json");
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

POST https://notification.freeconvert.com/webhooks

Create a webhook to receive task/job updates in your application.

Body parameter

{
  "url": "string",
  "events": [
    "job.created"
  ],
  "apiKeys": [],
  "description": "string"
}

Parameters

Name	In	Type	Required	Description
body	body	object	false	CODE SAMPLES at the right panel
» url	body	string	false	URL to send notifications to. This URL must be accessible via internet.
» events	body	[string]	false	Select notification events to be sent via the webhook. Possible values are [`job.created`, `job.success`, `job.failed`]
» apiKeys	body	array	false	The webhook will be invoked only for events of jobs create with these API keys.
» description	body	string	false	Has no effect. You can include a description for your reference.

Example responses

201 Response

{
  "id": "5ff3e22059136b0023424b20",
  "name": "example-webhook",
  "status": "active",
  "events": [
    "job.created",
    "job.success"
  ],
  "url": "http://your-domain.com/webhook-url",
  "signingSecret": "XXXXXXXXXXXX",
  "createdAt": "2020-07-17T07:14:56.004Z",
  "updatedAt": "2020-08-29T07:15:23.005Z",
  "lastErrorAt": "2020-07-21T02:16:03.000Z",
  "lastResponseCode": "NETWORK_ERROR"
}

Responses

Status	Meaning	Description	Schema
201	Created	Returns the created webhook. Please see example on the right.	Webhook
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Delete a Webhook

Code samples

# You can also use wget
curl -X DELETE https://notification.freeconvert.com/webhooks/{webhookId} \
  -H 'Authorization: Bearer {access-token}'

DELETE https://notification.freeconvert.com/webhooks/{webhookId} HTTP/1.1
Host: api.freeconvert.com


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('https://notification.freeconvert.com/webhooks/{webhookId}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.delete 'https://notification.freeconvert.com/webhooks/{webhookId}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Authorization': 'Bearer {access-token}'
}

r = requests.delete('https://notification.freeconvert.com/webhooks/{webhookId}', headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Authorization' => 'Bearer {access-token}',
);

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('DELETE','https://notification.freeconvert.com/webhooks/{webhookId}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://notification.freeconvert.com/webhooks/{webhookId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Authorization": []string{"Bearer {access-token}"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://notification.freeconvert.com/webhooks/{webhookId}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
    private HttpClient Client { get; set; }

    /// <<summary>>
    /// Setup http client
    /// <</summary>>
    public HttpExample()
    {
      Client = new HttpClient();
    }




    /// Make a dummy request
    public async Task MakeDeleteRequest()
    {
      int id = 1;
      string url = "https://notification.freeconvert.com/webhooks/{webhookId}";

      await DeleteAsync(id, url);
    }

    /// Performs a DELETE Request
    public async Task DeleteAsync(int id, string url)
    {
        //Execute DELETE request
        HttpResponseMessage response = await Client.DeleteAsync(url + $"/{id}");

        //Return response
        await DeserializeObject(response);
    }

    /// Deserialize object from request response
    private async Task DeserializeObject(HttpResponseMessage response)
    {
        //Read body 
        string responseBody = await response.Content.ReadAsStringAsync();

        //Deserialize Body to object
        var result = JsonConvert.DeserializeObject(responseBody);
    }
}

DELETE https://notification.freeconvert.com/webhooks/{webhookId}

Delete a specific webhook.

Parameters

Name	In	Type	Required	Description
webhookId	path	string(ObjectID)	true	ID of the webhook to delete.

Responses

Status	Meaning	Description	Schema
204	No Content	Webhook succesfully deleted (empty response body).	None
400	Bad Request	Invalid request body	None
401	Unauthorized	Access token is missing or invalid	None
403	Forbidden	Access Denied	None
406	Not Acceptable	Request not acceptable	None
429	Too Many Requests	Too many requests	None

Socket

Code samples

const socket = io("https://notification.freeconvert.com/", {
    transports: ["websocket"],
    path: "/socket.io",
    auth: { token: `Bearer ${YOUR_TOKEN_HERE}` },
});
//for subscribe job and task
socket.emit("subscribe", `job.{jobId}`);
socket.emit("subscribe", `task.{taskId}`);

//for unsubscribe job and task
socket.emit("unsubscribe", `job.{jobId}`);
socket.emit("unsubscribe", `task.{taskId}`);

socket.on("task_started", (data) => {
    console.log("task_started", data);
});

socket.on("job_started", (data) => {
    console.log("job_started", data);
});

If you would like to receive real-time updates of your tasks and jobs, you can use FreeConvert.com Socket API. The hostname for Socket.io updates is notification.freeconvert.com. Socket.io clients are available in Javascript and many other languages. Please see API code examples.

To join a channel, you must authorize using the Authorization: Bearer API_KEY as shown to the right.

Note:

When you initiate a job with the Create job API, you would receive real-time updates of your tasks and jobs via WebSocket. In rare cases, an export job may become completed even before you have subscribed to WebSocket. To avoid this you may call the Get job API once after the WebSocket subscription just to check if the job has finished and have the result ready.

The best practice would be to check if the socket returns the expected url value just after the subscription. If not call the Get job API once and manually check the value. If the GET API doesn’t return the url, the job is still processing.

Websocket Channels & Events

Channel	description	available event
job.{jobId}	Get job update related event	`job_started` `job_failed` `job_completed`
task.{taskId}	Task related all event	`task_started` `task_completed` `task_failed` `task_min_update`
user.{userId}.jobs	User job releted event	`job_started` `job_failed` `job_completed`
user.{userId}.tasks	User task releted event	`task_started` `task_completed` `task_failed` `task_min_update`

Schemas

Job

{
  "id": "5ff3e22059136b0023324b1f",
  "tag": "my-job",
  "createdAt": "2016-08-29T09:12:33.001Z",
  "updatedAt": "2016-08-29T09:12:33.001Z",
  "startedAt": "2016-08-29T09:12:33.001Z",
  "status": "created",
  "tasks": [
    {
      "name": "import-1",
      "operation": "import/upload",
      "status": "processing",
      "job": "5ff3e22059136b0023324b1f",
      "user": "620deb73617adb001968c8eb",
      "createdAt": "2021-01-05T03:50:56.067Z",
      "updatedAt": "2021-01-05T03:50:56.115Z",
      "expiresAt": "2021-01-05T03:50:56.115Z",
      "endedAt": null,
      "result": {
        "form": {
          "url": "https://server1.freeconvert.com/api/upload/5ff3e7337e69c10060706883",
          "parameters": {
            "signature": "46d0fab9c3534661"
          }
        }
      },
      "id": "64ec4fef50e994476de78470"
    },
    {
      "name": "convert-1",
      "operation": "convert",
      "status": "processing",
      "job": "5ff3e22059136b0023324b1f",
      "user": "620deb73617adb001968c8eb",
      "payload": {
        "input_format": "jpg",
        "output_format": "png",
        "options": {
          "quality": 75
        }
      },
      "dependsOn": [
        "64ec4fef50e994476de78470"
      ],
      "createdAt": "2021-01-05T03:50:56.067Z",
      "updatedAt": "2021-01-05T03:50:56.115Z",
      "expiresAt": "2021-01-05T03:50:56.115Z",
      "endedAt": null,
      "id": "64ec5b3750e994476de786e7"
    },
    {
      "name": "export-1",
      "operation": "export/url",
      "status": "processing",
      "job": "5ff3e22059136b0023324b1f",
      "user": "620deb73617adb001968c8eb",
      "payload": {
        "filename": "some.pdf",
        "archive_multiple_files": true
      },
      "dependsOn": [
        "64ec5b3750e994476de786e7"
      ],
      "createdAt": "2021-01-05T03:50:56.067Z",
      "updatedAt": "2021-01-05T03:50:56.115Z",
      "expiresAt": "2021-01-05T03:50:56.115Z",
      "endedAt": null,
      "id": "64ec4fef50e994476de78475"
    }
  ]
}

Properties

Name	Type	Required	Restrictions	Description
id	string(uuid)	true	read-only	ID of the job
tag	string	false	none	An abitrary string which has no effect. It can be used to identify a job with an ID in your system/application.
createdAt	string(date-time)	false	read-only	Timestamp of the creation of the job (ISO8601)
updatedAt	string(date-time)	false	read-only	ISO8601 timestamp of the last update of job.
startedAt	string(date-time)	false	read-only	Timestamp of when the job completed or failed (ISO8601)
status	string	true	read-only	Status of the Job. Possible values are [`created`, `processing`, `completed`, `failed`]
tasks	[Task]	true	none	none

Enumerated Values

Property	Value
status	created
status	processing
status	completed
status	failed

Task

{
  "id": "64e81136fb3a03d26709a152",
  "name": "mytask1",
  "operation": "convert",
  "status": "completed",
  "payload": {
    "options": {
      "image_custom_width": 450,
      "image_custom_height": 300
    }
  },
  "dependsOn": [
    "64ec4fee50e994476de7846d"
  ],
  "job": "64de4d4bc4f617b95a2e4ac0",
  "user": "620deb73617adb001968c8eb",
  "result": {
    "url": "https://s1.freeconvert.com/task/64e5785d555d3b23720c4fd3/tm_logo.jpg"
  },
  "createdAt": "2016-08-29T09:12:33.001Z",
  "startedAt": "2016-08-29T09:12:33.001Z",
  "endedAt": "2016-08-29T09:12:33.001Z",
  "updatedAt": "2016-08-29T09:12:33.001Z",
  "expiresAt": "2016-08-29T09:12:33.001Z"
}

Properties

Name	Type	Required	Restrictions	Description
id	string(uuid)	false	read-only	ID of the task.
name	string	false	none	Friendly name of the task specified by you. Can be used to reference other tasks inside a job.
operation	string	true	none	Name of the operation. For example, to upload a file to FreeConvert using the URL upload method requires a task with operation `import/url`. Possible operations are [ `import/url`, `import/upload`, `import/googlecloud`, `import/azureblob`, `import/s3`, `import/sftp`, `import/base64`, `convert`, `compress`, `merge`, `export/url`, `export/googlecloud`, `export/azureblob`, `export/s3`, `export/sftp`, ]
status	string	false	read-only	Status of the task. Can be one of [`created`, `processing`, `completed`, `failed`, `canceled`, `deleted`].
payload	object	false	none	Parameters sent by you for the task. Payload depends on the type of operation of the task.
dependsOn	array	false	read-only	The task IDs that this task depends on. This task will be automatically started once all depends tasks are complete.
job	string(uuid)	false	read-only	The Job ID the task belongs to.
user	string(uuid)	false	read-only	The user ID the task belongs to.
result	object	false	read-only	Shows the result of the task. If the task has succesfully finished, result property will list the created file(s) here.
» url	string	false	read-only	If the task succeeded, contains the resulting file's download url.
» errorCode	string	false	read-only	If the task failed, contains the error code indicating the cause. -`upload_timeout`: 'import/upload' task timed out before the uplaod completed. - `out_of_conversion_minutes`: User ran out of conversion minutes. - `out_of_conversion_minutes_per_task`: The task reached max conversion minutes usage per task. - `insufficient_permission`: External storage Import or Export task failed due to insufficient permissions. - `invalid_credentials`: External storage Import or Export task failed due to specified credentials were invalid. `processing_failed`: Generic task processing failure. `task_failed`: Task failed due to the Job faile. `unsupported_multifile`: Multi-file import task creation not allowed outside a Job.
» msg	string	false	read-only	Contains further details about why a task failed, if any.
createdAt	string(date-time)	false	read-only	Timestamp of when the task is created. Format ISO8601.
startedAt	string(date-time)	false	read-only	Timestamp of when the task processing is started. Format ISO8601.
endedAt	string(date-time)	false	read-only	Timestamp of when the task finished. Format ISO8601.
updatedAt	string(date-time)	false	read-only	Timestamp of when the task was last updated. Format ISO8601.
expiresAt	string(date-time)	false	read-only	Timestamp of when the task is automatically expired and deleted. Format ISO8601.

Enumerated Values

Property	Value
operation	import/url
operation	import/upload
operation	import/googlecloud
operation	import/azureblob
operation	import/s3
operation	import/sftp
operation	import/base64
operation	convert
operation	compress
operation	merge
operation	export/url
operation	export/googlecloud
operation	export/azureblob
operation	export/s3
operation	export/sftp
status	created
status	processing
status	completed
status	canceled
status	failed
status	deleted
errorCode	upload_timeout
errorCode	out_of_conversion_minutes
errorCode	out_of_conversion_minutes_per_task
errorCode	insufficient_permission
errorCode	invalid_credentials
errorCode	processing_failed
errorCode	task_failed
errorCode	unsupported_multifile

Webhook

{
  "id": "5ff3e22059136b0023424b20",
  "name": "example-webhook",
  "status": "active",
  "events": [
    "job.created",
    "job.success"
  ],
  "url": "http://your-domain.com/webhook-url",
  "signingSecret": "XXXXXXXXXXXX",
  "createdAt": "2020-07-17T07:14:56.004Z",
  "updatedAt": "2020-08-29T07:15:23.005Z",
  "lastErrorAt": "2020-07-21T02:16:03.000Z",
  "lastResponseCode": "NETWORK_ERROR"
}

Properties

Name	Type	Required	Restrictions	Description
id	string(uuid)	false	read-only	ID of the webhook
name	string	false	none	Name of the webhook
status	string	false	none	Status of the webhook [`active`, `inactive`]
events	[string]	false	none	Events for which this webhook will be notified for
url	string	false	none	Webhook URL
signingSecret	string	false	read-only	Webhook signing secret
createdAt	string(date-time)	false	read-only	Timestamp of when the webhook is created. Format ISO8601.
updatedAt	string(date-time)	false	read-only	Timestamp of when the webhook was last updated. Format ISO8601.
lastErrorAt	string(date-time)	false	read-only	Timestamp of when the webhook was last rejected. Format ISO8601.
lastResponseCode	string(date-time)	false	read-only	Last error message received timestamp when sending the webhook.

Enumerated Values

Property	Value
status	active
status	inactive