REST API Reference
Twelve operations, one authentication scheme, one error format.
Base URL and authentication
Hosted: https://api.rendarium.com. Self-hosted: your container, default port 8490. Every request carries the API key as a Bearer token:
Authorization: Bearer rnd_live_... # hosted key, created in the portal
Authorization: Bearer rnd_self_... # self-hosted key, generated with genkeyKeys are 41 characters: rnd_ + live/self + _ + 32 random lowercase letters and digits. Hosted keys are verified per request against a hash; self-hosted keys against the container configuration. No cookies, no CSRF tokens — the API is not a browser surface.
Operations and credits
One successful request that returns an artifact (PDF or image) costs one credit on the hosted API, regardless of document size. Self-hosted containers have no credits.
| Endpoint | Operation | Credits | Notes |
|---|---|---|---|
POST /convert/html | HTML to PDF | 1 | HTML string → PDF |
POST /convert/url | URL to PDF | 1 | public URL → PDF |
POST /convert/html/image | HTML to Image | 1 | HTML or URL → PNG / JPEG / WebP |
POST /convert/word | Word to PDF | 1 | DOCX → PDF |
POST /convert/excel | Excel to PDF | 1 | XLSX → PDF |
POST /convert/rtf | RTF to PDF | 1 | RTF → PDF |
POST /convert/markdown | Markdown to PDF | 1 | Markdown → PDF |
POST /documents/render | PDF Builder | 1 | drawing commands → PDF |
POST /edit | PDF Edit | 1 | PDF + edits → PDF |
POST /merge | PDF Merge | 1 | PDFs → PDF |
POST /measure | Text Measure | 0 | text/HTML → measurements (free) |
POST /jobs, GET /jobs/{id} | Async Jobs | 1 on accept | refunded if the job fails |
GET /health, /version, /license | Service | 0 | status, engine version, license status (self-hosted) |
Any failed or rejected request (4xx, 5xx, 503) costs 0 credits; if a credit was reserved before the failure it is refunded automatically. /documents/render limits the number of HTML template commands per request, since each one is a real Chromium render.
Versioning
Paths carry no version. The API version travels in the Rendarium-Version request header (year.month, for example 2026.8); when absent, the current version is used. Responses include Rendarium-Version and a Request-Id header — quote the request id in support tickets.
Rate limits
10 requests per second per API key, enforced with a token bucket (bursts up to 10, then 10/second sustained). Requests over the limit receive 429 {"error":"rate_limited"} before any credit or database is touched and are not charged.
Error format
Errors are JSON with a stable error code and an optional human-readable detail:
{ "error": "quota_exceeded",
"detail": "Buy a top-up or upgrade at https://app.rendarium.com/billing" }The complete list of codes and status mappings is on the convert/html page and applies to every operation.
Limits
- Request body: 2 MB for HTML strings; 25 MB for uploaded Word, Excel, RTF and PDF files.
- Synchronous request time-out: 60 seconds. Use async jobs for anything larger.
- Active API keys per hosted account: 10.
OpenAPI
The machine-readable contract is published at /rendarium-openapi.yaml (OpenAPI 3.1).