API Reference
Base URL: https://api.reforg.io — all public endpoints are versioned under /v1.
The full interactive reference — every request/response schema, try-it-out included — is generated from the API itself and lives at api.reforg.io/api/v1 . This page is the map; that page is the territory.
Authentication
Every request needs an x-api-key header. There are two key types:
| Key | Prefix | Where | Access |
|---|---|---|---|
| Secret key | sk_live_ | Server only | Full organization access |
| Public key | pk_live_ | Browser | Scoped to one end user; requires extra headers |
Public-key requests must additionally send a browser Origin on your allowed domains list, plus x-user-id and x-user-hash (HMAC-SHA256 of the user ID with your signing secret — see the frontend guide).
Rate limit
100 requests per minute per API key. Exceeding it returns 429 Too Many Requests.
Endpoints
Rendering
| Method & path | What it does |
|---|---|
POST /v1/render | Render a published template with { templateId, data, format } → { documentId, status, downloadUrl, fileSizeBytes, renderTimeMs } |
GET /v1/downloads/:id | 302 redirect to a fresh short-lived presigned URL for a completed document |
Templates
| Method & path | What it does |
|---|---|
POST /v1/templates | Create a template (requires name, formats: ('pdf'|'xlsx')[], and at least one entry in sections) |
GET /v1/templates | List non-archived templates (secret key: whole org; public key: that user’s) |
GET /v1/templates/:id | Get one template with sections and variables |
PATCH /v1/templates/:id | Update fields — every update records a new version |
DELETE /v1/templates/:id | Archive (soft delete) — hidden from lists, no longer renderable |
GET /v1/templates/:id/versions | Version history, newest first |
POST /v1/templates/:id/publish | Set status to published, making the template renderable |
Assets (read-only)
| Method & path | What it does |
|---|---|
GET /v1/assets | List the organization’s uploaded assets |
GET /v1/assets/:id | Asset metadata |
Usage
| Method & path | What it does |
|---|---|
GET /v1/usage | Usage grouped by template + format for a month (?year=&month=; secret key may filter ?externalUserId=) |
GET /v1/usage/trend | Documents per month, last 6 months |
Public-key callers always see only their own usage; secret-key callers see the whole organization.
Account
| Method & path | What it does |
|---|---|
POST /v1/auth/rotate-keys | Regenerate public key, secret key, and signing secret. Secret key required — old credentials die immediately |
GET /v1/orgs | The organization behind the API key (sensitive keys masked) |
Errors
Non-2xx responses carry a JSON body with a message; both SDK clients turn it into a thrown ReforgioError { message, statusCode }. See the error catalog for every exact message and how to handle it.