Full documentation for the OrbConvert REST API. Integrate file conversions into your applications with our simple, predictable API.
JSON-based REST API
256-bit SSL encrypted
<2s avg response time
Python, JS, Go clients
https://api.orbconvert.com
All API requests must be made over HTTPS. HTTP requests will fail.
All API requests require authentication via an API key in the x-api-key header:
x-api-key: ch_live_your_api_key_here
Get your API key from Settings → Developers. Keep your key secure — never expose it in client-side code.
# 1. Upload a file
curl -X POST https://api.orbconvert.com/api/uploads \
-H "x-api-key: ch_live_your_api_key_here" \
-F "file=@document.pdf"
# 2. Start the conversion
curl -X POST https://api.orbconvert.com/api/conversions \
-H "x-api-key: ch_live_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"fileId": "file_abc123", "toFormat": "docx"}'
# 3. Poll for status
curl -X GET https://api.orbconvert.com/api/conversions/conv_xyz789 \
-H "x-api-key: ch_live_your_api_key_here"Official client libraries for seamless integration. SDKs are planned — not yet published.
Every error response includes a JSON body with details about what went wrong.
| Code | Message | Description | Suggestion |
|---|---|---|---|
| 400 | Bad Request | Invalid parameters, unsupported format, or same-format request | Check your request body. Verify target format is valid for the file category and not identical to source format. |
| 401 | Unauthorized | Missing or invalid API key or JWT token | Ensure you are passing a valid API key in the x-api-key header or Bearer token. |
| 403 | Forbidden | Account quota exceeded or suspended | Check your plan limits in the dashboard. Free users have a 1 GB daily data allowance. |
| 404 | Not Found | Conversion ID or file ID not found | Verify the conversion ID is correct. IDs start with 'conv_'. |
| 413 | Payload Too Large | File exceeds maximum allowed size | Guest: 25 MB, Free: 100 MB, Pro: 2 GB, Business: 5 GB. Upgrade for higher limits. |
| 429 | Too Many Requests | Rate limit or queue capacity exceeded | Implement exponential backoff. Check X-RateLimit-Reset header or wait for queued jobs to complete. |
| 500 | Internal Server Error | Unexpected server processing error | Retry with exponential backoff. Contact support if persists. |
Was this page helpful?