Convertly Hub

API Documentation

Integrate Convertly Hub into your own applications with the API-key protected conversion API.

Supported directions: JPG to PNG, PNG to JPG, and DOCX to PDF. File size is limited by the active plan; PDF to DOCX is not available yet. Each API key is limited to 30 conversion requests per minute.

POST/api/v1/convert

Converts a file for an active API key on a Basic plan or higher. The active plan determines the maximum file size. Stored results return 202 and are downloaded separately; without storage the file is streamed immediately with 200.

Parameters

  • file (file): The file to be converted.
  • targetFormat (string): The desired output format (e.g., "pdf", "jpg", "png").

Code Examples

curl

curl -X POST \
  https://your-convertly-domain.example/api/v1/convert \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -F 'file=@/path/to/your/file.docx' \
  -F 'targetFormat=pdf'

javascript

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('targetFormat', 'pdf');

fetch('/api/v1/convert', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <YOUR_API_KEY>',
  },
  body: formData,
})
.then(async (response) => {
  if (!response.ok) throw new Error('Conversion request failed');
  if (response.status === 202) return response.json();

  const file = await response.blob();
  const url = URL.createObjectURL(file);
  const link = document.createElement('a');
  link.href = url;
  link.download = 'converted-file';
  link.click();
  URL.revokeObjectURL(url);
})
.then(data => { if (data) console.log(data); })
.catch(error => console.error('Error:', error));

Stored result response (202 Accepted)

{
  "conversionId": "c7a8b9d0-e1f2-g3h4-i5j6-k7l8m9n0o1p2",
  "status": "PENDING",
  "createdAt": "2026-08-24T12:00:00.000Z"
}

Downloading a stored result

When File Storage is enabled in the account, use the returned conversionId with the same API key. Do not use curl -i when writing the binary response to a file, because it adds HTTP headers to the downloaded file.

curl \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -o converted-file.jpg \
  https://your-convertly-domain.example/api/v1/conversions/<CONVERSION_ID>/download

The download endpoint returns 200 with the binary file, 401 for an invalid key, 404 when the stored result is not available yet or no longer exists, and 503 for a storage failure. Retry a newly created stored conversion with a short backoff.

Storage modes

File Storage is an account preference, not a multipart parameter. With it enabled, POST returns 202 and the result is private in storage. With it disabled, POST returns 200 and streams the binary result directly with Cache-Control: no-store; no later download endpoint is available for that conversion.