{"openapi":"3.1.0","info":{"title":"Docspout API","version":"1.0.0","description":"Render PDFs from JSON with published templates. One document is one successful PDF rendered with a live key; failures, previews, and test keys are free.","contact":{"email":"support@docspout.com"}},"servers":[{"url":"https://docspout.com/v1"}],"security":[{"bearer":[]}],"tags":[{"name":"Renders"},{"name":"Batches"},{"name":"Templates"},{"name":"Account"}],"paths":{"/renders":{"post":{"tags":["Renders"],"operationId":"createRender","summary":"Render one PDF","description":"Waits up to 10 seconds for the PDF by default (`wait: true`). With `output: \"pdf\"` the response body is the PDF itself.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retries with the same key and body return the original result and never count twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenderRequest"}}}},"responses":{"200":{"description":"Finished render (or the PDF bytes with output=pdf).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Render"}},"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"202":{"description":"Accepted and still rendering. Poll GET /renders/{id} or use webhook_url.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Render"}}}},"400":{"description":"Invalid request. `error.paths` lists the offending fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan limit reached (150% of monthly volume).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency-Key reused with a different body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body too large: 5 MB for renders, 50 MB for batches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The render failed; `error` says why (missing_field, wrong_type, asset_failed, ...). Failed renders are free.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Render"}}}},"429":{"description":"Rate limited. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/renders/{id}":{"get":{"tags":["Renders"],"operationId":"getRender","summary":"Get a render","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"rnd_Jf5NFXP1SgsMgCcN4542wC"}],"responses":{"200":{"description":"The render.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Render"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/batches":{"post":{"tags":["Batches"],"operationId":"createBatch","summary":"Render many PDFs from rows","description":"Up to 10,000 rows (plan limits apply). Batches resume after crashes; finished rows are never rendered twice.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Retries with the same key and body return the original result and never count twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchRequest"}}}},"responses":{"202":{"description":"Accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"400":{"description":"Invalid request. `error.paths` lists the offending fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan limit reached (150% of monthly volume).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency-Key reused with a different body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body too large: 5 MB for renders, 50 MB for batches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/batches/{id}":{"get":{"tags":["Batches"],"operationId":"getBatch","summary":"Get a batch with counts","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"bat_tkFAJXB5Z8GZEe9qjJq190"}],"responses":{"200":{"description":"The batch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/batches/{id}/renders":{"get":{"tags":["Batches"],"operationId":"listBatchRenders","summary":"List a batch's renders by row","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"bat_tkFAJXB5Z8GZEe9qjJq190"},{"name":"state","in":"query","schema":{"type":"string","enum":["queued","rendering","succeeded","failed"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"after_row","in":"query","schema":{"type":"integer","minimum":-1,"default":-1},"description":"Cursor: pass next_after_row from the previous page."}],"responses":{"200":{"description":"A page of renders.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Render"}},"next_after_row":{"type":["integer","null"]}},"required":["data","next_after_row"]}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/batches/{id}/retry":{"post":{"tags":["Batches"],"operationId":"retryBatch","summary":"Retry failed rows, optionally with corrected data","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"bat_tkFAJXB5Z8GZEe9qjJq190"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchRetryRequest"}}}},"responses":{"200":{"description":"Rows queued again.","content":{"application/json":{"schema":{"type":"object","properties":{"requeued":{"type":"integer"}},"required":["requeued"]}}}},"400":{"description":"Invalid request. `error.paths` lists the offending fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Plan limit reached (150% of monthly volume).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency-Key reused with a different body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body too large: 5 MB for renders, 50 MB for batches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. See Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/batches/{id}/cancel":{"post":{"tags":["Batches"],"operationId":"cancelBatch","summary":"Cancel the rows not yet rendered","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"bat_tkFAJXB5Z8GZEe9qjJq190"}],"responses":{"200":{"description":"The canceled batch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/batches/{id}/zip":{"get":{"tags":["Batches"],"operationId":"downloadBatchZip","summary":"Download every finished PDF as one ZIP","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"bat_tkFAJXB5Z8GZEe9qjJq190"}],"responses":{"200":{"description":"ZIP stream.","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/templates":{"get":{"tags":["Templates"],"operationId":"listTemplates","summary":"List published templates","responses":{"200":{"description":"Templates.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"version":{"type":["integer","null"]}}}}}}}}}}}},"/templates/{id}":{"get":{"tags":["Templates"],"operationId":"getTemplate","summary":"Get a template's fields (JSON Schema) and sample data","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"tpl_HPxQmBxC13qNbWGWMkC4w6"}],"responses":{"200":{"description":"The template.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"version":{"type":"integer"},"fields":{"type":"object","description":"JSON Schema of the data the template expects."},"sample":{}}}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/usage":{"get":{"tags":["Account"],"operationId":"getUsage","summary":"Documents used this month","responses":{"200":{"description":"Usage.","content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string","enum":["free","starter","pro","business"]},"used":{"type":"integer"},"limit":{"type":"integer"},"soft_cap":{"type":"integer"}},"required":["plan","used","limit","soft_cap"]}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"sk_live_… or sk_test_… from the dashboard. Test keys are free and watermark the PDF."}},"schemas":{"RenderRequest":{"type":"object","properties":{"template":{"type":"string","minLength":1},"version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"data":{"description":"Any JSON value"},"output":{"default":"url","type":"string","enum":["url","pdf"]},"filename":{"type":"string","maxLength":200},"wait":{"default":true,"type":"boolean"},"webhook_url":{"type":"string","format":"uri"},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":40},"additionalProperties":{"type":"string","maxLength":500}}},"required":["template","data"]},"BatchRequest":{"type":"object","properties":{"template":{"type":"string","minLength":1},"version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"rows":{"minItems":1,"maxItems":10000,"type":"array","items":{"description":"Any JSON value"}},"filename_pattern":{"type":"string","maxLength":200},"webhook_url":{"type":"string","format":"uri"}},"required":["template","rows"]},"BatchRetryRequest":{"type":"object","properties":{"rows":{"default":[],"maxItems":10000,"type":"array","items":{"type":"object","properties":{"row":{"type":"integer","minimum":0,"maximum":9007199254740991},"data":{"description":"Any JSON value"}},"required":["row","data"]}}}},"RenderError":{"type":"object","properties":{"code":{"type":"string","enum":["missing_field","wrong_type","asset_failed","too_many_pages","engine_error","timeout","worker_lost","canceled"]},"message":{"type":"string"},"paths":{"type":"array","items":{"type":"string"}}},"required":["code","message"]},"Render":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","rendering","succeeded","failed"]},"template":{"type":"object","properties":{"id":{"type":"string"},"version":{"type":"integer"}},"required":["id","version"]},"mode":{"type":"string","enum":["live","test"]},"url":{"type":["string","null"],"format":"uri"},"expires_at":{"type":["string","null"],"format":"date-time"},"pages":{"type":["integer","null"]},"duration_ms":{"type":["integer","null"]},"error":{"oneOf":[{"$ref":"#/components/schemas/RenderError"},{"type":"null"}]},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"const":"unused_field"},"path":{"type":"string"}}}},"batch":{"oneOf":[{"type":"object","properties":{"id":{"type":"string"},"row":{"type":"integer"}}},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"created_at":{"type":"string","format":"date-time"}},"required":["id","status","template","mode","url","error","created_at"]},"Batch":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["running","completed","completed_with_errors","canceled"]},"template":{"type":"object","properties":{"id":{"type":"string"},"version":{"type":"integer"}}},"total":{"type":"integer"},"counts":{"type":"object","properties":{"queued":{"type":"integer"},"rendering":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"}}},"created_at":{"type":"string","format":"date-time"}},"required":["id","status","total","counts","created_at"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"paths":{"type":"array","items":{"type":"string"}}},"required":["code","message"]}},"required":["error"]}}}}