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.
Base URL
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
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) |
| 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/...
Error responses
Errors return JSON with a message field:
{
"error": "not_found",
"message": "Site not found"
}
| 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
