Reference

Webpage to PDF

Use this endpoint to render public webpages into print-ready PDFs while keeping auth, polling, and downloads consistent with the rest of the DocuShell API.

Reference

View as Markdown

Getting startedShared request flow and error envelope.API overviewSee where URL rendering fits into the full endpoint map.

Reference

Endpoint Reference

POST/v1/url/render

Queue a URL capture job that renders a public webpage into a PDF.

Auth

Bearer token required.

Idempotency

Supports optional Idempotency-Key replay protection.

Content Type

application/json

Headers

Name	Type	Required	Location	Description
Authorization	Bearer <API_KEY>	Yes	header	User-owned API key created in the DocuShell dashboard.
Idempotency-Key	string	No	header	Recommended for safely retrying submit requests without creating duplicate jobs.
Content-Type	application/json	Yes	header	JSON request body.

Request Fields

Name	Type	Required	Location	Description
url	string	Yes	body	Public URL to capture.
width	number	No	body	Optional viewport width in pixels.
height	number	No	body	Optional viewport height in pixels.
fullHeight	boolean	No	body	Render the full page height instead of a fixed viewport capture.
cleanup	boolean	No	body	Best-effort clean capture mode for common cookie banners, popups, ads, and chat widgets. Defaults to true.
waitForSelector	string	No	body	Optional CSS selector to wait for before printing.
delay	number	No	body	Optional post-load delay in milliseconds before rendering.
landscape	boolean	No	body	Render the PDF in landscape orientation.
grayscale	boolean	No	body	Produce a grayscale PDF.

Request Notes

Private networks, metadata endpoints, and intranet-style targets are blocked by URL security validation before rendering.
Clean capture is best-effort. Set cleanup to false to render the page without banner, popup, ad, or chat-widget cleanup.

Render a public page

bash

curl -X POST "https://api.docushell.com/api/v1/url/render" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: url-demo-001" \
  -d '{
    "url": "https://docushell.com/pricing",
    "width": 1440,
    "height": 960,
    "fullHeight": true,
    "cleanup": true,
    "waitForSelector": "main",
    "delay": 1500
  }'

Try It Now

Console placeholder for safe sandbox execution.

Coming soon

MethodEndpointHeadersRequest Body

{
  "example": "Paste a request body when the sandbox is enabled"
}

Queued response

json

{
  "job_id": "job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
  "status": "queued",
  "cost": 25,
  "service": "webpage-to-pdf",
  "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E",
  "links": {
    "status": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  }
}

Status response

json

{
  "job_id": "job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
  "status": "done",
  "service": "webpage-to-pdf",
  "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E",
  "result": {
    "filename": "quarterly-report.pdf",
    "sizeBytes": 184322,
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  },
  "completed_at": "2026-04-24T10:12:56.145Z",
  "links": {
    "status": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  }
}

Completed jobs return a public download link and keep the file streaming URL behind the gateway. Downloads use application/pdf.

Poll And Download

Completed jobs stream one application/pdf file from GET /v1/jobs/:jobId/download.
See [Quickstart](/getting-started#queued-response) for the shared submit, poll, and download flow.

Failure Notes

Missing or invalid url fields return invalid_request.
Blocked private-network URLs are rejected by the rendering service before work is queued.
backend_unavailable indicates the render backend could not be reached.

Missing URL field

400invalid_request

The public lane requires a non-empty url string.

400 error

json

{
  "error": {
    "code": "invalid_request",
    "message": "A valid url field is required.",
    "type": "invalid_request_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}

Code Samples

Render a public page

curl -X POST "https://api.docushell.com/api/v1/url/render" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: url-demo-001" \
  -d '{
    "url": "https://docushell.com/pricing",
    "width": 1440,
    "height": 960,
    "fullHeight": true,
    "cleanup": true,
    "waitForSelector": "main",
    "delay": 1500
  }'

Queued response

{
  "job_id": "job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
  "status": "queued",
  "cost": 25,
  "service": "webpage-to-pdf",
  "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E",
  "links": {
    "status": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
    "download": "/v1/jobs/job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT/download"
  }
}