API Reference
Batch rendering contract for create, progress, downloads, and cancellation
This page is the source of truth for the batch rendering surface. Use it when one workflow must create many PDFs, track item level progress, download outputs, and receive terminal callbacks.
Auth model
All batch routes
X-API-Key required
Create, status, zip, item, and cancel all use the same API key model as the rest of the rendering surface.
Idempotent create
optional Idempotency-Key header
Reuse the same key and body to replay the original accepted job; same key with a different body returns 409 Conflict.
Webhook delivery
outbound server callback
Completion callbacks are sent only when webhook delivery is configured and your plan allows batch webhooks.
Create response
202 Accepted with a batch job id, status route, and expiry metadata.
Status model
Track overall job state and item level state in one status payload.
Terminal events
completed, failed, cancelled, and retention-driven expired.
Create Batch
Create an accepted batch job
Create always returns accepted work when it succeeds. Each item must include exactly one input source: html, url, or templateId.
POST/v1/pdf/batch
Request
X-API-Key
required header
Authorizes create and applies your plan and quota checks.
Idempotency-Key
optional header
Strongly recommended for retry safe create behavior.
items
required array, min 2
Plan-dependent maximum: Free 10, Starter 50, Professional 100, Business 1000.
items[].id
optional string, max 100
Client item identifier; duplicates in one batch are rejected.
items[].html | items[].url | items[].templateId
exactly one required
Each item must pick one input mode.
webhookUrl
optional HTTPS URL
Available on Professional and Business plans.
expiresInHours
optional integer, 1-168 (paid plans)
Free plan retention is fixed to 12 hours and cannot be customized.
Response
jobId
string
Batch identifier for all follow up routes.
status
queued | processing
Initial state immediately after queue admission.
statusUrl
relative route
Poll this route for progress and item details.
estimatedCompletionTime
ISO-8601 string
Estimate only; do not use as a hard deadline.
expiresAt
nullable ISO-8601 string
Output retention deadline.
Status codes: 202, 400, 401, 403, 409, 413, and 429.
Batch Status
Poll one route for job state and item level outcomes
Use status as the control plane for progress tracking, item outcomes, zip readiness, and terminal handling.
GET/v1/pdf/batch/:id
jobId
string
Stable batch identifier used on zip, item, and cancel routes.
status
queued | processing | completed | failed | cancelled | expired
Overall batch lifecycle state.
createdAt
ISO-8601 string
When the batch was accepted.
updatedAt
ISO-8601 string
Most recent persisted update time.
completedAt
nullable ISO-8601 string
Set when the batch completes successfully.
finishedAt
nullable ISO-8601 string
Set when the batch reaches any terminal state.
expiresAt
nullable ISO-8601 string
Output retention deadline used by zip and item download checks.
zipUrl
relative route
Archive endpoint path. The route may still return 404 until at least one item is completed.
manifestAvailable
boolean
Whether a manifest can be retrieved from manifestDownloadUrlEndpoint.
progress.total
integer
Total items accepted into the batch.
progress.completed
integer
Items that produced a completed output.
progress.failed
integer
Items that ended failed or were counted as failed during cancellation.
progress.pending
integer
Items still queued or processing.
progress.throttled
integer
Queued items currently delayed by throttling or temporary capacity wait.
progress.percentComplete
integer 0-100
Completion ratio derived from completed + failed versus total.
estimatedCompletionTime
nullable ISO-8601 string
Estimate while pending work remains.
job.id
string
Duplicate of overall jobId for nested consumers.
job.status
queued | processing | completed | failed | cancelled | expired
Overall status repeated in the nested object.
job.accessExpired
boolean
Indicates whether retained output access has expired.
job.totalCount
integer
Total item count admitted into the batch.
job.completedCount
integer
Items completed successfully.
job.failedCount
integer
Items in failed or cancellation-derived failed state.
job.notes
nullable string
Optional create-time notes.
job.metadata
nullable object
Optional create-time metadata object.
items[].id
string
Internal item identifier.
items[].itemId
string
Client item id when provided, otherwise internal id.
items[].itemIndex
integer
Zero-based index from request order.
items[].status
queued | processing | completed | failed | cancelled
Item lifecycle state.
items[].outputAvailable
boolean
Whether retained item output can be retrieved from its downloadUrlEndpoint.
items[].outputExpiresAt
nullable ISO-8601 string
Item output retention deadline.
items[].errorMessage
nullable string
Human-readable failure or cancellation detail.
items[].retryAttempt
nullable integer
Retry attempt count when the platform is throttling or waiting for capacity.
items[].error.code
nullable string
Stable error code for failed items.
items[].error.message
nullable string
Structured error message for failed items.
items[].pdfSize
integer
PDF size in bytes for completed items.
items[].pages
integer
Page count when known.
items[].processingTimeMs
integer
Render processing duration in milliseconds.
404 behavior
not found / expired
Expired jobs are treated as not found on the status route.
Status codes: 200, 401, and 404.
Zip Retrieval
Download completed outputs as a zip archive
Zip download is a binary response with an attachment filename.
GET/v1/pdf/batch/:id/zip
Content-Type
application/zip
Binary zip payload for completed items.
Auth
X-API-Key required
Must be the key that owns the batch job.
Error states
404, 410
404 means no completed files are currently available to zip; 410 Gone means retention has expired.
Item Retrieval
Download one PDF by batch item id
Use this endpoint when you need a single file rather than the full zip archive.
GET/v1/pdf/batch/:id/:itemId
itemId
path param
Can be the client-provided item id or the internal item id.
Auth
X-API-Key required
Must be the key that owns the batch job.
Content-Type
application/pdf
Streams the selected item as PDF binary.
Error states
404, 410
404 means item is not found or not downloadable yet; 410 Gone means retention already ended.
Cancel
Cancel queued or processing work explicitly
Use the explicit cancel route when work should stop. Already completed items remain completed.
POST/v1/pdf/batch/:id/cancel
jobId
string
Batch identifier for the cancelled job.
status
cancelled | completed | failed
Terminal state after cancel evaluation.
itemsProcessed
integer
Items already terminal before cancellation was applied.
itemsCancelled
integer
Queued or processing items that were transitioned to cancelled.
Error states
404, 410
410 Gone means the batch has already expired and cannot be cancelled.
Status codes: 200, 401, 404, and 410.
Webhook Contract
Handle terminal callbacks when webhookUrl is provided
Callbacks are attempted up to five times with backoff and signed headers. Treat webhook delivery as a terminal notification, then fetch status for source-of-truth details.
event
batch.completed | batch.failed | batch.cancelled
Derived from final batch state.
jobId
string
Batch identifier matching the create and status routes.
status
completed | failed | cancelled
Terminal batch state reported by the callback payload.
completedAt, finishedAt
ISO-8601 strings
Terminal timestamps attached to callback payloads.
progress.total
integer
Total items in the batch.
progress.completed
integer
Items completed when the callback was emitted.
progress.failed
integer
Items failed when the callback was emitted.
statusUrl
absolute URL
Fetch this route for full terminal job + item details.
zipUrl
absolute URL
Download URL for the archive when completed files exist.
Signature headers
X-SolidRelay-Signature-V2, X-SolidRelay-Timestamp, X-SolidRelay-Delivery-Id, X-SolidRelay-Key-Id
Verify the signature before processing callback payloads.
Use the webhook guide for end to end handler sequencing and recovery behavior.
Idempotent Create Behavior
Retry create without duplicating work
Batch create runs through a queue, so idempotency is the safest way to survive dropped connections or ambiguous client timeouts.
Same key + same body
replay existing accepted job
Returns the original batch response instead of enqueuing duplicate work.
Same key + different body
409 Conflict
Prevents accidental collision between unrelated create payloads.
In-flight idempotency key
409 Conflict
Returned when the first request using that key is still being resolved.
Use the idempotency concept page for shared rules across create routes.
Limit Model
Behavior that depends on plan and runtime capacity
Batch behavior changes at the edges when plan limits, webhook entitlement, active backlog, or retention windows are involved.
Batch item cap
Free 10, Starter 50, Professional 100, Business 1000
Create rejects oversized item arrays with 400 Bad Request.
Backlog cap
Free 3, Starter 10, Professional 25, Business 100 active jobs
When queued + processing backlog is full, create returns 429 Too Many Requests.
Webhook entitlement
Professional and Business
Create with webhookUrl on lower plans is rejected with 403 Forbidden.
Retention window
Free fixed 12h, paid default 24h, paid configurable 1-168h
After expiry, download routes return 410 Gone and status treats expired jobs as not found.
For async semantics and accepted work handling, anchor your implementation on execution model.
Next Steps
Connect the batch contract to concepts and implementation workflow
Need the async mental model?
Execution model
Use this concept page to align polling, acceptance, and completion expectations.
Need retry rules?
Idempotency
Use this concept page for replay, collision, and retry safety patterns.
Need an end to end implementation?
Batch with webhooks
Use the guide for handler order, verification, and fallback polling recovery.