TryDocify API guide

Quickstart

Send a document to POST /api/v1/generate with your key in the X-API-Key header. The response body is the PDF.

curl -X POST https://api.trydocify.com/api/v1/generate \
  -H "X-API-Key: $TRYDOCIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Invoice #1042",
    "header": { "left": "Acme Studio", "right": "INV-1042" },
    "blocks": [
      { "type": "keyValue", "items": [{ "key": "Billed to", "value": "Globex Corp." }] },
      { "type": "table",
        "columns": [{ "header": "Item" }, { "header": "Amount", "align": "right" }],
        "rows": [["Design audit", "$1,200.00"], ["Component library", "$2,550.00"]],
        "footer": [["Total", "$3,750.00"]] }
    ]
  }' \
  --output invoice.pdf

Authentication

Every request to /api/v1/generate, /api/v1/usage, /api/v1/keys/rotate and /api/v1/billing/portal needs your secret key in the X-API-Key header. Keys start with dfy_live_ and are shown exactly once, right after checkout.

• Keep keys server-side. Never ship them in browser or mobile bundles.
• We store only an HMAC-SHA256 hash of your key, so we can't show it to you again. Rotate it if it leaks.
• All traffic must use HTTPS.

Generate a PDF

POST/api/v1/generate

Success returns 200 with Content-Type: application/pdf and Content-Disposition: attachment. Useful response headers:

Prefer JSON? Send Accept: application/json and the PDF comes back base64-encoded in data, alongside fileName, sizeBytes, pageCount, creditsRemaining and renderTimeMs. This is handy for no-code tools and queues.

Each successful PDF costs one credit. Validation errors, render failures and rejected requests are free: a credit is reserved atomically before rendering and refunded if anything goes wrong.

Test mode

Add "test": true to any document while you build your integration. The PDF is rendered exactly as it would be in production, with a TEST watermark on every page, and it doesn't use a credit.

curl -X POST https://api.trydocify.com/api/v1/generate \
  -H "X-API-Key: $TRYDOCIFY_API_KEY" -H "Content-Type: application/json" \
  -d '{ "test": true, "title": "Invoice #1042", "blocks": [{ "type": "paragraph", "text": "Layout check" }] }' \
  -o test.pdf

• Each key gets 200 test renders per day, reset at 00:00 UTC. After that, test requests return 429 test_limit_reached.
• Test responses carry X-Docify-Test: true and X-Test-Renders-Remaining. With Accept: application/json, the envelope has test and testRendersRemaining.
• Test mode works while your subscription is active, even when this period's credits are used up.
• To go live, remove the flag. No key change is needed.

Document schema

The request body is a single document object:

Field names are camelCase; enum values are case-insensitive. Wherever a string is expected, numbers and booleans are accepted and rendered exactly as written, so ["Widget", 2, 19.90] is a valid table row.

Blocks

Each block has a type discriminator, which may appear anywhere in the object. Unknown types are rejected with invalid_json.

{ "type": "heading", "text": "Summary", "level": 2 }

{ "type": "paragraph", "text": "Thanks for your order.\nSee you soon.", "align": "justify" }

{ "type": "list", "ordered": true, "items": ["Sign", "Return"] }

{ "type": "keyValue", "columns": 2, "items": [{ "key": "Order", "value": "#5531" }] }

{ "type": "table", "columns": [{ "header": "Item", "width": 4 }, { "header": "Qty", "align": "right" }], "rows": [["Widget", 2]], "footer": [["Total", 2]] }

{ "type": "note", "tone": "warning", "title": "Due soon", "text": "Payment due in 7 days." }

{ "type": "image", "src": "data:image/png;base64,iVBORw0KG…", "width": 120 }

{ "type": "divider" }

{ "type": "spacer", "height": 24 }

{ "type": "pageBreak" }

Tables flow across pages and repeat their header row. footer rows are emphasized and the last one is styled as a grand total. Images must be inline base64 PNG, JPEG or WebP data URIs (max 2 MB each). Remote URLs aren't fetched, which keeps renders fast and deterministic.

Usage & credits

GET/api/v1/usage

Returns your plan, remaining credits, the current period and request statistics. Statistics lag live traffic by a second or two; the credit counters are exact.

{
  "apiKey": { "prefix": "dfy_live_Ab3x", "status": "active", "createdAt": "2026-10-01T09:12:44Z", "lastUsedAt": "2026-10-26T18:03:10Z" },
  "plan": { "code": "pro", "name": "Pro", "monthlyQuota": 10000 },
  "credits": { "limit": 10000, "used": 1342, "remaining": 8658 },
  "period": { "start": "2026-10-01T09:12:44Z", "end": "2026-11-01T09:12:44Z" },
  "testMode": { "dailyLimit": 200, "usedToday": 14, "remaining": 186, "resetsAt": "2026-10-27T00:00:00Z" },
  "stats": {
    "last24Hours": { "requests": 226, "succeeded": 223, "failed": 3, "creditsCharged": 209, "testRenders": 14 },
    "currentPeriod": { "requests": 1471, "succeeded": 1453, "failed": 18, "creditsCharged": 1342, "testRenders": 111 },
    "daily": [{ "date": "2026-10-26", "requests": 212, "creditsCharged": 209 }]
  }
}

Rotating keys

POST/api/v1/keys/rotate

Issues a new secret and invalidates the current one immediately. Plan, credits and history are kept. The response contains apiKey (shown once), prefix and rotatedAt.

Billing

POST/api/v1/billing/portal

Returns a short-lived Paddle customer portal url. Open it to switch between Starter and Pro, update your payment method, download invoices or cancel. Upgrades apply instantly. Credits reset at the start of each billing period.

Errors

Errors are RFC 9457 problem documents with a stable machine-readable code and a traceId for support.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://trydocify.com/docs#error-validation-failed",
  "title": "The document payload is invalid.",
  "status": 400,
  "detail": "One or more fields failed validation. See 'errors' for details.",
  "code": "validation_failed",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "errors": { "blocks[1].rows[3]": ["Each row must have exactly 4 cells (one per column)."] }
}

Limits

When you exceed the rate limit you get 429 with a Retry-After header. Back off and retry.

AI assistants

Using Claude Code, Cursor, Copilot or another AI coding assistant? Give it our instructions file. It covers the whole API (schema, every block, errors and limits) and the rules for a safe integration: key on the server, test mode while developing, retries on 429 and 503.

curl -o docs/TRYDOCIFY.md https://trydocify.com/trydocify.md

Then reference it from your assistant's instructions, for example a line in CLAUDE.md or AGENTS.md: For PDF generation, follow docs/TRYDOCIFY.md. The same content is available as llms-full.txt, and the machine-readable API is at openapi.json.