# API guides

Everything an integrator needs beyond the endpoint reference.

Everything an integrator needs beyond the endpoint reference. These pages
cover the cross-cutting behaviour that sits behind every endpoint. Start with the
[Quickstart](/docs/api/quickstart); building with an AI agent, start with [Agents](/docs/api/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](/docs/api/quickstart) | A key, a contact, an event and a first email, in five requests |
| [Transactional messages](/docs/api/transactional) | Receipts, resets and alerts by email and push: templates, fallback, batches, secrets |
| [Push notifications](/docs/api/push) | Setting up iOS, Android and web apps, registering devices from your server, reporting taps, iPhone web apps |
| [Agents](/docs/api/agents) | Connecting Claude, Cursor or any MCP client, and what an agent key cannot do |
| [Authentication](/docs/api/authentication) | Obtaining a key, the scope catalogue, and why an `agent` key returns 403s that look like bugs |
| [Pagination](/docs/api/pagination) | Cursor-only, opaque, `meta.pagination.nextCursor` — and why there is no `page` parameter |
| [Errors](/docs/api/errors) | The envelope, every public code, and which are worth retrying |
| [Rate limits](/docs/api/rate-limits) | Per-key and per-org limits, `Retry-After`, and correct backoff |
| [Idempotency](/docs/api/idempotency) | Which operations are safe to retry, and the two different mechanisms |
| [Webhooks](/docs/api/webhooks) | Event catalogue, signature verification, delivery and retry behaviour |
| [E-commerce events](/docs/api/ecommerce-events) | The standard commerce event names and properties, and payments from a connected provider |
| [Versioning](/docs/api/versioning) | What `/v1` guarantees, how additive changes are signalled |
| [Staging](/docs/api/staging) | Running your integration from staging: a second workspace, not a test mode |
| [SDK conformance](/docs/api/sdk-conformance) | The checklist every server library must satisfy |

## The shape of every response

Success bodies carry the payload under `data`, with optional `meta`:

```json
{ "data": { "id": "018f…", "name": "Weekly digest" } }
```

List responses add pagination to `meta`:

```json
{
  "data": [ … ],
  "meta": { "pagination": { "limit": 20, "nextCursor": "eyJpZCI6…" } }
}
```

Errors replace `data` with `error`, and never mix the two:

```json
{ "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.