Libraries & SDKs

With an API key sent as a bearer token. Keys are created in the dashboard and belong to a workspace.

Everything in the workspace it belongs to. Keys are not scoped to individual templates — if you need one integration to reach only a subset of templates, put those templates in their own workspace and use that workspace’s key.

Yes. Keys carry a permission level, so a key used only for polling does not need to be able to create renders.

Create a new one, move your integration to it, then delete the old one. Keys are independent, so there is no window where both stop working.

Renders are queued. You get a job back immediately and collect the result either by polling it or by receiving a webhook. Video work in particular takes long enough that holding a request open is not practical. For images we do have an optional sync endpoint.

Only if you cannot receive a webhook. A webhook tells you the moment a job finishes; polling costs you requests and latency.

Register a URL and Bannerbear posts to it when a job reaches a terminal state. You can listen for completions only, or for every event.

Yes. A webhook is scoped, so you can have one for image renders and another for tool jobs rather than one endpoint sorting out everything.

Each webhook has a signing key, and deliveries are signed with it. Verify the signature before acting on the payload.

Yes, it can be rolled. Do it if you suspect the key has leaked.

The delivery is recorded with its outcome, so you can see what was sent and what happened. Build your endpoint to be idempotent — treat a repeated delivery as a no-op rather than a second render.

Yes. Every request is logged with its payload, its result and the credits it cost, filterable by API key — which is usually the fastest way to find out why something behaved unexpectedly.

A JSON body with a message, and a status code that says what to do: 400 for a malformed request, 404 for a template that does not exist, 402 when the account is out of credits.

The request is refused rather than queued, with a message saying how many credits it needed and how many remain. Handle it distinctly from a transient failure — retrying will not help.

Yes, generated from the same definitions the API validates against, so it stays in step with what the endpoints actually accept.

No. It is a JSON API over HTTPS and works with whatever HTTP client you already use.

Use a separate workspace. Its templates and its API key are isolated from production, so experiments cannot touch the templates a live integration depends on.

Pin the version. Renders can target a specific saved version of a template, so redesigning it does not change what an existing integration produces until you move it.

Files are served from a CDN and the URLs are returned with the finished job. If you need them permanently, copy them into your own storage as part of handling the webhook.