docs / api

API reference

Base URL is https://postimager.com. Send Authorization: Bearer <key> on every request. Bodies are JSON.

Endpoints

Method	Path	Key scope	What it does
`POST`	`/v1/renders`	`renders:write`	Create a render. Send Idempotency-Key; add ?wait=1..60 to get the finished file in the same response.
`GET`	`/v1/renders/{id}`	`renders:read`	Status, failure reason and a fresh download link valid 24 hours.
`GET`	`/v1/renders`	`renders:read`	Recent renders, newest first (limit up to 100).
`DELETE`	`/v1/renders/{id}`	`renders:write`	Delete a finished file now; the record stays.
`GET`	`/v1/templates`	`templates:read`	Templates available to your account.
`GET`	`/v1/templates/{id}`	`templates:read`	Fields, limits, defaults and sizes for one template.
`GET`	`/v1/usage`	`usage:read`	Renders used this month, what was not charged, and your limits.

Create a render

POST /v1/renders?wait=60
Idempotency-Key: rss-item-8f2c
{
  "template": "product-card",
  "template_version": 1,          // optional; must match if sent
  "size": "square",               // optional; template default
  "format": "png",                // png | jpg | pdf (always one page)
  "variables": { "brand_name": "Kiln & Clay", "product_name": "Mug", "price": "₹1,250" }
}

Returns 202 with the render. A replay with the same key and body returns 200 and the header Idempotent-Replayed: true. Without wait the response is immediate with status queued; poll GET /v1/renders/{id} every second or two.

Render object

{
  "id": "9b1c…", "status": "completed",
  "template": { "id": "product-card", "version": 1 },
  "size": "square", "width": 1080, "height": 1080, "format": "png",
  "attempts": 1, "warnings": [], "error": null,
  "variables": { … },
  "output": {
    "bytes": 56872, "render_ms": 240, "retained_until": "…", "deleted": false,
    "download": { "url": "…/files/9b1c…?exp=…&sig=…", "expires_at": "…" },
    "thumbnail_url": "/v1/renders/9b1c…/thumbnail"
  }
}

Keys and scopes

Keys carry scopes: renders:write, renders:read, templates:read, usage:read. A read-only key is useful for reporting. Keys are stored as hashes; if you lose one, revoke it and create another.