API Reference
Use the single render route as the main contract for creating one PDF
This page is the source of truth for POST /v1/pdf. Use it when you need the exact request shape, the output modes, the sync versus async behavior, the accepted response envelope, and the idempotency rules for create calls that are safe to retry.
Auth model
Render auth
X-API-Key required
Single render is part of the machine-authenticated rendering surface. This route does not use bearer identity.
Create semantics
queued request
The route creates one render job from exactly one input source and can finish inline or return accepted work for later follow up.
Retry protection
Idempotency-Key recommended
Use idempotency on retriable create requests so dropped connections or upstream uncertainty do not create duplicate work.
Credential
Send the render API key in the X-API-Key header on every request.
Input rule
Choose exactly one input source: html, url, or templateId.
Success model
A successful request returns either final output now or accepted work to follow with job routes.
Signed in dashboard users should expect the same contract in Explorer. A single render may complete inline, or it may return accepted work that remains recoverable through dashboard render history and detail views.
Request Contract
Choose one input source, one execution mode, and one output mode
Treat this route as three high level decisions: exactly one input source, one execution mode, and one output mode. Keep nested objects focused by passing template data in data and shared render controls inoptions.
POST/v1/pdf
Request
Single render accepts JSON with one input source plus optional execution, output, and delivery controls.
X-API-Key
required header
Render API key used to authorize the single render request.
Content-Type
required header: application/json
Single render expects a JSON request body.
Idempotency-Key
optional header
Recommended when client retries are possible and you want safe replay behavior.
html | url | templateId
exactly one required
The request must include one input source and rejects mixed or missing input modes.
templateVersionId
optional UUID
Pins a template render to one saved version when templateId is used.
data
optional object
Template data payload for saved template renders. This object does not have one fixed global schema; its accepted keys come from the variables used by the saved template. Use a plain JSON object with keys that match the template variables your saved template expects, such as invoiceNumber, customer.name, or lineItems.
options
optional object
Shared layout, timing, watermark, metadata, runtime, and asset controls. This object is reused across rendering routes, so the detailed field list lives on the dedicated PDF options page.
output
optional enum: binary, base64, or url
Controls the final success shape. Defaults to binary.
executionMode
optional enum: sync or async
Controls whether the route waits briefly for inline completion or returns accepted work immediately. Defaults to sync, but sync can still end in 202 Accepted when work does not finish inside the fixed wait window.
filename
optional string
Suggested file name for downloadable output responses.
disposition
optional enum: inline or attachment
Controls binary response delivery. It only matters when the final output is returned as a file response.
Response
The create route returns either finished output now or accepted work for follow up. Each success shape has its own returned fields and delivery rules.
200 binary
application/pdf
Returned when the request finishes inside the sync wait window and the requested output mode is binary.
Content-Type
application/pdf
Binary success streams the PDF body directly instead of wrapping it in JSON.
Content-Disposition
inline or attachment
Built from the requested disposition value and the resolved file name when binary output is returned inline.
X-Processing-Time
string header
Included on inline binary success to report how long the queued render took before completion.
200 base64 JSON
JSON response
Returned when the request finishes inside the sync wait window and the requested output mode is base64.
success
boolean
Signals that the render completed and the encoded payload is ready in the same response.
encoding
string
Returned as base64 for this output mode.
data
string
Base64-encoded PDF bytes for the finished render.
metadata
object
Describes the finished render without requiring the client to inspect the decoded file first.
metadata.size
number
Size of the finished PDF in bytes.
metadata.processingTime
number
Processing time for the completed render job in milliseconds.
metadata.mode
html, url, or template
Resolved input mode used to generate the PDF.
metadata.format
string
Resolved PDF page format, defaulting to Letter when not overridden.
200 URL JSON
JSON response
Returned when the request finishes inside the sync wait window and the requested output mode is url.
success
boolean
Signals that the render completed and the output URL is ready for retrieval.
url
string
Signed URL for downloading the completed PDF from object storage.
expiresAt
ISO 8601 datetime
Expiration time for the signed output URL.
metadata
object
Describes the finished render behind the signed URL.
metadata.size
number
Size of the finished PDF in bytes.
metadata.processingTime
number
Processing time for the completed render job in milliseconds.
metadata.mode
html, url, or template
Resolved input mode used to generate the PDF.
metadata.format
string
Resolved PDF page format, defaulting to Letter when not overridden.
202 accepted JSON
JSON response
Returned for async requests, and for sync requests that do not finish inside the fixed 5000ms wait window.
success
boolean
Signals that the create request succeeded and moved into accepted job processing.
jobId
string
Identifier for the queued render job.
status
string enum: queued
Initial accepted state returned by create when the job is admitted.
statusUrl
string
Relative route for polling job status after acceptance.
fileUrl
string
Relative route for retrieving the finished PDF after the job completes.
Use the PDF options page for the full shared options object.
Input Modes
Use one input mode per request
Input mode is the first decision on the route. The API accepts inline HTML, a remote URL, or a saved template reference, but never more than one at a time.
html
inline markup
Shortest path for first integrations and direct server-owned document generation.
url
remote page render
Useful when the source document already exists as a web page and the API should render it remotely.
templateId
saved template render
Use with optional templateVersionId and data when the document structure is stored as a reusable template. The shape of the data object comes from the variables inside that template, not from one global request schema.
Validation rule
exactly one input required
The route rejects requests that omit all input modes or combine more than one in the same payload.
Output Modes
Choose how finished output should come back when the request completes inline
Output mode controls the success payload for inline completion. Accepted work still uses the same job follow up path regardless of the requested output mode.
binary
application/pdf response
Streams the PDF directly. Filename and disposition shape the download headers, and the response includes an X-Processing-Time header when output completes inline.
base64
JSON with encoded PDF data
Returns the PDF body as a base64 string plus explicit render metadata fields.
base64.success
boolean
Signals inline completion for the current request.
base64.encoding
base64
Confirms the returned payload encoding.
base64.data
string
Base64-encoded PDF bytes for the finished render.
base64.metadata
object
Metadata block describing the completed render.
base64.metadata.size
number
Finished PDF size in bytes.
base64.metadata.processingTime
number
Render processing time in milliseconds.
base64.metadata.mode
html, url, or template
Resolved input mode used for the finished PDF.
base64.metadata.format
string
Resolved page format, defaulting to Letter when not overridden.
url
JSON with signed output URL
Returns a signed retrieval URL plus explicit render metadata fields.
url.success
boolean
Signals inline completion for the current request.
url.url
string
Signed object-storage URL for downloading the generated PDF.
url.expiresAt
ISO 8601 datetime
Expiration timestamp for the signed output URL.
url.metadata
object
Metadata block describing the completed render behind the signed URL.
url.metadata.size
number
Finished PDF size in bytes.
url.metadata.processingTime
number
Render processing time reported for the completed job.
url.metadata.mode
html, url, or template
Resolved input mode used for the finished PDF.
url.metadata.format
string
Resolved PDF format, defaulting to Letter when not overridden.
Sync Vs Async
Both execution modes are queue-backed
The important distinction is not queued versus non-queued. Both modes enqueue the work. The difference is whether the create route waits briefly for completion or immediately returns accepted work.
sync
default create behavior
The API enqueues the job and waits up to 5000ms for a terminal result. If the render completes in time, the route returns final output inline.
async
always returns accepted work
The API enqueues the job and returns the accepted response envelope immediately instead of waiting for inline completion.
Sync fallback
202 after the wait window
A sync request still returns 202 Accepted when worker completion does not happen inside the fixed wait window.
Client rule
treat 202 as success
Accepted work is part of the normal success path, not a partial failure.
Accepted Response
Use the accepted envelope to switch into the job workflow
When the route returns 202 Accepted, the client should stop expecting final output from the create response and move into the job-status and file-retrieval flow.
success
boolean
Signals that the create request succeeded and the work was admitted.
jobId
string
Identifier for the queued render job.
status
string enum: queued
Initial state for a newly accepted job.
statusUrl
string
Route used to poll job state and determine when output is ready.
fileUrl
string
Route used to download the finished PDF after the job is complete and the output is ready for retrieval.
Signed in dashboard users can also recover accepted single renders later from dashboard render historyand one-job detail pages instead of depending only on transient Explorer state.
Idempotency
Use Idempotency-Key for retry safe create calls
Single render is a create route. If the client can retry because of dropped connections, ambiguous timeouts, or transient upstream failure, bind the request to an Idempotency-Key.
Same key, same body
replay or reconnect
Completed results can be replayed, and in-flight accepted work is reused instead of creating duplicate renders.
Same key, different body
409 Conflict
The API rejects the request rather than guessing which payload the key should represent.
Header validation
database-safe key format
The header is normalized and rejected when it exceeds the safe length boundary or contains markup or control characters.
Replay window
24-hour record retention
Idempotency records expire after the retention window, so a later retry may be treated as a new create request.
Practical rule
reuse the key with the exact same body
If you retry, keep the request body stable so the API can replay or resume the original work safely.
Status Codes
Separate success, client fixes, and platform-level retry cases
The critical distinction is between finished success and accepted success. After that, most non-success responses fall into request-fix, auth-policy, or temporary-capacity buckets.
200 OK
finished output now
The render completed inside the sync wait window and the client already has the final output.
202 Accepted
accepted work to follow
The request succeeded, but the client must continue through the job routes to get the finished result.
400 Bad Request
request contract validation failure
Input mode conflicts, invalid fields, or malformed Idempotency-Key values must be fixed before retrying.
401 Unauthorized
missing or invalid API key
The route requires a valid X-API-Key tied to an active account key.
403 Forbidden
policy or account restriction
The request was authenticated but blocked by account state, key policy, or route specific authorization constraints.
409 Conflict
idempotency collision
The same Idempotency-Key was reused with a different request body or conflicting in-flight state.
404 Not Found
expired stored idempotent output
A replayable idempotent record exists but its stored output has expired.
413 Payload Too Large
size limit exceeded
The input body exceeds the allowed payload boundary and must be reduced before retrying.
429 Too Many Requests
throttled request
Rate limiting or capacity throttling is active; retry with backoff and keep idempotency protection.
503 Service Unavailable
queue or worker failure
The job failed before completion or enqueue could not be satisfied; retry with idempotency and backoff.
500 Internal Server Error
unexpected platform failure
A transient server-side failure occurred. Retry safely with Idempotency-Key and backoff.
504 Gateway Timeout
upstream timeout condition
The request timed out while waiting on dependent services. Retry with backoff and idempotency protection.
Use the shared errors page for retryability, backoff guidance, and standard failure shape.
Next Steps
Move from the create contract into execution, jobs, or shared options
Use the pages below when your next question is about the mental model, the accepted job follow up flow, or the shared render controls that sit behind the options object.
Need the mental model first?
Open execution model concept page
Use the concept page for accepted work versus finished work, queued sync behavior, and the normal 200 versus 202 split.
Need the 202 follow up routes?
Open accepted jobs reference
Use the jobs page for status polling, retry signals, terminal states, and file retrieval after accepted render work.
Need the shared options object?
Open PDF options reference
Use the PDF options page for layout, timing, watermark, metadata, runtime, and asset configuration shared across render requests.