{"openapi":"3.1.0","info":{"title":"PDFOven","version":"0.1.0","description":"PDF and image generation API. Send HTML, Markdown, a public URL, or JSON into a Handlebars template and get a Chromium-rendered PDF, PNG or JPEG back.","contact":{"name":"PDFOven support","email":"support@pdfoven.com"},"termsOfService":"https://pdfoven.com/terms","x-logo":{"url":"https://pdfoven.com/logo.png"}},"externalDocs":{"description":"PDFOven API documentation","url":"https://pdfoven.com/docs"},"servers":[{"url":"https://pdfoven.com"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"tags":[{"name":"Render","description":"Render PDFs and images."},{"name":"Templates","description":"Manage saved Handlebars templates."},{"name":"Usage","description":"Plan and monthly usage."}],"paths":{"/v1/pdf":{"post":{"operationId":"renderPdf","summary":"Render a PDF","description":"Renders a PDF from html, markdown, url, an inline Handlebars template, or a saved or built-in template.","tags":["Render"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenderRequest"}}}},"responses":{"200":{"description":"The rendered file, or a JSON envelope when response is \"base64\".","headers":{"X-Render-Ms":{"description":"Render time in milliseconds.","schema":{"type":"integer"}},"X-Usage-Remaining":{"description":"Renders left this calendar month.","schema":{"type":"integer"}},"Content-Disposition":{"description":"Inline disposition with the requested filename.","schema":{"type":"string"}}},"content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"$ref":"#/components/schemas/Base64Response"}}}},"400":{"description":"invalid_request: the body is not valid JSON or failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"template_not_found: template_id does not match a saved or built-in template.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"template_error or render_failed (blocked URL, timeout, HTTP error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"quota_exceeded: the monthly render limit is reached. Failed renders do not count.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error: the render failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/image":{"post":{"operationId":"renderImage","summary":"Render an image","description":"Takes the same sources as /v1/pdf and returns a PNG, or a JPEG with type=jpeg.","tags":["Render"],"parameters":[{"name":"type","in":"query","required":false,"description":"Set to jpeg for a JPEG. Any other value returns a PNG.","schema":{"type":"string","enum":["png","jpeg"],"default":"png"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenderRequest"}}}},"responses":{"200":{"description":"The rendered file, or a JSON envelope when response is \"base64\".","headers":{"X-Render-Ms":{"description":"Render time in milliseconds.","schema":{"type":"integer"}},"X-Usage-Remaining":{"description":"Renders left this calendar month.","schema":{"type":"integer"}},"Content-Disposition":{"description":"Inline disposition with the requested filename.","schema":{"type":"string"}}},"content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"$ref":"#/components/schemas/Base64Response"}}}},"400":{"description":"invalid_request: the body is not valid JSON or failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"template_not_found: template_id does not match a saved or built-in template.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"template_error or render_failed (blocked URL, timeout, HTTP error).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"quota_exceeded: the monthly render limit is reached. Failed renders do not count.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"internal_error: the render failed unexpectedly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/templates":{"get":{"operationId":"listTemplates","summary":"List templates","description":"Lists your saved templates.","tags":["Templates"],"responses":{"200":{"description":"Your templates.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateList"}}}},"401":{"description":"unauthorized: missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createTemplate","summary":"Create a template","description":"Saves a Handlebars or Markdown template.","tags":["Templates"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateInput"}}}},"responses":{"201":{"description":"The created template.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateCreated"}}}},"400":{"description":"invalid_request: the body is not valid JSON or failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"template_limit: your plan's template limit is reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/usage":{"get":{"operationId":"getUsage","summary":"Get usage","description":"Returns your plan, limit and renders used this calendar month (UTC).","tags":["Usage"],"responses":{"200":{"description":"Current usage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"description":"unauthorized: missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Send your API key as Authorization: Bearer po_live_…. Keys are created in the dashboard."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Alternative to the bearer token."}},"schemas":{"RenderRequest":{"type":"object","properties":{"html":{"type":"string","maxLength":5000000},"url":{"type":"string","maxLength":4000,"format":"uri"},"markdown":{"type":"string","maxLength":2000000},"template_id":{"type":"string","maxLength":64},"template":{"type":"string","maxLength":2000000},"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"css":{"type":"string","maxLength":500000},"options":{"type":"object","properties":{"format":{"type":"string","enum":["A3","A4","A5","Letter","Legal","Tabloid"]},"landscape":{"type":"boolean"},"margin":{"type":"string","pattern":"^\\d+(\\.\\d+)?(px|in|cm|mm)?$"},"print_background":{"type":"boolean"},"header_template":{"type":"string","maxLength":20000},"footer_template":{"type":"string","maxLength":20000},"scale":{"type":"number","minimum":0.1,"maximum":2},"width":{"type":"integer","minimum":16,"maximum":4000},"height":{"type":"integer","minimum":16,"maximum":4000},"full_page":{"type":"boolean"},"device_scale_factor":{"type":"number","minimum":1,"maximum":3},"quality":{"type":"integer","minimum":1,"maximum":100}},"additionalProperties":false},"wait_for_selector":{"type":"string","maxLength":500},"timeout_ms":{"type":"integer","minimum":1000,"maximum":60000},"response":{"type":"string","enum":["binary","base64"]},"filename":{"type":"string","maxLength":200,"pattern":"^[\\w.\\- ]+$"}},"additionalProperties":false,"description":"Provide exactly one source: html, markdown, url, template, or template_id. data fills a Handlebars template or saved template.","oneOf":[{"required":["html"]},{"required":["markdown"]},{"required":["url"]},{"required":["template"]},{"required":["template_id"]}]},"TemplateInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"engine":{"default":"handlebars","type":"string","enum":["handlebars","markdown"]},"content":{"type":"string","maxLength":2000000},"css":{"default":"","type":"string","maxLength":500000},"sample_data":{"default":{},"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"page_options":{"default":{},"type":"object","properties":{"format":{"type":"string"},"landscape":{"type":"boolean"},"margin":{"type":"string"},"printBackground":{"type":"boolean"}}}},"required":["name","content"],"additionalProperties":false},"Base64Response":{"type":"object","required":["data","content_type","bytes"],"properties":{"data":{"type":"string","format":"byte","description":"Base64-encoded file."},"content_type":{"type":"string","examples":["application/pdf"]},"bytes":{"type":"integer","description":"Size of the decoded file in bytes."}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","unauthorized","template_limit","template_not_found","template_error","render_failed","quota_exceeded","internal_error"]},"message":{"type":"string"}}}}},"TemplateSummary":{"type":"object","required":["id","name","engine","sample_data","page_options","updated_at"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"engine":{"type":"string","enum":["handlebars","markdown"]},"sample_data":{"type":"object","additionalProperties":true},"page_options":{"type":"object","additionalProperties":true},"updated_at":{"type":"string"}}},"TemplateList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TemplateSummary"}}}},"TemplateCreated":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"Usage":{"type":"object","required":["plan","period","used","limit"],"properties":{"plan":{"type":"string"},"period":{"type":"string","description":"Calendar month in UTC, YYYY-MM.","examples":["2026-10"]},"used":{"type":"integer"},"limit":{"type":"integer"}}}}}}