> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toffee.at/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Authentication, base URL, and common patterns for the Toffee API.

## Base URL

```
https://api.toffee.at
```

All endpoints are prefixed with `/api/v1`.

## Authentication

The API uses two authentication methods depending on the endpoint:

### Session auth (dashboard)

Used by the dashboard and any integration that manages teams, sites, and analytics. Authenticates via session cookies set by the `/api/auth/*` endpoints (powered by BetterAuth).

All team-scoped endpoints (`/api/v1/teams/:teamSlug/...`) require session auth plus team membership.

### API key auth (SDK ingestion)

Used by the SDK to send events. Pass the API key as a header:

```
X-Api-Key: ar_YOUR_API_KEY
```

Or as a query parameter:

```
?apiKey=ar_YOUR_API_KEY
```

API keys are created per-site and can be revoked from the dashboard.

## Endpoints

### Public (no auth)

| Method | Route              | Description                                                     |
| ------ | ------------------ | --------------------------------------------------------------- |
| `POST` | `/api/v1/waitlist` | Join waitlist (rate-limited: 3 req/15min per IP)                |
| `GET`  | `/api/v1/pixel`    | Tracking pixel for non-JS clients (API key via `k` query param) |

### SDK / API key auth (`X-Api-Key` header)

| Method | Route                        | Description                                          |
| ------ | ---------------------------- | ---------------------------------------------------- |
| `POST` | `/api/v1/events`             | Ingest events (detections, pageviews, session\_end)  |
| `GET`  | `/api/v1/stats`              | Site statistics (agent/human counts, detection rate) |
| `GET`  | `/api/v1/agents`             | List detected agents                                 |
| `GET`  | `/api/v1/pages`              | Page-level statistics                                |
| `GET`  | `/api/v1/elements`           | Element clicks (requires `page` query param)         |
| `GET`  | `/api/v1/visitors`           | Visitor analytics                                    |
| `GET`  | `/api/v1/session/:sessionId` | Events for a specific session                        |
| `GET`  | `/api/v1/live`               | SSE stream for real-time updates (requires `siteId`) |

## Common patterns

### Team-scoped routes

Most endpoints are scoped to a team via the URL:

```
/api/v1/teams/:teamSlug/sites/:siteId/...
```

Your session must have membership in the team. Some operations (update/delete team, manage roles) require owner or admin role.

### Error responses

Errors return JSON with a `message` field:

```json theme={null}
{
  "error": "not_found",
  "message": "Site not found"
}
```

Common status codes:

| Code  | Meaning                                     |
| ----- | ------------------------------------------- |
| `400` | Bad request — missing or invalid parameters |
| `401` | Unauthorized — missing or invalid auth      |
| `403` | Forbidden — insufficient permissions        |
| `404` | Not found                                   |
| `500` | Server error                                |

### Analytics time ranges

Analytics endpoints accept a `range` query parameter — the number of hours to include (default: `24`):

```
GET /api/v1/teams/:teamSlug/analytics/:siteId/stats?range=168
```

This returns data for the last 7 days.