The canonical REST API reference for converting files across images, documents, video, audio, archives, vectors, CAD, and ebooks.
OrbConvert conversions are executed asynchronously via a distributed worker queue. Every file conversion follows a strict 4-step sequence:
Upload File
Send file via multipart to POST /api/uploads. Receive unique fileId.
Start Job
Submit conversion parameters to POST /api/conversions. Receive conversionId.
Check Status
Poll GET /api/conversions/:id until status becomes completed.
Get Output
Download the converted result via signed outputUrl with automatic MIME attachment headers.
All endpoints require authentication using an API key or session token in the HTTP request headers:
API Key Header
Authorization: Bearer <API_KEY> # or x-api-key: <API_KEY>
Guest Fingerprint Header
x-guest-fingerprint: <CLIENT_UUID>
/api/uploadsUpload a source file via multipart/form-data. The server stores the file in isolated storage, detects the format from the binary signature, and returns a storage key.
Response Payload:
{
"file": {
"fileId": "inputs/user/usr_abc123/quarterly_report.docx",
"originalName": "quarterly_report.docx",
"mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"size": 142080,
"format": "docx",
"category": "document",
"path": "/api/files/inputs%2Fuser%2Fusr_abc123%2Fquarterly_report.docx"
},
"detection": {
"extension": "docx",
"mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"category": "document"
},
"suggestions": ["pdf", "odt", "rtf", "txt"]
}/api/conversionsEnqueue a conversion job with the uploaded fileId and target format. Optional options modify encoder and output behavior.
{
"fileId": "inputs/user/usr_abc123/quarterly_report.docx",
"toFormat": "pdf",
"options": {
"metadata": "remove"
}
}| Parameter | Type | Required | Description |
|---|---|---|---|
| fileId | string | Yes | The storage key returned by POST /api/uploads. |
| toFormat | string | Yes | The desired target format extension (e.g. 'pdf', 'docx', 'webp', 'mp4'). |
| fromFormat | string | No | Source format extension override if different from upload detection. |
| fileName | string | No | Original filename used for attachment naming upon download. |
| jobIntent | string | No | Defaults to 'convert'. Must be set to 'transform' for same-format optimization. Accepted: "convert" | "transform" |
| options | object | No | Category-specific encoder options (see specialized API documentation pages). |
Response Payload (201 Created):
{
"conversionId": "conv_a8b2c4d6",
"queued": false,
"queueDepth": 0
}/api/conversions/:idPoll job progress, status, and download URL. Polling every 2 to 5 seconds is recommended.
Response Payload (Completed):
{
"conversion": {
"id": "conv_a8b2c4d6",
"status": "completed",
"progress": 100,
"fromFormat": "docx",
"toFormat": "pdf",
"outputFileId": "outputs/user/usr_abc123/conv_a8b2c4d6.pdf",
"outputUrl": "https://api.orbconvert.com/api/files/outputs%2Fuser%2Fusr_abc123%2Fconv_a8b2c4d6.pdf/download?token=eyJhbGci...",
"outputSize": 284160,
"createdAt": "2026-09-17T04:00:00.000Z",
"completedAt": "2026-09-17T04:00:04.250Z"
}
}/api/files/:id/downloadDownload the output file stream. Requires valid bearer token or signed URL token parameter (?token=...).
The API returns standard RFC 7807 error envelopes:
| HTTP | Error Code | Cause & Resolution |
|---|---|---|
| 400 | BAD_REQUEST | Missing fileId or toFormat in request body. |
| 400 | SAME_FORMAT_NOOP | Source and target formats are identical without jobIntent: 'transform'. |
| 400 | UNSUPPORTED_FORMAT | Format pairing is not supported by the conversion engine. |
| 400 | INVALID_OPTIONS | Option value is outside accepted bounds or not recognized. |
| 401 | UNAUTHORIZED | Invalid, expired, or missing API key / bearer token. |
| 403 | FORBIDDEN | User account suspended or target tool is disabled by administrator. |
| 404 | NOT_FOUND | Specified fileId or conversionId does not exist. |
| 413 | FILE_TOO_LARGE | Uploaded file exceeds maximum file size for user plan. |
| 429 | QUOTA_EXCEEDED | Daily conversion or data processing quota exceeded. |
| 429 | QUEUE_FULL_USER | Per-user pending queue limit reached. |
| 503 | QUEUE_FULL_GLOBAL | System queue is at maximum capacity. |
| 500 | INTERNAL_SERVER_ERROR | Conversion engine encountered an unexpected error. |
# 1. Upload the source file
curl -X POST "https://api.orbconvert.com/api/uploads" \
-H "Authorization: Bearer <API_KEY>" \
-F "file=@/path/to/quarterly_report.docx"
# 2. Enqueue the conversion
curl -X POST "https://api.orbconvert.com/api/conversions" \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{"fileId":"inputs/user/usr_abc123/quarterly_report.docx","toFormat":"pdf"}'
# 3. Poll conversion status
curl "https://api.orbconvert.com/api/conversions/conv_a8b2c4d6" \
-H "Authorization: Bearer <API_KEY>"
# 4. Download converted file
curl -O -J "https://api.orbconvert.com/api/files/conv_a8b2c4d6/download?token=eyJhbGci..."Office to PDF API
Detailed input formats and options for Word, Excel, and PowerPoint files.
PDF to Office API
Converting PDFs back to editable Word and text documents.
Video Encoding API
Transcoding with codec matrix, CRF, bitrates, and audio stripping.
Compress Images API
Image downsizing, target sizes, and lossless palette quantization.
Was this page helpful?