# Telemetry ingestion

Low-level HTTP endpoints for sending traces and events to Brizz.

Brizz provides a simple HTTP API for sending raw telemetry. Most teams should prefer the **official SDKs**, which handle:

- Authentication headers
- OpenTelemetry formatting
- Batching/retries
- Automatic instrumentation of supported AI libraries

Use this API when you need a custom pipeline or want to send telemetry from a non-supported runtime.

## Base URL

```
https://telemetry.brizz.dev
```

## Authentication

All requests require an API key:

```
Authorization: Bearer YOUR_API_KEY
```

Brizz accepts:

- **Legacy API keys** — work as-is.
- **Server DSN** (`brizz-ing-s-…`) — single-paste credential for the Brizz backend SDK. Bundles bearer, endpoint, and service name. Don't use with the frontend SDK.
- **Client DSN** (`brizz-ing-c-…`) — single-paste credential for the Brizz frontend SDK. Safe to ship inside browser bundles. Optionally pin to an `allowed_origins` list (set in the dashboard) to restrict which sites can use the key.

## Send traces

`POST /raw/traces`

A trace payload includes:

- `provider` (currently `openai`)
- `service_name` (your app/service name)
- `session_id` (conversation/workflow identifier)
- `request` (the full provider request)
- `responses` (1–2 responses; use 2 for tool-call workflows)

Example:

```bash
curl -X POST "https://telemetry.brizz.dev/raw/traces" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BRIZZ_API_KEY" \
  -d '{
    "provider": "openai",
    "service_name": "my-chatbot",
    "session_id": "session-001",
    "environment": "production",
    "request": {
      "model": "gpt-4",
      "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of France?"}
      ]
    },
    "responses": [
      {
        "id": "chatcmpl-demo123",
        "object": "chat.completion",
        "model": "gpt-4",
        "choices": [
          {"index": 0, "message": {"role": "assistant", "content": "The capital of France is Paris."}, "finish_reason": "stop"}
        ],
        "usage": {"prompt_tokens": 15, "completion_tokens": 8, "total_tokens": 23}
      }
    ],
    "start_time": "2025-11-24T10:00:00Z",
    "end_time": "2025-11-24T10:00:02Z"
  }'
```

Success response:

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

## Send events

`POST /raw/events`

Example:

```bash
curl -X POST "https://telemetry.brizz.dev/raw/events" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BRIZZ_API_KEY" \
  -d '{
    "name": "user.login",
    "service_name": "my-app",
    "session_id": "session-001",
    "timestamp": "2025-11-24T10:00:00Z",
    "severity_number": 9,
    "attributes": {"user_id": "user-123", "method": "oauth"},
    "body": {"success": true, "duration_ms": 245},
    "environment": "production"
  }'
```

## Common errors

- **400**: invalid payload
- **401**: missing/invalid API key
- **403**: DSN origin rule violation
- **500**: server error

:::tip
If you’re using Node/Python, prefer the SDKs unless you have a strong reason not to.
:::

## See also

- [API overview](/docs/api/overview.md) — base URLs, auth, error model.
- [Choose your SDK](/docs/sdks.md) — language-specific options that handle batching and instrumentation for you.
- [API keys](/docs/admin/api-keys.md) — creating and rotating the key used here.