API Overview - Toffee

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:

{
  "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.

​Base URL

​Authentication

​Session auth (dashboard)

​API key auth (SDK ingestion)

​Endpoints

​Public (no auth)

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

​Common patterns

​Team-scoped routes

​Error responses

​Analytics time ranges