API reference
Authentication
Every request carries a bearer key in the Authorization header. Keys are scoped
per stream and can be rotated without downtime, the old key stays valid for one hour after rotation.
Endpoints
| Method | Path | Purpose |
|---|
| POST | /v3/events | Publish a single event or a batch |
| GET | /v3/events/replay | Replay a window by cursor |
| GET | /v3/streams | List streams and retention |
| POST | /v3/keys/rotate | Rotate an ingestion key |
Publishing
Batches accept up to 500 events or 1 MB, whichever comes first. Events are acknowledged only after
they are durable. Each event needs a stream, a type and a payload object.
| Field | Type | Notes |
|---|
| stream | string | Target stream, created on first write |
| type | string | Dotted event name, for example order.paid |
| data | object | Free form payload up to 64 KB |
| idempotency_key | string | Optional, deduplicates retries for 24 hours |
Replay
Cursors are opaque and stable. Passing a cursor twice returns the same window, which makes retries
safe. A replay never affects the position of other consumers on the same stream.
Rate limits
| Plan | Writes/s | Retention |
|---|
| Starter | 500 | 7 days |
| Team | 5,000 | 30 days |
| Scale | 50,000 | 90 days |
Errors
| Code | Meaning |
|---|
| 401 | Key missing, expired or out of scope |
| 409 | Duplicate idempotency key |
| 429 | Write rate exceeded, retry after the header value |