API Reference
All endpoints at https://pdfxdoc.com. API keys: doc_ + 64 hex chars. Download OpenAPI Spec →
Authentication
Pass your API key in the X-Api-Key header. Never put API keys in query parameters — they get logged and exposed in your browser history.
curl -H "X-Api-Key: doc_your_key" https://pdfxdoc.com/api/v1/convert
Error Codes
| Code | Meaning |
|---|---|
| 401 | Invalid/missing API key |
| 429 | Rate limit exceeded |
| 413 | File too large for tier |
| 400 | Invalid parameters |
| 404 | Task not found |
| 503 | Processing failed |
Rate Limits by Tier
| Tier | Pages/Day | Pages/Hr | File Size | Concurrent | Webhooks |
|---|---|---|---|---|---|
| Free | 50 | 10 | 10 MB | 3 | — |
| Pro | 500 | 50 | 50 MB | 5 | ✓ |
| Business | 5,000 | 500 | 100 MB | 10 | ✓ |
Auth Endpoints
POST/api/auth/register
Create account, get API key immediately.
Request
{"email":"[email protected]","password":"min-8-chars","name":"Optional"}Response 200
{"api_key":"doc_a1b2c3...","message":"Account created."}POST/api/auth/login
Sign in, get JWT (7 days).
{"email":"[email protected]","password":"your-password"}Response 200
{"access_token":"eyJ...","token_type":"bearer"}POST/api/auth/forgot-password
Request password reset. Always 200.
{"email":"[email protected]"}POST/api/auth/reset-password
Reset with token.
{"token":"...","new_password":"min-8-chars"}Key Management
GET/api/keys
List API keys (session).
POST/api/keys/create
Create key (full key once).
{"label":"Production"}DELETE/api/keys/:id
Revoke immediately.
Usage
GET/api/usage
Usage stats + tier info.
Response 200
{"pages_today":12,"pages_this_hour":3,"total_tasks":47,"tier":"Free","limit_pages_per_hour":10,"limit_pages_per_day":50,"max_file_size_mb":10,"max_concurrent":3,"has_webhooks":false}Conversion
POST/api/v1/upload
Get presigned R2 URL for large files.
Request
{"filename":"report.pdf","size":25000000}Response 200
{"upload_url":"https://...","r2_key":"uploads/tsk_abc.pdf","expires_in":300}POST/api/v1/convert
Submit PDF. Two modes: multipart (≤10MB) or JSON with r2_key from upload.
Parameters
| Param | Values | Default |
|---|---|---|
file | PDF binary | — |
r2_key | From upload | — |
output_format | json, docx, md, html | json |
ocr_lang | eng, ara, ara,eng | eng |
table_mode | fast, accurate | accurate |
webhook_url | URL (Pro+) | — |
curl (small file)
curl -X POST https://pdfxdoc.com/api/v1/convert -H "X-Api-Key: doc_key" -F "[email protected]" -F "output_format=json" -F "ocr_lang=ara,eng"
Python
import requests
r = requests.post("https://pdfxdoc.com/api/v1/convert",
headers={"X-Api-Key": "doc_key"},
files={"file": open("invoice.pdf","rb")},
data={"output_format":"json","ocr_lang":"ara,eng"})
print(r.json()) # {"task_id":"tsk_a1b2c3d4","status":"queued"}Response 200
{"task_id":"tsk_a1b2c3d4","status":"queued"}GET/api/v1/result/:task_id
Poll for result.
Responses
{"task_id":"...","status":"processing"}
{"task_id":"...","status":"done","document":{...},"processing_time":3.2}
{"task_id":"...","status":"failed","error_message":"..."}GET/api/v1/download/:task_id
Download DOCX binary.
curl -H "X-Api-Key: doc_key" https://pdfxdoc.com/api/v1/download/tsk_abc123 -o result.docx
Webhooks
GET/api/webhook-secret
Check if webhook secret is configured (session).
PUT/api/webhook-secret
Set/rotate secret (min 16 chars, session).
{"secret":"your-secret-at-least-16-chars"}