Quickstart
Make your first successful PDF render
This guide gets you to one successful render fast: one render key, one minimal HTML payload, and one request to POST /v1/pdf. Finish this page when your integration can handle both valid success outcomes: immediate output (200 OK) and accepted work (202 Accepted).
Recommended path
- Set the correct auth and headers for rendering routes.
- Send one minimal HTML render request.
- Handle both success outcomes correctly.
Auth
Use the X-API-Key header with a render key.
Route
Use the single render create route with exactly one input source.
POST/v1/pdf
Success
You either get output now or accepted work with a job ID to follow.
If you are testing in the signed in dashboard, Explorer follows the same rule: it may finish inline or it may move into a queued pending state. Accepted single renders can be recovered later from dashboard render history and detail views instead of relying on in memory Explorer state alone.
Before You Begin
Confirm the few setup details that make the first request meaningful
Confirm these first so your first request actually validates the render path instead of setup mistakes.
01
Use a render API key
Create or reveal a render credential in the dashboard and send it in the X-API-Key header.
02
Send JSON with one input source
This quickstart uses inline HTML. Do not combine it with a URL source or a template reference.
03
Expect either immediate output or accepted work
The first request is successful if it returns the file now or returns a job you can complete with status and file routes.
Minimum Request
Send one minimal render before adding options
Use the smallest realistic payload first. After this works, move to templates, URL inputs, and broader request options. By default, sync execution waits up to 5000ms for completion before returning accepted work.
curl -X POST "https://api.solidrelay.io/v1/pdf" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-o hello.pdf \
-d '{
"html": "<h1>Hello Solid Relay</h1><p>Quickstart complete.</p>",
"output": "binary",
"filename": "hello.pdf"
}'After this request, either outcome is success: a completed file now, or a queued job you finish with polling.
Success Responses
Two success outcomes are normal on the first request
Treat both shapes as success. The quickstart is complete when your client handles each one correctly.
Immediate completion
200 OK returns the file now
The render finished inside the fixed wait window, so the PDF is returned directly in the response body.
Accepted work
202 Accepted returns a job to follow
The API accepted the render and returned identifiers for later retrieval. This is expected for async requests and for sync requests that run longer than the 5000ms wait window.
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: inline; filename="hello.pdf"
X-Processing-Time: 412ms
%PDF-1.7
...binary PDF bytes...{
"success": true,
"jobId": "job_01JX8V4Q8S9R6Z0ABCDE12345",
"status": "queued",
"statusUrl": "/v1/pdf/jobs/job_01JX8V4Q8S9R6Z0ABCDE12345",
"fileUrl": "/v1/pdf/jobs/job_01JX8V4Q8S9R6Z0ABCDE12345/file"
}What 202 Accepted Means
Work was accepted, but output is not ready yet
202 Accepted means request validation and queueing succeeded. It does not mean rendering failed, and it does not mean the output is ready to download yet. Treat this as a normal success path.
GET/v1/pdf/jobs/:id
GET/v1/pdf/jobs/:id/file
01
Store the returned identifiers
Keep the job ID, status URL, and file URL from the response.
02
Poll status until the job is terminal
Use the status route on an interval and stop only when the job is terminal (completed or failed).
03
Download the file after completion
Call the file route only after status is completed. If status is failed, use errors and retry guidance instead of downloading.
04
Use dashboard history when you are testing in the app
In the signed in dashboard, accepted Explorer runs can be reopened later from/dashboard/renders and /dashboard/renders/:jobId. Treat that history surface as the durable recovery path for accepted single renders.
# Check queued job status
curl -X GET "https://api.solidrelay.io/v1/pdf/jobs/JOB_ID" \
-H "X-API-Key: YOUR_API_KEY"
# Download the PDF only after status is completed
curl -X GET "https://api.solidrelay.io/v1/pdf/jobs/JOB_ID/file" \
-H "X-API-Key: YOUR_API_KEY" \
-o hello.pdfTroubleshooting
Check these first when the quickstart does not behave as expected
Most first-request failures come from one of three issues: wrong credentials, wrong payload shape, or incomplete handling of accepted work.
Check the render key first
The X-API-Key header may be missing, invalid, revoked, or copied from the wrong account.
Check the request body shape
The payload may be malformed or include more than one input source.
Keep polling until the job is terminal
Queued and processing states are expected. Stop polling only when status becomes completed or failed.
See the shared errors page for retry guidance and failure details.
Next Steps
Move deeper once the first render path is working
After the quickstart succeeds, use the reference pages to expand the request shape, harden the workflow, and understand the rest of the rendering surface.
Need the full contract?
Read the single render reference
See input modes, output modes, execution behavior, idempotency, and the full status code surface for the single render create route.
Need the exact retrieval contract?
Read accepted jobs reference
Use the full status and file route contract to harden polling, completion checks, and download behavior.
Need safe retry strategy?
Read idempotency
Learn how to retry create requests safely without creating duplicate render jobs.