API keys and rate limits

Every API request carries a secret key from your shop. Each key has its own render limit, so a bug in one integration can't empty your balance.

Create a key#

  1. In the app, open your shop's Settings and scroll to Developer API.
  2. Give the key a name, for example "Configurator", and press Create key.
  3. Copy the key right away. It is shown once; VizTunr only keeps a fingerprint of it.

Keys start with vzt_sk_. Send one in the Authorization header of every request:

curl https://app.viztunr.com/api/v1/balance \
  -H "Authorization: Bearer vzt_sk_..."

Keep keys on your server. A key in a browser, mobile app, or public repository lets anyone render on your balance. If one leaks, revoke it.

A shop can have up to 10 active keys. Use a separate key for each integration, so you can limit or revoke one without touching the others.

Plans#

The API is included with Growth and Pro.

Your planWhat the API answers
Growth or ProNormal responses
Starter402 with code plan_upgrade_required
No active plan402 with code plan_required

If your shop moves down to Starter, your keys stay listed and start working again as soon as you upgrade. Nothing is revoked.

Rate limit#

Each key may start 30 renders per minute by default. Change it per key in Settings → Developer API, anywhere from 1 to 300: higher for a batch job, lower for a key used by a public configurator.

Over the limit, POST /v1/renders answers 429 with code rate_limited and a Retry-After header with the seconds to wait. Uploads, reading renders, and the balance are not limited.

The limit is separate from the visitor limits on your storefront. Those don't apply to the API: your own site decides how often each customer can render.

Balance#

curl https://app.viztunr.com/api/v1/balance \
  -H "Authorization: Bearer $VIZTUNR_KEY"
{ "renders_available": 412, "plan": "growth" }

Balances are counted in renders. When it reaches zero, new renders answer 402 with code out_of_renders. Turn on Auto top-up in Billing to keep the API running; see Plans, renders, and top-ups.

Revoke a key#

Press Revoke next to the key in Settings → Developer API and confirm. Requests with that key stop working immediately (401, code invalid_api_key). Renders it already made stay in your dashboard.