Docs

Async jobs

Set response: async when the job may take longer than you want to hold an HTTP connection — Office convert, large merges, or agent workflows that poll. Completed files are public at GET /v1/files/:id for 24 hours. Optional callbackUrl fires when that job finishes.

Any generating endpoint can return 202 when response is async. Poll with the same API key. Completed files are public at GET /v1/files/:id for 24 hours.

Request

Set response to async. Optional callbackUrl is POSTed when that job finishes.

Example

{
  "file": "UEsDB...",
  "sourceFilename": "deck.pptx",
  "to": "pdf",
  "response": "async"
}

202 body

id and pollUrl. Node: result.kind === "async". Python: AsyncResult.

202

{
  "id": "job_...",
  "status": "processing",
  "pollUrl": "https://api.relaypdf.com/v1/jobs/job_..."
}

Poll

GET /v1/jobs/:id until completed or failed. SDKs: client.jobs.wait(id). status is processing, completed, or failed.

Downloads

Completed jobs include a temporary URL. GET /v1/files/:id does not require a key. SDKs: client.files.download(id).

Durable jobs and reservations

Async jobs retain private inputs for processing, retry transient infrastructure failures, and settle once. A 202 response means accepted, not completed. Poll until completed or failed. Use Idempotency-Key for safe request retries and X-RelayPDF-Max-Charge-Microdollars for a per-request spending cap. See /docs/idempotency and /docs/billing.

Docs hub →Node.js SDK →Playground →