Everything an integrator needs beyond the endpoint reference. These pages cover the cross-cutting behaviour that sits behind every endpoint. Start with the Quickstart; building with an AI agent, start with Agents.
Written for the person building a client. If three people implement an SDK independently and each invents their own answer to something, that something belongs here.
| Guide | What it settles |
|---|---|
| Quickstart | A key, a contact, an event and a first email, in five requests |
| Transactional messages | Receipts, resets and alerts by email and push: templates, fallback, batches, secrets |
| Push notifications | Setting up iOS, Android and web apps, registering devices from your server, reporting taps, iPhone web apps |
| Agents | Connecting Claude, Cursor or any MCP client, and what an agent key cannot do |
| Authentication | Obtaining a key, the scope catalogue, and why an agent key returns 403s that look like bugs |
| Pagination | Cursor-only, opaque, meta.pagination.nextCursor — and why there is no page parameter |
| Errors | The envelope, every public code, and which are worth retrying |
| Rate limits | Per-key and per-org limits, Retry-After, and correct backoff |
| Idempotency | Which operations are safe to retry, and the two different mechanisms |
| Webhooks | Event catalogue, signature verification, delivery and retry behaviour |
| E-commerce events | The standard commerce event names and properties, and payments from a connected provider |
| Versioning | What /v1 guarantees, how additive changes are signalled |
| Staging | Running your integration from staging: a second workspace, not a test mode |
| SDK conformance | The checklist every server library must satisfy |
The shape of every response
Success bodies carry the payload under data, with optional meta:
{ "data": { "id": "018f…", "name": "Weekly digest" } }List responses add pagination to meta:
{
"data": [ … ],
"meta": { "pagination": { "limit": 20, "nextCursor": "eyJpZCI6…" } }
}Errors replace data with error, and never mix the two:
{ "error": { "code": "CONFLICT", "message": "…", "details": { … } } }204 No Content responses have no body at all.
Base URL
The base URL is https://api.kirora.io. Every SDK uses it by default and lets you override it, so
tests can point at a mock server. The version is in each path (/v1/…), not in the base URL.