A small API that does one job well

Seven endpoints, bearer-key authentication, the same error shape everywhere, and idempotent creates so retries are always safe.

Quickstart Full reference

Render your first image

These are the exact files our test script runs against a local server before every release of the docs.

#!/usr/bin/env bash
# Render a product card and download it. Needs only bash, curl, grep and sed.
# POSTIMAGER_API_KEY=rk_... POSTIMAGER_URL=https://postimager.com ./render.sh
set -euo pipefail
BASE="${POSTIMAGER_URL:-https://postimager.com}"

RESPONSE=$(curl -sS -X POST "$BASE/v1/renders?wait=15" \
  -H "Authorization: Bearer $POSTIMAGER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-sku-482-v1" \
  -d '{
    "template": "product-card",
    "size": "square",
    "format": "png",
    "variables": {
      "brand_name": "Kiln & Clay",
      "product_name": "Speckled stoneware mug, 350 ml",
      "price": "₹1,250",
      "image_url": "sample:mug"
    }
  }')

if ! echo "$RESPONSE" | grep -q '"status":"completed"'; then
  echo "Not finished yet or failed: $RESPONSE" >&2
  exit 1
fi
URL=$(echo "$RESPONSE" | sed -n 's/.*"download":{"url":"\([^"]*\)".*/\1/p')
curl -sS -o product-card.png "$URL"
echo "Saved product-card.png"

docs/examples/render.sh · executed against a local server by scripts/test-examples.ts

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.

Errors, limits and async behaviour