Convertz API documentation

Convert files through a simple async API flow: upload a file, receive a job ID, check status, and download the result when processing is complete.

POST /api/convert
GET /api/status/{job_id}
GET /api/download/{job_id}
GET /api/health

Overview

Convertz API provides asynchronous document conversion. Instead of waiting for long-running conversions in a single request, you submit a job, receive a job ID, and poll for completion.

This design works well for SaaS products, dashboards, internal tools, automation systems, and bulk processing workflows.

Base URL

https://convertz.it

All example paths below are relative to this base URL.

Authentication

Requests should include your API key as a Bearer token in the Authorization header. 

Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with the key generated in your dashboard.

Conversion flow

1. Upload a file to /api/convert.
2. Receive a response with job_id and initial status.
3. Poll /api/status/{job_id} until the job is completed.
4. Download the converted file from /api/download/{job_id}.

Supported conversions

Source format Target formats
DOC DOCX, ODT, RTF, TXT, PDF, HTML, EPUB, FODT
DOCX DOC, ODT, RTF, TXT, PDF, HTML, EPUB, FODT
ODT DOC, DOCX, RTF, TXT, PDF, HTML, EPUB, FODT
RTF DOC, DOCX, ODT, TXT, PDF, HTML, EPUB, FODT
TXT DOC, DOCX, ODT, RTF, PDF, HTML, EPUB, FODT
HTML DOC, DOCX, ODT, RTF, PDF, TXT, EPUB, FODT
PDF DOCX, HTML, TXT

Notes

PDF conversion workflows may use different internal methods depending on the requested output. For most integrations, using automatic method selection is the easiest option.

Endpoints

Convert file

POST /api/convert

Upload a file and request conversion to a target format.

Field Type Required Description
file file Yes The uploaded source file.
target_format string No* Desired output format such as docx, txt, html, pdf.
conversion_method string No Conversion engine. Common values include auto, unoconv, libreoffice, pdf2docx, pymupdf.

* In many flows the API can default intelligently, but sending target_format explicitly is recommended.

Check status

GET /api/status/{job_id}

Returns the current status of a conversion job.

Download converted file

GET /api/download/{job_id}

Downloads the converted file once the job has completed.

Health check

GET /api/health

Returns a simple health response for uptime checks and monitoring.

Examples

Example 1: PDF to DOCX

curl -X POST "https://convertz.it/api/convert" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "target_format=docx" \
  -F "conversion_method=auto"

Example response

{
  "job_id": "eaa81fdc-c790-4aa0-b471-520892688e3a",
  "status": "queued"
}

Check status

curl -X GET "https://convertz.it/api/status/eaa81fdc-c790-4aa0-b471-520892688e3a" \
  -H "Authorization: Bearer YOUR_API_KEY"

Completed status response

{
  "job_id": "eaa81fdc-c790-4aa0-b471-520892688e3a",
  "status": "completed",
  "file_path": "/app/static/converted_files/eaa81fdc-c790-4aa0-b471-520892688e3a_converted.docx",
  "callback_url": null
}

Download converted file

curl -L -X GET "https://convertz.it/api/download/eaa81fdc-c790-4aa0-b471-520892688e3a" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o converted.docx

Example 2: DOCX to PDF

curl -X POST "https://convertz.it/api/convert" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "target_format=pdf" \
  -F "conversion_method=libreoffice"

Example 3: PDF to TXT

curl -X POST "https://convertz.it/api/convert" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "target_format=txt" \
  -F "conversion_method=pymupdf"

Errors and integration notes

Common issues to handle in your client:

Situation What to do
Unsupported format pair Validate allowed source/target combinations before sending the request.
Job still queued or processing Poll the status endpoint again after a short delay.
Download requested too early Only call the download endpoint after status becomes completed.
Authentication failure Verify your API key and Bearer token header format.