API Reference

Authentication

All API requests require an API key. Pass it in the x-api-key header.

curl -X POST https://api.tannur.xyz/emit \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"stream":"orders","type":"order.created","data":{"id":"123"}}'

You can generate and rotate API keys from the Tannur Dashboard under Settings → API Keys, or via the CLI:

tannur rotate-key

Event Sourcing API

Tannur's core is an event-sourcing engine. You emit events into named streams, and Tannur materialises the current state by replaying them in order.

POST /emit

Append a new event to a stream. Tannur automatically resolves the tenant from your API key.

{
  "stream": "orders",
  "type": "order.created",
  "data": {
    "orderId": "abc-123",
    "amount": 49.99,
    "currency": "NGN"
  }
}

{
  "ok": true,
  "eventId": "evt_7xk29m",
  "stream": "orders",
  "sequence": 42,
  "timestamp": "2026-06-30T12:00:00Z"
}

GET /state

Returns the current materialised state of a stream — computed by replaying every event in order.

GET /state?stream=orders

{
  "stream": "orders",
  "state": {
    "totalOrders": 42,
    "totalRevenue": 2099.58,
    "lastOrderAt": "2026-06-30T12:00:00Z"
  },
  "version": 42
}

GET /events

Retrieve the raw event log for a stream.

GET /events?stream=orders
    &limit=50
    &offset=0

{
  "events": [
    {
      "id": "evt_7xk29m",
      "type": "order.created",
      "data": { "orderId": "abc-123" },
      "sequence": 42,
      "timestamp": "2026-06-30T12:00:00Z"
    }
  ],
  "total": 42
}

CLI Authentication Flow

The CLI authenticates via a browser-based OAuth handshake. These three endpoints power that flow.

# Typical flow (the CLI does this for you):
1. POST /auth-cli-start  →  { code: "ABCD-1234", url: "https://tannur.xyz/auth?code=ABCD-1234" }
2. User opens URL in browser and approves
3. GET  /auth-cli-poll?code=ABCD-1234  →  { status: "approved", token: "tk_..." }
4. CLI stores the token locally for future requests

Deployment API

Push builds to Tannur's edge network and check system health.

Database API

Provision and manage databases (PostgreSQL, MySQL, MongoDB, Redis, ClickHouse) directly through the API.

Create a Database

POST /api/database/create

{
  "name": "my-app-db",
  "type": "postgres",
  "region": "us-east-1",
  "memory_limit": 1024,
  "storage_limit": 10240
}

{
  "database": {
    "id": "db_8fk29x",
    "name": "my-app-db",
    "type": "postgres",
    "status": "provisioning",
    "host": "db-8fk29x.tannur.xyz",
    "port": 5432,
    "connection_string": "postgresql://..."
  }
}

Supported Engines

Feature Access & Tiers

Tannur enforces tier-based feature gating. Use these endpoints to check what your current plan allows.

Tier Hierarchy

Error Handling

All errors follow a consistent JSON shape:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "status": 401
  }
}