Renders

Render a document

Renders template with data and returns a signed URL. Returns 200 when the render finished inside the request, 202 when it was queued. A cache hit always returns 200.

post/v1/render

Request

  • Base URL: https://api.galleyrender.com
  • URL: https://api.galleyrender.com/v1/render
  • Auth: HTTP bearer

Request body

templatestring required

invoice for the latest version, or invoice@3 to pin one. Pin it in anything you ship.

format'pdf' | 'png' | 'jpg' | 'jpeg'

Defaults to pdf for chromium templates and png for satori ones. webp is not in v1.

webhook_urlstring uri

Absolute https URL to POST on completion. Supplying one forces the queued path. The body is signed with X-Galley-Signature (HMAC-SHA256 over the raw body, using the secret from GET /v1/account), and delivery is retried up to five times with exponential backoff over about a quarter of an hour.

asyncboolean

Force the queued path even for a small job.

Example request

{
  "template": "invoice@3",
  "data": {
    "lang": "pt-BR"
  },
  "options": {
    "margin": "18mm"
  },
  "webhook_url": "https://example.com/hooks/galley"
}

Response

Rendered inside the request, or served from cache.

object'render' required
idstring required
status'queued' | 'processing' | 'succeeded' | 'failed' required
templatestring required

The resolved name@version.

format'pdf' | 'png' | 'jpg' required
engine'chromium' | 'satori' required
cachedboolean required

True when the stored object was reused. A cache hit is never billed.

urlstring uri nullable required

Signed URL to the file. Expires in an hour by default; the stored file lasts until expires_at. null while the render is unfinished, when it failed, and once expires_at has passed.

expires_atstring date-time nullable

The end of the file's retention, fixed when the render is made from the account's plan. After it the render is no longer a cache hit, GET /v1/renders/{id} answers 410 retention_expired, and the file is deleted by a daily sweep. Not the signed URL's expiry.

page_countinteger nullable

Pages in the PDF; 1 for raster output.

billable_unitsinteger nullable

1 per PNG/JPG, 1 per PDF page.

byte_sizeinteger nullable
content_typestring nullable
created_atstring date-time required
completed_atstring date-time nullable
errorunknown
webhook_status'pending' | 'delivered' | 'failed' | 'null' nullable

null when no webhook_url was given. pending while delivery is still being attempted, delivered once your endpoint answered 2xx, failed once all attempts were used.

webhook_attemptsinteger

Delivery attempts made so far.

batch_idstring

Present only for batch items.

file_deleted_atstring date-time nullable

When the file was deleted because its retention had passed. null until then. The render record itself is kept; the data and options it was made from are deleted with the file.

Example response

{
  "id": "rnd_7hq2m4x8k1bv",
  "template": "invoice@1",
  "warnings": [
    {
      "path": "data.deposit",
      "did_you_mean": "data.deposit_amount"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.