# DocJet

> DocJet is a PDF and image generation API for AI agents and automation builders. Send a template ID (or raw HTML) plus JSON data to https://api.docjet.dev/v1/render with an Authorization: Bearer <api_key> header; receive a branded PDF or PNG. Free tier signup: POST /v1/signup with {"email":"..."}.

## API at a glance (everything needed to make a call)

Base URL: `https://api.docjet.dev`

Authentication: HTTP header `Authorization: Bearer <api_key>` on every `/v1/*` request except `POST /v1/signup` and `GET /v1/templates`. API keys start with `binfra_`.

Get a free API key (100 renders/month, no card):

```
curl -X POST https://api.docjet.dev/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'
```

Returns `{"apiKey":"binfra_...","tier":"free","message":"..."}` — the key is shown only once.

Try it instantly with the public demo key (no signup; rate-limited to 3 req/min, 50 renders/month, shared):

```
curl -X POST https://api.docjet.dev/v1/render \
  -H "Authorization: Bearer binfra_9afb57dbb6478c441ad101129fca65847f5745403f9d718b3de6d934c9b63f88" \
  -H "Content-Type: application/json" \
  -d '{"html":"<h1>Hello from DocJet</h1>"}' \
  --output hello.pdf
```

### POST /v1/render — render a PDF

Request body (JSON), exactly one of `template_id` or `html`:

- `{"template_id": "<id from GET /v1/templates>", "data": { ...Handlebars variables... }}`
- `{"html": "<raw HTML, max 512 KB>", "data": { ...optional variables... }}`
- Optional in both shapes: `"webhook_url": "https://..."` for async delivery (HTTPS only).

Response: PDF binary by default. Append `?response=url` to get JSON `{"url":"<signed download URL>"}` instead, or `?response=json` for base64.

### POST /v1/image — render a PNG

Same request body and `?response=` query as `/v1/render`. Returns PNG binary by default. Image dimensions come from the template (e.g. `og-blog` is 1200x630).

### Other endpoints

- `GET /v1/templates` — public template catalog `[{id, name, description, outputType}]`. No auth required.
- `GET /v1/keys/usage` — current-period usage `{tier, quota, used, remaining, period}`. Auth required.
- `GET /v1/keys/webhook-secret` — webhook signing secret for `X-DocJet-Signature` verification. Auth required.
- `POST /v1/billing/checkout` — body `{"plan":"starter"|"pro"|"business"}`, returns `{url}` (Stripe Checkout). Auth required.

### Errors

All errors are JSON `{"error": "...", "code": "...", "hint": "..."}`. Codes: `AUTH_INVALID` (401), `PAYLOAD_INVALID` (422), `TEMPLATE_NOT_FOUND` (404), `RATE_LIMITED` (429), `QUOTA_EXCEEDED` (429), `CONCURRENCY_EXCEEDED` (429), `INTERNAL_ERROR` (500).

### Webhooks

Async render callbacks are signed: header `X-DocJet-Signature: t=<unix-seconds>,v1=<hex>` where `v1 = HMAC-SHA256("<t>.<rawBody>", webhook_secret)`. Verify with a timing-safe comparison and a 300-second replay window (the `docjet` npm and PyPI SDKs ship `verifyWebhookSignature` / `verify_webhook_signature` helpers).


## Documentation Sets

- [Abridged documentation](https://docjet.dev/llms-small.txt): a compact version of the documentation for DocJet, with non-essential content removed
- [Complete documentation](https://docjet.dev/llms-full.txt): the full documentation for DocJet

## Notes

- The complete documentation includes all content from the official documentation
- The content is automatically generated from the same source as the official documentation

## Optional

- [OpenAPI 3.1 specification](https://docjet.dev/docs/quickstart/curl/): cURL quickstart with the full request/response surface
- [Webhook signature verification](https://docjet.dev/docs/concepts/webhooks/): X-DocJet-Signature scheme and verify helpers
- [Error codes reference](https://docjet.dev/docs/concepts/errors/): Full error taxonomy with HTTP statuses