{"openapi":"3.1.1","info":{"title":"TryDocify API","description":"The cleanest JSON-to-PDF API. Describe a document as JSON (headings, paragraphs, tables, key/value grids, notes, images) and get a professionally typeset PDF back in milliseconds.\n\nAuthenticate every request with the `X-API-Key` header. Errors use RFC 9457 problem details with a stable `code` field.","version":"v1"},"servers":[{"url":"https://api.trydocify.com","description":"Production"}],"paths":{"/api/v1/generate":{"post":{"tags":["Documents"],"summary":"Generate a PDF from JSON","description":"Renders the document described by the JSON body and returns the PDF bytes. Send `Accept: application/json` to receive the PDF base64-encoded in a JSON envelope instead. Each successful render costs 1 credit; failed or rejected requests are never charged. Set `\"test\": true` in the body for a free, watermarked test render (limited per key per day).","operationId":"GeneratePdf","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateJsonResponse"}}}},"400":{"description":"Bad Request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"402":{"description":"Payment Required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"Forbidden","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"413":{"description":"Payload Too Large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"422":{"description":"Unprocessable Entity","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Too Many Requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Service Unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}},"security":[{"ApiKey":[]}]}},"/api/v1/usage":{"get":{"tags":["Account"],"summary":"Remaining credits and usage statistics","description":"Returns the plan, remaining credits, current billing period, today's test renders and request statistics for the calling API key. Statistics lag a second or two behind live traffic.","operationId":"GetUsage","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Too Many Requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}},"security":[{"ApiKey":[]}]}},"/api/v1/keys/rotate":{"post":{"tags":["Account"],"summary":"Rotate the calling API key","description":"Issues a new secret for this key and invalidates the current one immediately. Credits, plan and history are kept. The new key is returned once — store it securely.","operationId":"RotateApiKey","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotateKeyResponse"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}},"security":[{"ApiKey":[]}]}},"/api/v1/billing/portal":{"post":{"tags":["Billing"],"summary":"Open the billing portal","description":"Returns a short-lived Paddle customer portal URL where the key owner can change plans, update payment details, download invoices or cancel.","operationId":"CreateBillingPortalSession","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalResponse"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"502":{"description":"Bad Gateway","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"503":{"description":"Service Unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}},"security":[{"ApiKey":[]}]}}},"components":{"schemas":{"Block":{"required":["type"],"type":"object","anyOf":[{"$ref":"#/components/schemas/BlockHeadingBlock"},{"$ref":"#/components/schemas/BlockParagraphBlock"},{"$ref":"#/components/schemas/BlockListBlock"},{"$ref":"#/components/schemas/BlockKeyValueBlock"},{"$ref":"#/components/schemas/BlockTableBlock"},{"$ref":"#/components/schemas/BlockNoteBlock"},{"$ref":"#/components/schemas/BlockImageBlock"},{"$ref":"#/components/schemas/BlockDividerBlock"},{"$ref":"#/components/schemas/BlockSpacerBlock"},{"$ref":"#/components/schemas/BlockPageBreakBlock"}],"discriminator":{"propertyName":"type","mapping":{"heading":"#/components/schemas/BlockHeadingBlock","paragraph":"#/components/schemas/BlockParagraphBlock","list":"#/components/schemas/BlockListBlock","keyValue":"#/components/schemas/BlockKeyValueBlock","table":"#/components/schemas/BlockTableBlock","note":"#/components/schemas/BlockNoteBlock","image":"#/components/schemas/BlockImageBlock","divider":"#/components/schemas/BlockDividerBlock","spacer":"#/components/schemas/BlockSpacerBlock","pageBreak":"#/components/schemas/BlockPageBreakBlock"}}},"BlockDividerBlock":{"properties":{"type":{"enum":["divider"],"type":"string"}}},"BlockHeadingBlock":{"properties":{"type":{"enum":["heading"],"type":"string"},"text":{},"level":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"1 (largest) to 3. Default 1.","format":"int32"}}},"BlockImageBlock":{"properties":{"type":{"enum":["image"],"type":"string"},"src":{"description":"Base64 data URI: data:image/png|jpeg|webp;base64,… (max 2 MB decoded). Remote URLs are not fetched."},"width":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$","type":["null","number","string"],"description":"Width in points. Defaults to the full content width.","format":"float"},"align":{"$ref":"#/components/schemas/TextAlignment"}}},"BlockKeyValueBlock":{"properties":{"type":{"enum":["keyValue"],"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/KeyValueItem"}},"columns":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"Number of key/value pairs per row, 1–3. Default 1.","format":"int32"}}},"BlockListBlock":{"properties":{"type":{"enum":["list"],"type":"string"},"items":{"type":"array"},"ordered":{"type":"boolean"}}},"BlockNoteBlock":{"properties":{"type":{"enum":["note"],"type":"string"},"title":{},"text":{},"tone":{"$ref":"#/components/schemas/NoteTone"}}},"BlockPageBreakBlock":{"properties":{"type":{"enum":["pageBreak"],"type":"string"}}},"BlockParagraphBlock":{"properties":{"type":{"enum":["paragraph"],"type":"string"},"text":{"description":"Plain text. Line breaks (\\n) are preserved."},"align":{"$ref":"#/components/schemas/TextAlignment"},"bold":{"type":"boolean"},"italic":{"type":"boolean"},"muted":{"type":"boolean"}}},"BlockSpacerBlock":{"properties":{"type":{"enum":["spacer"],"type":"string"},"height":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$","type":["number","string"],"description":"Height in points, 1–400. Default 12.","format":"float"}}},"BlockTableBlock":{"properties":{"type":{"enum":["table"],"type":"string"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/TableColumn"}},"rows":{"type":"array","items":{"type":"array"},"description":"Rows of cells. Numbers and booleans are accepted and rendered as written."},"footer":{"type":["null","array"],"items":{},"description":"Optional emphasized rows after the body, e.g. subtotal / tax / total."},"striped":{"type":"boolean"}}},"DocumentInfo":{"type":"object","properties":{"author":{},"subject":{},"keywords":{}}},"DocumentRequest":{"type":"object","properties":{"fileName":{"description":"Download file name. Sanitized; '.pdf' is appended when missing. Defaults to 'document.pdf'."},"title":{"description":"Large title rendered at the top of the first page. Also used as the PDF title metadata."},"subtitle":{"description":"Muted line rendered below the title."},"pageSize":{"$ref":"#/components/schemas/PageSizeOption"},"orientation":{"$ref":"#/components/schemas/PageOrientation"},"theme":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/DocumentTheme"}]},"info":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/DocumentInfo"}]},"header":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/PageHeader"}]},"footer":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/PageFooter"}]},"blocks":{"type":"array","items":{"$ref":"#/components/schemas/Block"},"description":"Content blocks rendered top to bottom. Each block has a 'type' discriminator."},"test":{"type":"boolean","description":"Test mode: the PDF is watermarked \"TEST\" and costs no credit. Limited per key per day (see /api/v1/usage). Default false."}},"description":"A document to render: page setup, optional running header/footer and a list of content blocks."},"DocumentTheme":{"type":"object","properties":{"accentColor":{"description":"Hex color (#RRGGBB) for headings, table headers and accents. Default #111111."},"textColor":{"description":"Hex color (#RRGGBB) for body text. Default #1F1F1F."},"fontSize":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$","type":["null","number","string"],"description":"Base font size in points, 7–16. Default 10.","format":"float"},"margin":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$","type":["null","number","string"],"description":"Page margin in points (72 pt = 1 inch), 18–108. Default 48.","format":"float"}}},"GenerateJsonResponse":{"required":["fileName","contentType","sizeBytes","pageCount","creditsRemaining","renderTimeMs","test","testRendersRemaining","data"],"type":"object","properties":{"fileName":{},"contentType":{},"sizeBytes":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"pageCount":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"format":"int32"},"creditsRemaining":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"renderTimeMs":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$","type":["number","string"],"format":"double"},"test":{"type":"boolean"},"testRendersRemaining":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"format":"int32"},"data":{}}},"KeyValueItem":{"type":"object","properties":{"key":{},"value":{}}},"NoteTone":{"enum":["info","success","warning","danger"]},"PageFooter":{"type":"object","properties":{"text":{},"showPageNumbers":{"type":"boolean"}}},"PageHeader":{"type":"object","properties":{"left":{"description":"Text on the left of every page header, e.g. a company name."},"right":{"description":"Text on the right of every page header, e.g. a date or reference."}}},"PageOrientation":{"enum":["portrait","landscape"]},"PageSizeOption":{"enum":["a3","a4","a5","letter","legal"]},"PortalResponse":{"required":["url"],"type":"object","properties":{"url":{}}},"ProblemDetails":{"type":"object","properties":{"type":{},"title":{},"status":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"format":"int32"},"detail":{},"instance":{}}},"RotateKeyResponse":{"required":["apiKey","prefix","rotatedAt"],"type":"object","properties":{"apiKey":{},"prefix":{},"rotatedAt":{"type":"string","format":"date-time"}}},"TableColumn":{"type":"object","properties":{"header":{},"align":{"$ref":"#/components/schemas/TextAlignment"},"width":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?(?:[eE][+-]?\\d+)?$","type":["number","string"],"description":"Relative width, 1–12. Default 1.","format":"float"}}},"TextAlignment":{"enum":["left","center","right","justify"]},"UsageCredits":{"required":["limit","used","remaining"],"type":"object","properties":{"limit":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"used":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"remaining":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"}}},"UsageDay":{"required":["date","requests","creditsCharged"],"type":"object","properties":{"date":{"type":"string","format":"date"},"requests":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"creditsCharged":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"}}},"UsageKeyInfo":{"required":["prefix","status","createdAt","lastUsedAt"],"type":"object","properties":{"prefix":{},"status":{},"createdAt":{"type":"string","format":"date-time"},"lastUsedAt":{"type":["null","string"],"format":"date-time"}}},"UsagePeriod":{"required":["start","end"],"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"UsagePlanInfo":{"required":["code","name","monthlyQuota"],"type":"object","properties":{"code":{},"name":{},"monthlyQuota":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"}}},"UsageResponse":{"required":["apiKey","plan","credits","period","testMode","stats"],"type":"object","properties":{"apiKey":{"$ref":"#/components/schemas/UsageKeyInfo"},"plan":{"$ref":"#/components/schemas/UsagePlanInfo"},"credits":{"$ref":"#/components/schemas/UsageCredits"},"period":{"$ref":"#/components/schemas/UsagePeriod"},"testMode":{"$ref":"#/components/schemas/UsageTestMode"},"stats":{"$ref":"#/components/schemas/UsageStats"}}},"UsageStats":{"required":["last24Hours","currentPeriod","daily"],"type":"object","properties":{"last24Hours":{"$ref":"#/components/schemas/UsageWindowStats"},"currentPeriod":{"$ref":"#/components/schemas/UsageWindowStats"},"daily":{"type":"array","items":{"$ref":"#/components/schemas/UsageDay"}}}},"UsageTestMode":{"required":["dailyLimit","usedToday","remaining","resetsAt"],"type":"object","properties":{"dailyLimit":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"usedToday":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"remaining":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"resetsAt":{"type":"string","format":"date-time"}}},"UsageWindowStats":{"required":["requests","succeeded","failed","creditsCharged","testRenders"],"type":"object","properties":{"requests":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"succeeded":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"failed":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"creditsCharged":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"testRenders":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"}}}},"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Your secret API key (starts with `dfy_`). Shown once after checkout.","name":"X-API-Key","in":"header"}}},"tags":[{"name":"Documents"},{"name":"Account"},{"name":"Billing"}]}