DocuShell
PProduct HuntLaunch offer: reserve 1 month of Pro free before limited slots open.Reserve free Pro

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.

Reference5 min
View as Markdown
Getting startedShared request flow and error envelope.API overviewSee where URL rendering fits into the full endpoint map.

Section

What It Does

DocuShell loads the target URL in an isolated rendering environment, applies optional viewport and timing settings, and returns the final PDF through the shared jobs API.

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

NameTypeRequiredLocationDescription
AuthorizationBearer <API_KEY>YesheaderUser-owned API key created in the DocuShell dashboard.
Idempotency-KeystringNoheaderRecommended for safely retrying submit requests without creating duplicate jobs.
Content-Typeapplication/jsonYesheaderJSON request body.

Request Fields

NameTypeRequiredLocationDescription
urlstringYesbodyPublic URL to capture.
widthnumberNobodyOptional viewport width in pixels.
heightnumberNobodyOptional viewport height in pixels.
fullHeightbooleanNobodyRender the full page height instead of a fixed viewport capture.
cleanupbooleanNobodyBest-effort clean capture mode for common cookie banners, popups, ads, and chat widgets. Defaults to true.
waitForSelectorstringNobodyOptional CSS selector to wait for before printing.
delaynumberNobodyOptional post-load delay in milliseconds before rendering.
landscapebooleanNobodyRender the PDF in landscape orientation.
grayscalebooleanNobodyProduce 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

Queued response

json

{
  "job_id": "job_01JX8Y5YJ2M2D8N1AQ5F7Q3KVT",
  "status": "queued",
  "cost": 1500,
  "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

  • Submit a URL render job, then poll the shared jobs endpoint until the job finishes.
  • Completed jobs stream a PDF from the shared download route.

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"
  }
}

Authentication failure

401invalid_api_key

Returned when the bearer token is missing, revoked, expired, or not allowed to use the API lane.

401 error

json

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key.",
    "type": "auth_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}

Idempotency conflict

409idempotency_key_reused

Returned when the same Idempotency-Key is reused with a different payload than the original request.

409 error

json

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request.",
    "type": "invalid_request_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}

Webhook access disabled

403webhook_access_disabled

Returned when a Starter API key submits webhook fields. Pro, Growth, and Scale include webhooks.

403 error

json

{
  "error": {
    "code": "webhook_access_disabled",
    "message": "Webhooks are available on Pro, Growth, and Scale. Starter includes API access without webhooks.",
    "type": "billing_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}

Rate limit

429rate_limit_exceeded

Returned when the API key or caller fingerprint exceeds the configured request rate.

429 error

json

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded.",
    "type": "rate_limit_error",
    "request_id": "req_01JX8Y62XCDNZ2BM7TBM2M9Q8E"
  }
}