Concepts
Understand accepted work versus finished work
Render create routes run through a queue. A successful create request can either return finished output now or return accepted work to finish through follow up routes. Both are normal success paths and each requires a different client action.
Accepted work
The API admitted the request and returned identifiers, but output is not ready yet.
Finished work
The request already produced output you can use immediately.
Design rule
Model both outcomes as success paths from day one so retries and polling stay predictable.
Accepted Vs Finished
Success means either "admitted" or "done"
The most important distinction is timing. Accepted means the platform now owns the work. Finished means the work has already reached usable output. Integrations break when these are treated as the same state.
200 and 202 comparison
200 OK
finished response
Consume output now. You do not need a status loop for this request path.
202 Accepted
admitted response
Persist IDs and continue through status routes until the job or batch becomes terminal.
Single Render
Single render can finish inline or continue as accepted work
The single render create route always starts as queued render work. The execution mode only changes how long the create call waits before returning.
POST/v1/pdf
- Sync mode waits up to a short fixed window (5 seconds) for terminal completion before it falls back to accepted work.
- Async mode returns accepted work immediately and expects follow up through status routes.
- In both modes, an accepted response is still a successful create outcome.
- In the signed in dashboard, Explorer follows the same contract: a request can finish inline or switch into a queued pending state that is recoverable later from
/dashboard/renders.
Create single render
-> queued work is admitted
-> if work finishes in the sync wait window: 200 OK
-> otherwise (or async mode): 202 Accepted
-> follow status until terminal, then fetch output if availableBatch Behavior
Batch creation is acceptance-first by design
Batch create confirms admission of the set, not completion of every item. That means batch success starts with accepted work and continues through progress checks.
- The batch create route returns accepted work for successful batch admission.
- Overall completion means the workflow is done processing, not that every item succeeded.
- Treat final batch success as a decision based on completed and failed counts, not status text alone.
POST/v1/pdf/batch
After Acceptance
Use one control loop after the create response
Once work is accepted, switch from create-response handling to lifecycle handling. This loop is the same mental model for single render jobs and batch jobs.
01
Persist identifiers from the accepted response
Store job IDs, batch IDs, and status URLs so your process can recover across retries and restarts.
02
Poll status until terminal
Check the status route until the resource is completed, failed, cancelled, or expired.
GET/v1/pdf/jobs/:id
GET/v1/pdf/batch/:id
03
Download only when output is ready and retained
Use file and zip routes only after status confirms downloadable output is available.
GET/v1/pdf/jobs/:id/file
GET/v1/pdf/batch/:id/zip
04
Use the dashboard recovery path when you are operating inside the app
Signed in users do not need to keep accepted single render state in Explorer alone. The dashboard render history and detail routes at /dashboard/renders and /dashboard/renders/:jobIdprovide the durable recovery path for accepted work.
Common Mistakes
Most execution bugs are control-flow bugs
These mistakes often look like transport errors but usually come from collapsing accepted work and finished work into one path.
- Do not treat 202 Accepted as a failure. It is a normal create success that requires follow up.
- Do not treat sync mode as "not queued." Sync still queues work and only adds a short wait window.
- Do not attempt file download before status confirms completed output.
- Do not assume a completed batch means every item succeeded; verify failed and throttled counts.
- Do not keep all state in memory only; persist accepted identifiers so retries can resume safely.
Next Steps
Use these canonical routes when you need contract details
Keep this page as the mental model, then move to reference routes for exact request fields and payload contracts.
Need create route details?
Open single render reference
Use this for the exact single render create contract, including sync wait behavior and accepted responses.
POST/v1/pdf
Need follow up payload fields?
Open render jobs reference
Use this for job statuses, retry signals, and single render file retrieval behavior.
Need batch workflow contracts?
Open batch rendering reference
Use this for batch admission, progress payloads, zip/item retrieval, and webhook behavior.