FreeConvert.com API
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 without authentication will also fail.
Base URLs:
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.
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": {
"expires": 1650352160710,
"size_limit": 5368709120,
"max_file_count": 1,
"signature": "503808ac1738adbd"
}
}
},
...
}
Upload File to the Server
# You can also use wget
curl -L "https://server100.freeconvert.com/api/upload/625e27e075ae740013481967/" \
-F "expires=1650352160710" \
-F "max_file_count=1" \
-F "size_limit=5368709120" \
-F "signature=503808ac1738adbd" \
-F "file=@/path/to/file.ext" \
const formData = new FormData();
for (const parameter in task.result.form.parameters) {
formData.append(parameter, task.result.form.parameters[parameter]);
}
fetch(task.result.form.url, {
method: "POST",
body: formData,
})
.then(function (res) {
return res.json();
})
.then(function (body) {
console.log(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.
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: 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",
}
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",
}
const inputBody = {
input: import_task_id,
input_format: "jpg",
output_format: "png",
};
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'
}
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'
}
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',
)
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"}
}
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 for you to control the output file. We'll introduce the advanced options into our documentation soon.
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"
}
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"
}
const inputBody = {
input: import_task_id,
input_format: "jpg"
};
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'
}
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'
}
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'
)
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"}
}
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. We'll introduce the advanced options into our documentation soon.
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
}
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
}
inputBody = {
input: [task_id_1, task_id_2],
output_format: "pdf",
filename: "some.pdf" // optional
};
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
}
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
}
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
)
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
}
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.
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.
Authentication
- HTTP Authentication, scheme: bearer
Every request to the 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.
All API requests are authenticated using the Authorization: Bearer API_KEY
in the header.
API keys do not expire unless you delete them.
User
Current User
Code samples
# You can also use wget
curl -X GET https://api.freeconvert.com/v1/account/me \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
GET https://api.freeconvert.com/v1/account/me 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/account/me',
{
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/account/me',
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/account/me', 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/account/me', 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/account/me");
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/account/me", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
GET /account/me
Show the current user information
Example responses
200 Response
{
"id": "5ff3e22059136b0023324b1f",
"email": "ysqunbyfxjkgotcpjp@test.com",
"role": "user",
"stripeId": "cus_LAOHqzua0vfHGj",
"interface": "api",
"parent": "",
"team": "625c2530448d2800121f7fb8",
"teamRole": "OWNER",
"iat": 1646709671,
"exp": 1649301671
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Successful user lookup, returns a list of attributes for the user in the response body. | User |
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 |
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)
// ...
}
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 , insufficiant_minute ] |
operation | query | string | false | FIlter the list to only show tasks with a given operation (for example, import/url , convert |
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": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"operation": "convert",
"status": "completed",
"payload": {
"options": {
"image_custom_width": 450,
"image_custom_height": 300
}
},
"ignoreError": false,
"job": "4bbaedb0-902b-4b27-8218-8f40d3470a54",
"result": {
"url": "http://example.com/output.ext"
},
"endedAt": "2016-08-29T09:12:33.001Z",
"dependsOn": [
{
"name": "import-1",
"operation": "import/upload",
"status": "processing",
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"redirect": "https://example.com"
},
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"id": "5ff3e22059136b0023324b20"
}
],
"createdAt": "2016-08-29T09:12:33.001Z",
"updatedAt": "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)
// ...
}
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 , dependsOn , and job details in the result. You can seperate multiple inlude values with a comma. |
Example responses
200 Response
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"operation": "convert",
"status": "completed",
"payload": {
"options": {
"image_custom_width": 450,
"image_custom_height": 300
}
},
"ignoreError": false,
"job": "4bbaedb0-902b-4b27-8218-8f40d3470a54",
"result": {
"url": "http://example.com/output.ext"
},
"endedAt": "2016-08-29T09:12:33.001Z",
"dependsOn": [
{
"name": "import-1",
"operation": "import/upload",
"status": "processing",
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"redirect": "https://example.com"
},
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"id": "5ff3e22059136b0023324b20"
}
],
"createdAt": "2016-08-29T09:12:33.001Z",
"updatedAt": "2016-08-29T09:12:33.001Z"
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Successful lookup. Task details are returned in the response body (as per Show a Task endpoint). | 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)
// ...
}
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 |
Wait for Task
Code samples
# You can also use wget
curl -X GET https://api.freeconvert.com/v1/process/tasks/{taskId}/wait \
-H 'Authorization: Bearer {access-token}'
GET https://api.freeconvert.com/v1/process/tasks/{taskId}/wait HTTP/1.1
Host: api.freeconvert.com
const headers = {
'Authorization':'Bearer {access-token}'
};
fetch('https://api.freeconvert.com/v1/process/tasks/{taskId}/wait',
{
method: 'GET',
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.get 'https://api.freeconvert.com/v1/process/tasks/{taskId}/wait',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Authorization': 'Bearer {access-token}'
}
r = requests.get('https://api.freeconvert.com/v1/process/tasks/{taskId}/wait', 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('GET','https://api.freeconvert.com/v1/process/tasks/{taskId}/wait', 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}/wait");
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{
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.freeconvert.com/v1/process/tasks/{taskId}/wait", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
GET /process/tasks/{taskId}/wait
Block the request until the task status is success
or failed
.
This method is not recommended since your system may timeout the request for tasks that takes a long time to complete (i.e. large video conversions). We may also queue your tasks when our systems are busy.
Instead, use webhooks to receive notification of task completion or error.
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
taskId | path | string(ObjectID) | true | ID of task to wait for |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Returns the completed or failed 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 |
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)
// ...
}
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 AND has ignoreError
set to false
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",
"operation": "convert",
"status": "completed",
"payload": {
"options": {
"image_custom_width": 450,
"image_custom_height": 300
}
},
"ignoreError": false,
"job": "4bbaedb0-902b-4b27-8218-8f40d3470a54",
"result": {
"url": "http://example.com/output.ext"
},
"endedAt": "2016-08-29T09:12:33.001Z",
"dependsOn": [
{
"name": "import-1",
"operation": "import/upload",
"status": "processing",
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"redirect": "https://example.com"
},
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"id": "5ff3e22059136b0023324b20"
}
],
"createdAt": "2016-08-29T09:12:33.001Z",
"updatedAt": "2016-08-29T09:12:33.001Z"
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Returns the updated task details (status, operation...etc) | 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 |
List Operations
Code samples
# You can also use wget
curl -X GET https://api.freeconvert.com/v1/query/view/options?operation=string&input_format=string \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}'
GET https://api.freeconvert.com/v1/query/view/options?operation=string&input_format=string 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/query/view/options?operation=string&input_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',
'Authorization' => 'Bearer {access-token}'
}
result = RestClient.get 'https://api.freeconvert.com/v1/query/view/options',
params: {
'operation' => 'string',
'input_format' => 'string'
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {access-token}'
}
r = requests.get('https://api.freeconvert.com/v1/query/view/options', params={
'operation': 'string', 'input_format': 'string'
}, 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/query/view/options', 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/view/options?operation=string&input_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"},
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.freeconvert.com/v1/query/view/options", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
GET /query/view/options
List all possible operations by extention types
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
operation | query | string | true | type of operation |
input_format | query | string | true | input extension |
Example responses
200 Response
{
"type": "document",
"targets": {
"video": [
{
"name": "WEBM",
"slug": "webm",
"ext": "webm",
"type": "video",
"device": false
},
"..."
],
"audio": [
{
"name": "OGG",
"slug": "ogg",
"ext": "ogg",
"type": "audio",
"device": false
},
"..."
],
"image": [
{
"name": "PNG",
"slug": "png",
"ext": "png",
"type": "image",
"device": false
},
"..."
],
"document": [
{
"name": "DOCX",
"slug": "docx",
"ext": "docx",
"type": "document",
"device": false
},
"..."
],
"archive": [
{
"name": "7z",
"slug": "7z",
"ext": "7z",
"type": "archive",
"device": false
},
"..."
],
"ebook": [
{
"name": "AZW3",
"slug": "azw3",
"ext": "azw3",
"type": "ebook",
"device": false
},
"..."
],
"vector": [
{
"name": "WMF",
"slug": "wmf",
"ext": "wmf",
"type": "vector",
"device": false
},
"..."
]
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | successfully get list of possible operation | 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)
// ...
}
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 tasks of each job in the job list. |
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",
"interface": "api",
"isRemoved": false,
"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",
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"redirect": "https://example.com"
},
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"result": {
"form": {
"url": "https://server301.freeconvert.com/api/upload/5ff3e7337e69c10060706883",
"parameters": {
"expires": 1609834355208,
"size_limit": 5368709120,
"max_file_count": 1,
"signature": "46d0fab9c3534661"
}
}
},
"id": "5ff3e22059136b0023324b20"
},
{
"name": "convert-1",
"operation": "convert",
"status": "processing",
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"input_format": "jpg",
"output_format": "png",
"options": {
"quality": 75
}
},
"dependsOn": [
"5ff3e22059136b0023324b20"
],
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"id": "5ff3e22059136b0023324b20"
},
{
"name": "export-1",
"operation": "export/url",
"status": "processing",
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"filename": "some.pdf",
"archive_multiple_files": true
},
"dependsOn": [
"5fcb12f03f51983f4074dfb3",
"5fcb12f03f51983f4074dfb4"
],
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"id": "5ff3e22059136b0023324b20"
}
]
}
],
"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)
// ...
}
POST /process/jobs
Creates a new job along with all of its tasks. A job cretaion request must include at least one task.
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 | any | 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. |
»»» anonymous | body | string | false | none |
»»» anonymous | body | [string] | false | none |
»» ignore_error | body | boolean | false | By default, the job will fail if one of the tasks within it fails. You can ignore failure of specific tasks with this property. |
»» 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",
"interface": "api",
"isRemoved": false,
"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",
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"redirect": "https://example.com"
},
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"result": {
"form": {
"url": "https://server301.freeconvert.com/api/upload/5ff3e7337e69c10060706883",
"parameters": {
"expires": 1609834355208,
"size_limit": 5368709120,
"max_file_count": 1,
"signature": "46d0fab9c3534661"
}
}
},
"id": "5ff3e22059136b0023324b20"
},
{
"name": "convert-1",
"operation": "convert",
"status": "processing",
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"input_format": "jpg",
"output_format": "png",
"options": {
"quality": 75
}
},
"dependsOn": [
"5ff3e22059136b0023324b20"
],
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"id": "5ff3e22059136b0023324b20"
},
{
"name": "export-1",
"operation": "export/url",
"status": "processing",
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"filename": "some.pdf",
"archive_multiple_files": true
},
"dependsOn": [
"5fcb12f03f51983f4074dfb3",
"5fcb12f03f51983f4074dfb4"
],
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"id": "5ff3e22059136b0023324b20"
}
]
}
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)
// ...
}
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",
"interface": "api",
"isRemoved": false,
"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",
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"redirect": "https://example.com"
},
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"result": {
"form": {
"url": "https://server301.freeconvert.com/api/upload/5ff3e7337e69c10060706883",
"parameters": {
"expires": 1609834355208,
"size_limit": 5368709120,
"max_file_count": 1,
"signature": "46d0fab9c3534661"
}
}
},
"id": "5ff3e22059136b0023324b20"
},
{
"name": "convert-1",
"operation": "convert",
"status": "processing",
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"input_format": "jpg",
"output_format": "png",
"options": {
"quality": 75
}
},
"dependsOn": [
"5ff3e22059136b0023324b20"
],
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"id": "5ff3e22059136b0023324b20"
},
{
"name": "export-1",
"operation": "export/url",
"status": "processing",
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"filename": "some.pdf",
"archive_multiple_files": true
},
"dependsOn": [
"5fcb12f03f51983f4074dfb3",
"5fcb12f03f51983f4074dfb4"
],
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"id": "5ff3e22059136b0023324b20"
}
]
}
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)
// ...
}
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 |
Wait for Job
Code samples
# You can also use wget
curl -X GET https://api.freeconvert.com/v1/process/jobs/{jobId}/wait \
-H 'Authorization: Bearer {access-token}'
GET https://api.freeconvert.com/v1/process/jobs/{jobId}/wait HTTP/1.1
Host: api.freeconvert.com
const headers = {
'Authorization':'Bearer {access-token}'
};
fetch('https://api.freeconvert.com/v1/process/jobs/{jobId}/wait',
{
method: 'GET',
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.get 'https://api.freeconvert.com/v1/process/jobs/{jobId}/wait',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Authorization': 'Bearer {access-token}'
}
r = requests.get('https://api.freeconvert.com/v1/process/jobs/{jobId}/wait', 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('GET','https://api.freeconvert.com/v1/process/jobs/{jobId}/wait', 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}/wait");
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{
"Authorization": []string{"Bearer {access-token}"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.freeconvert.com/v1/process/jobs/{jobId}/wait", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
GET /process/jobs/{jobId}/wait
Block the request until the job status is success
or failed
.
This method is not recommended since your system may timeout the request for jobs that takes a long time to complete (i.e. large video conversions). Please note that we may also queue your jobs when our systems are busy.
Instead, use webhooks to receive notification of job completion or error.
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
jobId | path | string(ObjectID) | true | ID of job to wait for |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Returns the completed or failed job details. | 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)
// ...
}
POST /process/import/url
Creates a new task to import a file into FreeConvert from an 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 image URL of the remote path |
» filename | body | string | false | Name of the file |
Example responses
201 Response
{
"status": "processing",
"message": "",
"code": "200",
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"filename": "some.jpg",
"url": "https://example.com",
"operation": "import/url"
},
"operation": "import/url",
"lastAcknowledgeTime": "2021-01-05T03:50:56.067Z",
"user": "620deb73617adb001968c8eb",
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"id": "5ff3e22059136b0023324b20",
"links": {
"self": "https://api.freeconvert.com/v1/process/tasks/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 '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 inputBody = '{
"redirect": "https://example.com"
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'Authorization':'Bearer {access-token}'
};
fetch('https://api.freeconvert.com/v1/process/import/upload',
{
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/upload',
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/upload', 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/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{
"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/upload", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
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.
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.
Form Upload Example
<form action="https://server301.freeconvert.com/api/upload/5ff3e7337e69c10060706883/"
method="POST"
enctype="multipart/form-data">
<input type="hidden" name="expires" value="1609834355208">
<input type="hidden" name="max_file_count" value="1">
<input type="hidden" name="size_limit" value="5368709120">
<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.
Body parameter
{
"redirect": "https://example.com"
}
Parameters
Name | In | Type | Required | Description |
---|---|---|---|---|
body | body | object | false | CODE SAMPLES at the Right panel |
» redirect | body | string | false | The URL to redirect after completion of the upload. |
Example responses
201 Response
{
"status": "processing",
"message": "",
"code": "200",
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"redirect": "https://example.com"
},
"operation": "import/upload",
"lastAcknowledgeTime": "2021-01-05T03:50:56.067Z",
"user": "620deb73617adb001968c8eb",
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"result": {
"form": {
"url": "https://server301.freeconvert.com/api/upload/5ff3e7337e69c10060706883",
"parameters": {
"expires": 1609834355208,
"size_limit": 5368709120,
"max_file_count": 1,
"signature": "46d0fab9c3534661"
}
}
},
"id": "5ff3e22059136b0023324b20",
"links": {
"self": "https://api.freeconvert.com/v1/process/tasks/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)
// ...
}
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 | The filename of the input file, including extension. If none provided we will use the file parameter as the filename for the file. |
Example responses
201 Response
{
"status": "processing",
"message": "",
"code": 200,
"parentUser": null,
"isRemoved": false,
"ignoreError": false,
"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",
"lastAcknowledgeTime": "2021-12-19T09:53:11.330Z",
"user": "113.11.39.191",
"createdAt": "2021-12-19T09:53:11.148Z",
"updatedAt": "2021-12-19T09:53:11.331Z",
"server": "server301.freeconvert.com",
"id": "61bf0107e39b480011724974",
"links": {
"self": "https://api.freeconvert.com/v1/process/tasks/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 |
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)
// ...
}
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 | The filename of the input file, including extension. If none provided we will use the blob parameter as the filename for the file. |
Example responses
201 Response
{
"status": "processing",
"message": "",
"code": 200,
"parentUser": null,
"isRemoved": false,
"ignoreError": false,
"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",
"lastAcknowledgeTime": "2021-12-19T06:06:24.740Z",
"user": "612f012d0c9c43393c424ab6",
"createdAt": "2021-12-19T06:06:24.689Z",
"updatedAt": "2021-12-19T06:06:24.741Z",
"server": "server301.freeconvert.com",
"id": "61becbe0e39b48001172496a",
"links": {
"self": "https://api.freeconvert.com/v1/process/tasks/624c5a94814ef00012b6d30b"
}
}
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)
// ...
}
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 |
» 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",
"message": "",
"code": "200",
"ignoreError": false,
"endedAt": null,
"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",
"lastAcknowledgeTime": "2021-01-05T03:50:56.067Z",
"user": "620deb73617adb001968c8eb",
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"id": "5ff3e22059136b0023324b20",
"links": {
"self": "https://api.freeconvert.com/v1/process/tasks/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)
// ...
}
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",
"message": "",
"code": "200",
"ignoreError": false,
"endedAt": null,
"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",
"lastAcknowledgeTime": "2021-01-05T03:50:56.067Z",
"user": "620deb73617adb001968c8eb",
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"id": "5ff3e22059136b0023324b20",
"links": {
"self": "https://api.freeconvert.com/v1/process/tasks/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)
// ...
}
POST /process/import/base64
Creates a new task to import a file as base64 encoded string into FreeConvert
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",
"message": "",
"code": "200",
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"file": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEKjAqMAAD/2wBDAAoHBwgHBgoICAgLCgoLDhgQDg0NDh0VFhEYIx8lJCIfIiEmKzcvJik0KSEiMEExNDk7Pj4+JS5ESUM8SDc9Pjv/.....",
"filename": "some.jpg"
},
"operation": "import/base64",
"lastAcknowledgeTime": "2021-01-05T03:50:56.067Z",
"user": "620deb73617adb001968c8eb",
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"id": "5ff3e22059136b0023324b20",
"links": {
"self": "https://api.freeconvert.com/v1/process/tasks/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)
// ...
}
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 | The name of the file |
» 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",
"message": "",
"code": 200,
"parentUser": null,
"isRemoved": false,
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"filename": "some.pdf",
"archive_multiple_files": true
},
"dependsOn": [
"5fcb12f03f51983f4074dfb3",
"5fcb12f03f51983f4074dfb4"
],
"operation": "export/url",
"lastAcknowledgeTime": "2021-01-05T03:50:56.067Z",
"user": "620deb73617adb001968c8eb",
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "example.freeconvert.com",
"id": "5ff3e22059136b0023324b20",
"links": {
"self": "https://api.freeconvert.com/v1/process/tasks/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)
// ...
}
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",
"message": "",
"code": 200,
"parentUser": null,
"dependsOn": [],
"isRemoved": false,
"ignoreError": false,
"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",
"lastAcknowledgeTime": "2021-12-19T09:53:11.265Z",
"user": "113.11.39.191",
"createdAt": "2021-12-19T09:53:11.266Z",
"updatedAt": "2021-12-19T09:53:11.266Z",
"id": "61bf0107e39b480011724976",
"links": {
"self": "https://api.freeconvert.com/v1/process/tasks/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)
// ...
}
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 | true | Blob name for storing the file (the filename in the container, including path) |
» filename | body | string | false | The filename of the input file, including extension. If none provided we will use the blob parameter as the filename for the file. |
» 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. |
» blob_prefix | body | string | false | Alternatively to using.blob, you can specify a blob prefix for exporting files. |
» metadata | body | string | false | Object of additional Azure meta data. |
Example responses
201 Response
{
"status": "processing",
"message": "",
"code": 200,
"parentUser": null,
"isRemoved": false,
"ignoreError": false,
"endedAt": null,
"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",
"lastAcknowledgeTime": "2021-01-05T03:50:56.067Z",
"user": "620deb73617adb001968c8eb",
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"id": "5ff3e22059136b0023324b20",
"links": {
"self": "https://api.freeconvert.com/v1/process/tasks/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)
// ...
}
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",
"message": "",
"code": 200,
"parentUser": null,
"isRemoved": false,
"ignoreError": false,
"endedAt": null,
"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"
},
"dependsOn": [
"5fcb12f03f51983f4074dfb3",
"5fcb12f03f51983f4074dfb4"
],
"operation": "export/s3",
"lastAcknowledgeTime": "2021-01-05T03:50:56.067Z",
"user": "620deb73617adb001968c8eb",
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "example.freeconvert.com",
"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)
// ...
}
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",
"message": "",
"code": 200,
"parentUser": null,
"isRemoved": false,
"ignoreError": false,
"endedAt": null,
"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",
"lastAcknowledgeTime": "2021-01-05T03:50:56.067Z",
"user": "620deb73617adb001968c8eb",
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"id": "5ff3e22059136b0023324b20",
"links": {
"self": "https://api.freeconvert.com/v1/process/tasks/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)
// ...
}
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. For example, an image can be resized by dimension or by percentage. |
Example responses
201 Response
{
"status": "processing",
"message": "",
"code": 200,
"parentUser": null,
"isRemoved": false,
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"input_format": "jpg",
"output_format": "png",
"options": {
"image_custom_width": 450,
"image_custom_height": 300
},
"operation": "convert"
},
"dependsOn": [
"5ff3e22059136b0023324b20"
],
"operation": "convert",
"lastAcknowledgeTime": "2021-01-05T03:50:56.067Z",
"user": "620deb73617adb001968c8eb",
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"id": "5ff3e22059136b0023324b20",
"inks": {
"self": "https://api.freeconvert.com/v1/process/tasks/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": "jpg",
"output_format": "png",
"options": {
"pdf_compression_level": "strong",
"pdf_convert_to_gray": true
}
}';
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)
// ...
}
POST /process/compress
Creates a task to compress one input file
Body parameter
{
"input": "import_task_id",
"input_format": "jpg",
"output_format": "png",
"options": {
"pdf_compression_level": "strong",
"pdf_convert_to_gray": 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 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 |
» filename | body | string | false | Name of the output file |
» options | body | object | false | Options depend on the type of compress. For example, an image can be compressed only by quality . |
Example responses
201 Response
{
"status": "processing",
"message": "",
"code": 200,
"parentUser": null,
"isRemoved": false,
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"input_format": "pdf",
"filename": "sample.pdf",
"options": {
"pdf_compression_level": "strong",
"pdf_convert_to_gray": true
},
"operation": "compress"
},
"dependsOn": [
"5ff3e22059136b0023324b20"
],
"operation": "compress",
"lastAcknowledgeTime": "2021-01-05T03:50:56.067Z",
"user": "620deb73617adb001968c8eb",
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"id": "5ff3e22059136b0023324b20",
"links": {
"self": "https://api.freeconvert.com/v1/process/tasks/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"
}';
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)
// ...
}
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"
}
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 |
Example responses
201 Response
{
"status": "processing",
"message": "",
"code": 200,
"parentUser": null,
"isRemoved": false,
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"output_format": "pdf",
"filename": "some.pdf",
"operation": "merge"
},
"dependsOn": [
"5fcb12f03f51983f4074dfb3",
"5fcb12f03f51983f4074dfb4"
],
"operation": "merge",
"lastAcknowledgeTime": "2021-01-05T03:50:56.067Z",
"user": "620deb73617adb001968c8eb",
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"id": "5ff3e22059136b0023324b20",
"links": {
"self": "https://api.freeconvert.com/v1/process/tasks/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 |
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)
// ...
}
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.finished"
],
"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",
"links": {
"self": "http://api.freeconvert.comhttps://notification.freeconvert.com/webhooks/5ff3e22059136b0023424b20"
}
}
],
"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"
]
}';
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)
// ...
}
POST https://notification.freeconvert.com/webhooks
Create a webhook to receive task/job updates in your application.
Body parameter
{
"url": "string",
"events": [
"job.created"
]
}
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. |
» events | body | [string] | false | Select notification events to be sent via the webhook. |
Example responses
201 Response
{
"id": "5ff3e22059136b0023424b20",
"name": "example-webhook",
"status": "active",
"events": [
"job.created",
"job.finished"
],
"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",
"links": {
"self": "http://api.freeconvert.comhttps://notification.freeconvert.com/webhooks/5ff3e22059136b0023424b20"
}
}
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)
// ...
}
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.
To join a channel, you must authorize using the Authorization: Bearer API_KEY
as shown to the right.
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",
"interface": "api",
"isRemoved": false,
"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",
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"redirect": "https://example.com"
},
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"result": {
"form": {
"url": "https://server301.freeconvert.com/api/upload/5ff3e7337e69c10060706883",
"parameters": {
"expires": 1609834355208,
"size_limit": 5368709120,
"max_file_count": 1,
"signature": "46d0fab9c3534661"
}
}
},
"id": "5ff3e22059136b0023324b20"
},
{
"name": "convert-1",
"operation": "convert",
"status": "processing",
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"input_format": "jpg",
"output_format": "png",
"options": {
"quality": 75
}
},
"dependsOn": [
"5ff3e22059136b0023324b20"
],
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"id": "5ff3e22059136b0023324b20"
},
{
"name": "export-1",
"operation": "export/url",
"status": "processing",
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"filename": "some.pdf",
"archive_multiple_files": true
},
"dependsOn": [
"5fcb12f03f51983f4074dfb3",
"5fcb12f03f51983f4074dfb4"
],
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"id": "5ff3e22059136b0023324b20"
}
]
}
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. |
interface | string | false | read-only | The platform from where the API request has been created |
isRemoved | boolean | false | none | none |
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 |
---|---|
interface | api |
interface | web |
status | created |
status | processing |
status | completed |
status | failed |
Task
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"operation": "convert",
"status": "completed",
"payload": {
"options": {
"image_custom_width": 450,
"image_custom_height": 300
}
},
"ignoreError": false,
"job": "4bbaedb0-902b-4b27-8218-8f40d3470a54",
"result": {
"url": "http://example.com/output.ext"
},
"endedAt": "2016-08-29T09:12:33.001Z",
"dependsOn": [
{
"name": "import-1",
"operation": "import/upload",
"status": "processing",
"ignoreError": false,
"endedAt": null,
"job": "5ff3e22059136b0023324b1f",
"payload": {
"redirect": "https://example.com"
},
"createdAt": "2021-01-05T03:50:56.067Z",
"updatedAt": "2021-01-05T03:50:56.115Z",
"server": "server301.freeconvert.com",
"id": "5ff3e22059136b0023324b20"
}
],
"createdAt": "2016-08-29T09:12:33.001Z",
"updatedAt": "2016-08-29T09:12:33.001Z"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
id | string(uuid) | false | read-only | ID of the task. |
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 | Payload sent by you for the task. Payload depends on the type of operation of the task. |
ignoreError | boolean | false | none | If this task should be ignored if failed. |
job | string(uuid) | false | none | The Job 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. |
endedAt | string(date-time) | false | read-only | Timestamp of when the task finished. Format ISO8601. |
dependsOn | [Task] | false | none | List the task(s) this task depends on. For example, a convert task may list an upload task as a dependency. Only available if the include parameter is set to dependsOn . |
createdAt | string(date-time) | false | read-only | Timestamp of when the task is created. Format ISO8601. |
updatedAt | string(date-time) | false | read-only | Timestamp of when the task was last updated. 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 |
status | insufficiant_minute |
User
{
"id": "5ff3e22059136b0023324b1f",
"email": "ysqunbyfxjkgotcpjp@test.com",
"role": "user",
"stripeId": "cus_LAOHqzua0vfHGj",
"interface": "api",
"parent": "",
"team": "625c2530448d2800121f7fb8",
"teamRole": "OWNER",
"iat": 1646709671,
"exp": 1649301671
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
id | string(uuid) | true | none | ID of the User |
string(email) | true | none | Email of the User | |
role | string(string) | true | none | Role of the User |
stripeId | string(string) | false | none | Stripe ID of the user |
interface | string(enum) | false | none | The platform from where the API request has been created |
parent | string(string) | false | none | none |
team | string(string) | true | none | The ID of the team |
teamRole | string(enum) | true | none | The role inside the team |
iat | number(unix) | false | none | none |
exp | number(unix) | false | none | none |
Webhook
{
"id": "5ff3e22059136b0023424b20",
"name": "example-webhook",
"status": "active",
"events": [
"job.created",
"job.finished"
],
"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",
"links": {
"self": "http://api.freeconvert.comhttps://notification.freeconvert.com/webhooks/5ff3e22059136b0023424b20"
}
}
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. |
links | object | false | none | none |
Enumerated Values
Property | Value |
---|---|
status | active |
status | inactive |
Schema
{
"id": 0
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
id | integer(int64) | false | none | none |