API reference

The Stet API is a REST API for composing broadcasts, targeting audiences, sending or scheduling, and reading back delivery and engagement results. Every operation below documents its own parameters, request body, and responses — this page covers what's true across all of them.

Authentication

Every request carries an API key (prefix bk_) as a bearer token:

Authorization: Bearer bk_xxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are minted under Settings → API keys, scoped read or write — composing and sending require a write-scope key. The whole API surface requires the organization's plan to be Growth or higher; below that, every request returns a 403 with a plan-upgrade-required problem document. /api/keys (listing, creating, and revoking keys) is the one part of this surface a bk_ key can never reach — those routes require a signed-in Clerk dashboard session instead, so a key can't be used to mint or revoke keys.

Idempotency

Send-affecting routes accept an Idempotency-Key header — a client-generated UUID. POST /api/broadcasts/{id}/schedule and POST /api/broadcasts/{id}/send-now require one; POST /api/broadcasts honors it if supplied but does not require it. Replaying a request with the same key returns the original result instead of repeating the side effect. This is best-effort response caching, not a lock: the send pipeline's atomic claim is what actually guarantees a broadcast sends exactly once.

Errors

Errors are RFC 9457 problem+json (Content-Type: application/problem+json). Match on type — a stable URI like https://stethq.com/problems/plan-upgrade-required — not on title or the HTTP status, which can change independently of the error's meaning.