API reference

An asynchronous, credit-based REST API for PDF processing. Generate OpenAPI from a single source of truth.

Authentication

Pass your secret key as a bearer token. Keys are shown once and stored only as a SHA-256 hash.

Your key

Quickstart

curl -X POST https://pdflet.top/v1/jobs \
  -H "Authorization: Bearer $PDF_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "compress",
    "input": { "type": "url", "url": "https://example.com/report.pdf" },
    "options": { "quality": "ebook" },
    "webhook_url": "https://yourapp.com/hooks/pdf"
  }'

# 202 Accepted
# { "job_id": "job_01J8ZQ...", "status": "pending", "credits_estimated": 2 }

Endpoints

Method	Path	Description
POST	/v1/jobs	Create a processing job
GET	/v1/jobs	List jobs (filter by status, tool, time)
GET	/v1/jobs/{job_id}	Get job status and result
POST	/v1/jobs/{job_id}/cancel	Cancel a job
POST	/v1/jobs/{job_id}/retry	Retry a failed job (no double charge)
GET	/v1/jobs/{job_id}/download	Get a signed download URL
POST	/v1/files/upload	Upload a file, returns file_id
GET	/v1/files/{file_id}	File metadata
DELETE	/v1/files/{file_id}	Delete a file immediately
GET	/v1/tools	Tool catalog with options and credit cost
GET	/v1/tools/{tool_id}	Single tool details
GET	/v1/account	Account information
GET	/v1/account/usage	Usage statistics
GET	/v1/account/limits	Current quota and rate limits
GET	/v1/account/invoices	Invoice list
GET/POST	/v1/webhooks	List / create webhooks
DELETE	/v1/webhooks/{id}	Delete a webhook
POST	/v1/webhooks/{id}/test	Send a test event

Error codes

code	HTTP	Description
file_too_large	413	File exceeds the plan limit
too_many_files	400	Too many files in one request
invalid_pdf	422	Not a valid PDF (magic-number check failed)
pdf_encrypted	409	PDF is encrypted, unlock it first
password_required	409	A password parameter is required
insufficient_credits	402	Not enough credits
quota_exceeded	429	Monthly quota exhausted
rate_limited	429	Rate limit exceeded
idempotency_key_reuse	409	Same key, different request body
unknown_tool	400	Unknown tool
invalid_job_state	409	Operation not allowed in this state
job_not_found	404	Job ID does not exist
job_expired	410	Result file has expired
processing_failed	500	Engine failed (auto-refunded)