# API Overview

Overview of the Brizz REST API

Brizz has two HTTP surfaces on two different hosts: **ingestion**, where you send telemetry in, and the **platform API**, where you read your data back out and manage configuration. They take different credentials and different `Authorization` schemes — mixing them up is the most common cause of a `401`.

Most teams should use the official SDKs for ingestion and only use the raw API for custom pipelines.

## Base URLs

| Surface | Base URL | What it does |
|---|---|---|
| Telemetry ingestion | `https://telemetry.brizz.dev` | Accepts traces and events. Write-only — it has no read endpoints. |
| Platform API | `https://platform.brizz.dev/api/v1` | Reads sessions, traces, and analysis results; manages configuration such as webhook subscriptions. |

## Authentication

### Telemetry ingestion — `Bearer`

Ingestion takes a **Telemetry API key** or a [DSN](/docs/admin/server-dsn.md), created under **Organization Settings > API Keys**, sent as `Bearer`:

```bash
curl -X POST "https://telemetry.brizz.dev/raw/events" \
  -H "Authorization: Bearer $BRIZZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"user.login","service_name":"my-app","session_id":"s-1","timestamp":"2025-11-24T10:00:00Z"}'
```

### Platform API — `Token`

The platform API takes a **Platform API key**, created under [**User Settings > Platform API Keys**](/app/settings/platform-api-keys), sent as `Token`:

```bash
curl "https://platform.brizz.dev/api/v1/telemetry/otel/sessions/my-agent/SESSION_ID/transcript" \
  -H "Authorization: Token $BRIZZ_PLATFORM_API_KEY"
```

:::warning
The two credentials are not interchangeable, and neither is the scheme. On the platform API, `Bearer` is reserved for the dashboard's sign-in token, so a Platform API key sent as `Bearer` is checked against the wrong validator and returns `401` even though the key itself is valid — use `Token`. A Telemetry API key or DSN is not a Platform API key at all: it authenticates ingestion only, and returns `401` against the platform API whichever scheme you use. Both failures return an identical bare `401`, so check the key class and the scheme together rather than assuming the key is bad.
:::

A Platform API key acts as the user who created it, with that user's role and tenant, and inherits their project membership. Create it under an account that will outlive any one person's access — if the owning user is deprovisioned, integrations using their key stop working. The key is pinned to its own tenant; an `X-Tenant-ID` header is ignored on this path.

## Request Format

- All requests must use HTTPS
- Request bodies should be JSON with `Content-Type: application/json`
- Dates should be in ISO 8601 format

## Response Format

Ingestion endpoints respond with a simple JSON status:

```json
{ "status": "success" }
```

### Error Responses

Errors follow this format:

```json
{ "error": "Invalid JSON format" }
```

## Common Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| `unauthorized` | 401 | Invalid or missing API key |
| `forbidden` | 403 | Insufficient permissions |
| `not_found` | 404 | Resource not found |
| `rate_limited` | 429 | Too many requests |
| `invalid_request` | 400 | Invalid request parameters |
| `server_error` | 500 | Internal server error |

## Endpoints

- [Telemetry ingestion](/docs/api/telemetry.md) — `POST /raw/traces`, `POST /raw/events`.
- [Reading data](/docs/api/reading-data.md) — fetching sessions, transcripts, traces, and spans back out.
- [Outbound webhooks](/docs/api/webhooks.md) — subscribing to `session.matured` and `trace.matured` instead of polling.

## SDKs

We provide official SDKs that handle authentication, retries, batching, and auto-instrumentation:

- [Python SDK](/docs/sdks/python.md)
- [Node.js / TypeScript SDK](/docs/sdks/typescript.md)

## See also

- [Telemetry ingestion](/docs/api/telemetry.md) — endpoint reference for the ingestion host.
- [Reading data](/docs/api/reading-data.md) — endpoint reference for the platform host.
- [Outbound webhooks](/docs/api/webhooks.md) — get pushed an event instead of polling.
- [API keys](/docs/admin/api-keys.md) — creating and rotating the *telemetry* keys used for ingestion.
- [Choose your SDK](/docs/sdks.md) — prefer an SDK over raw HTTP for almost every case.

Support: support@brizz.ai