{"openapi":"3.1.0","info":{"title":"PDFik Public API","description":"\nPublic API endpoints for asynchronously generating PDFs from HTML markup or public URLs.\n\nFor full developer guides, tutorials, and SDK examples, visit our [API Documentation Portal](https://docs.pdfik.net).\n    ","termsOfService":"https://docs.pdfik.net/legal/terms","contact":{"name":"PDFik Support","url":"https://pdfik.net/dashboard","email":"support@pdfik.net"},"license":{"name":"Commercial","url":"https://docs.pdfik.net/legal/terms"},"version":"1.0.0"},"servers":[{"url":"https://api.pdfik.net","description":"Production"}],"paths":{"/url-to-pdf":{"post":{"tags":["PDF Tasks"],"summary":"Convert URL to PDF","description":"Asynchronously converts a public URL to a PDF document.\n\n**Flow:**\n1. Submit the URL → receive a `job_id`\n2. Poll `GET /jobs/{job_id}` until `status == \"done\"`\n3. Fetch the file via `GET /jobs/{job_id}/download`\n\n**Rate Limits:** See [Rate Limits &amp; Quotas](https://docs.pdfik.net/rate-limits).","operationId":"url_to_pdf_url_to_pdf_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional idempotency key (1-255 chars: letters, digits, `_ - . :`). Retrying a request with the same key returns the original job instead of creating a duplicate.","title":"Idempotency-Key"},"description":"Optional idempotency key (1-255 chars: letters, digits, `_ - . :`). Retrying a request with the same key returns the original job instead of creating a duplicate."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UrlToPdfRequest"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCreatedResponse"}}}},"400":{"description":"Bad Request — invalid URL or SSRF blocked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Payload Too Large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment Required — quota exceeded or plan upgrade required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/html-to-pdf":{"post":{"tags":["PDF Tasks"],"summary":"Convert HTML to PDF","description":"Converts raw HTML markup to a PDF document.\n\n**HTML is sanitized** before rendering (script injection protection).\n\n**Options example:**\n```json\n{\n  \"options\": {\n    \"format\": \"A4\",\n    \"landscape\": true,\n    \"margin\": {\"top\": \"20mm\", \"bottom\": \"20mm\"}\n  }\n}\n```","operationId":"html_to_pdf_html_to_pdf_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional idempotency key (1-255 chars: letters, digits, `_ - . :`). Retrying a request with the same key returns the original job instead of creating a duplicate.","title":"Idempotency-Key"},"description":"Optional idempotency key (1-255 chars: letters, digits, `_ - . :`). Retrying a request with the same key returns the original job instead of creating a duplicate."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HtmlToPdfRequest"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCreatedResponse"}}}},"400":{"description":"Bad Request — empty HTML or SSRF","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Payload Too Large — HTML exceeds limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment Required — quota exceeded or plan upgrade required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/jobs/{job_id}":{"get":{"tags":["Jobs"],"summary":"Get Job Status","description":"Returns the current status and metadata for a PDF generation job.\n\n**Status values:**\n| Status | Description |\n|--------|-------------|\n| `queued` | Job is waiting in queue |\n| `rendering` | PDF is being generated |\n| `uploading` | PDF is uploading to storage |\n| `done` | Job completed successfully |\n| `failed` | Job failed — check `error_code` |","operationId":"get_job_status_jobs__job_id__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatusResponse"}}}},"404":{"description":"Job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment Required — quota exceeded or plan upgrade required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/jobs/{job_id}/download":{"get":{"tags":["Jobs"],"summary":"Stream PDF File","description":"Streams the generated PDF binary directly. Returns `Content-Type: application/pdf`.\n\nThe file is available for 24 hours after the job finishes (410 `#file-expired` after that), for at most 3 download attempts (429 `#download-limit-exceeded`), with one active stream at a time.","operationId":"download_job_file_jobs__job_id__download_get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"PDF binary stream","content":{"application/json":{"schema":{}},"application/pdf":{}}},"404":{"description":"Job not found or not complete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"File expired — the retention window has passed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment Required — quota exceeded or plan upgrade required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"CompressionOptions":{"properties":{"level":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Level","description":"Structural compression level (1-9): 1-3 basic, 4-6 object streams, 7-9 linearize","example":6},"image_quality":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Image Quality","description":"Lossy JPEG image recompression quality (1-100). Pro+ plan required.","example":85}},"type":"object","title":"CompressionOptions"},"ErrorResponse":{"properties":{"detail":{"type":"string","title":"Detail","description":"Error description details","example":"Invalid API key"}},"type":"object","required":["detail"],"title":"ErrorResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HtmlToPdfRequest":{"properties":{"html":{"type":"string","title":"Html","description":"Raw HTML markup to convert to PDF. HTML will be sanitized. Generated output is limited to 150 MB per file (contact support for more).","example":"<h1>My Invoice</h1><p>Description...</p>"},"webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Webhook Url","description":"Optional callback URL. PDFik will send a POST request with the job outcome.","example":"https://yourserver.com/webhooks/pdf"},"options":{"anyOf":[{"$ref":"#/components/schemas/PdfOptions"},{"type":"null"}],"description":"PDF styling and document options"},"render":{"anyOf":[{"$ref":"#/components/schemas/RenderOptions"},{"type":"null"}],"description":"Browser navigation/rendering options"},"test":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Test","description":"Test mode: the job runs through the full pipeline (statuses, webhook, download) but no rendering happens and the bundled sample PDF is returned by the download endpoint. Test jobs are FREE: they do not consume the PDF or data-volume quota. They are rate-limited separately (per-minute and per-day caps per account).","default":false,"example":false}},"type":"object","required":["html"],"title":"HtmlToPdfRequest"},"JobAuthOptions":{"properties":{"type":{"type":"string","title":"Type","description":"Authorization type: 'basic' or 'bearer'","example":"basic"},"value":{"type":"string","title":"Value","description":"Credentials value (username:password for basic, or raw token string for bearer)","example":"user:password"}},"type":"object","required":["type","value"],"title":"JobAuthOptions"},"JobCreatedResponse":{"properties":{"job_id":{"type":"string","title":"Job Id","description":"Unique identifier for the generated PDF job","example":"550e8400-e29b-41d4-a716-446655440000"},"status":{"type":"string","title":"Status","description":"Current status of the job: queued, rendering, uploading, done, failed","example":"queued"},"detail":{"type":"string","title":"Detail","description":"Informational message about job creation","example":"Job successfully sent to processing queue."}},"type":"object","required":["job_id","status","detail"],"title":"JobCreatedResponse"},"JobMetrics":{"properties":{"file_size_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"File Size Bytes","description":"Size of the generated PDF in bytes","example":1048576},"file_size_human":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File Size Human","description":"Human-readable file size","example":"1.00 MB"},"page_load_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Load Ms","description":"Browser page load time in milliseconds (navigation + wait_for_selector; excludes wait_after_load_ms)","example":1200},"processing_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Processing Ms","description":"PDFik processing time in milliseconds (PDF generation, watermark, compression, encryption, upload) — excludes page load and client-requested waits","example":650},"total_duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Duration Ms","description":"Total generation wall-clock time in milliseconds, including page load and client-requested waits","example":3200},"page_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Count","description":"Number of pages in the generated PDF","example":3}},"type":"object","title":"JobMetrics"},"JobStatusResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Current job status: queued, rendering, uploading, done, failed","example":"done"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"Timestamp when the job was created","example":"2026-06-14T19:11:03Z"},"finished_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Finished At","description":"Timestamp when the job was completed","example":"2026-06-14T19:11:06Z"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At","description":"ISO-8601 timestamp (UTC) after which the generated file is no longer downloadable (410). null until the job finishes.","example":"2026-06-15T19:11:06Z"},"test":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Test","description":"True when the job was submitted in test mode (no rendering; the bundled sample PDF is served).","example":false},"pages_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Pages Count","description":"Number of pages in the PDF","example":3},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Error code if the job failed. FILE_TOO_LARGE means the generated PDF exceeded the 150 MB per-file limit.","example":"SSRF_BLOCKED"},"metrics":{"anyOf":[{"$ref":"#/components/schemas/JobMetrics"},{"type":"null"}],"description":"Performance and size metrics for the job"}},"type":"object","required":["status"],"title":"JobStatusResponse"},"MarginOptions":{"properties":{"top":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Top","description":"Top margin (e.g. '10px', '20mm', '1in')","example":"10mm"},"right":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Right","description":"Right margin (e.g. '10px', '20mm', '1in')","example":"10mm"},"bottom":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bottom","description":"Bottom margin (e.g. '10px', '20mm', '1in')","example":"10mm"},"left":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Left","description":"Left margin (e.g. '10px', '20mm', '1in')","example":"10mm"}},"type":"object","title":"MarginOptions"},"PdfOptions":{"properties":{"format":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Format","description":"Paper format: A4, A3, Letter, Legal, Tabloid","default":"A4","example":"A4"},"landscape":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Landscape","description":"Use landscape orientation instead of portrait","default":false,"example":false},"margin":{"anyOf":[{"$ref":"#/components/schemas/MarginOptions"},{"type":"null"}],"description":"Margins for the PDF pages"},"print_background":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Print Background","description":"Render background colors and images from CSS","default":true,"example":true},"display_header_footer":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Display Header Footer","description":"Display header and footer templates","default":false,"example":false},"header_template":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"title":"Header Template","description":"HTML template for the header. Use class pageNumber, totalPages, date, title, url. Sanitized before rendering.","example":"<span class='title'>Page <span class='pageNumber'></span></span>"},"footer_template":{"anyOf":[{"type":"string","maxLength":10000},{"type":"null"}],"title":"Footer Template","description":"HTML template for the footer. Use class pageNumber, totalPages, date, title, url. Sanitized before rendering.","example":"<span style='font-size:10px;'>Page <span class='pageNumber'></span> of <span class='totalPages'></span></span>"},"watermark":{"anyOf":[{"$ref":"#/components/schemas/WatermarkOptions"},{"type":"null"}],"description":"Watermark configuration for the document. Starter+ plan required."},"user_password":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Password","description":"Encrypt PDF with a password. Pro+ plan required.","example":"secret123"},"compression":{"anyOf":[{"$ref":"#/components/schemas/CompressionOptions"},{"type":"null"}],"description":"PDF compression settings. Pro+ plan required."},"scale":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Scale","description":"Scale of the webpage rendering. Must be between 0.5 and 2.0. If omitted, it will be automatically calculated.","example":0.8}},"type":"object","title":"PdfOptions"},"RenderOptions":{"properties":{"page_load_timeout_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Load Timeout Ms","description":"Browser timeout for page load in milliseconds","example":30000},"wait_until":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Wait Until","description":"Event to wait for: 'load', 'domcontentloaded', 'networkidle', 'commit'","example":"load"},"wait_for_selector":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Wait For Selector","description":"CSS selector to wait for before rendering PDF","example":"#report-loaded"},"wait_after_load_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Wait After Load Ms","description":"Additional delay in milliseconds to wait after the load event (0 to 10000 ms)","example":0}},"type":"object","title":"RenderOptions"},"UrlToPdfRequest":{"properties":{"url":{"type":"string","title":"Url","description":"Public URL of the web page to convert to PDF. Private IPs are blocked. Generated output is limited to 150 MB per file (contact support for more).","example":"https://example.com"},"webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Webhook Url","description":"Optional callback URL. PDFik will send a POST request with the job outcome.","example":"https://yourserver.com/webhooks/pdf"},"options":{"anyOf":[{"$ref":"#/components/schemas/PdfOptions"},{"type":"null"}],"description":"PDF styling and document options"},"render":{"anyOf":[{"$ref":"#/components/schemas/RenderOptions"},{"type":"null"}],"description":"Browser navigation/rendering options"},"auth":{"anyOf":[{"$ref":"#/components/schemas/JobAuthOptions"},{"type":"null"}],"description":"Authorization options for Pro+ plans"},"test":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Test","description":"Test mode: the job runs through the full pipeline (statuses, webhook, download) but no rendering happens and the bundled sample PDF is returned by the download endpoint. Test jobs are FREE: they do not consume the PDF or data-volume quota. They are rate-limited separately (per-minute and per-day caps per account).","default":false,"example":false}},"type":"object","required":["url"],"title":"UrlToPdfRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WatermarkOptions":{"properties":{"text":{"type":"string","title":"Text","description":"Watermark text to render on all pages","example":"CONFIDENTIAL"},"color":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Color","description":"CSS color representation for the watermark text","default":"rgba(200, 200, 200, 0.3)","example":"rgba(255, 0, 0, 0.2)"},"font_size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Font Size","description":"CSS font size for the watermark text","default":"60px","example":"48px"},"rotation_degrees":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rotation Degrees","description":"Angle of watermark rotation in degrees","default":-45,"example":-30}},"type":"object","required":["text"],"title":"WatermarkOptions"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"tags":[{"name":"PDF Tasks","description":"Endpoints for generating PDF files from URLs or HTML templates."},{"name":"Jobs","description":"Endpoints for tracking job progress and downloading generated PDF files."}]}