REST API Reference
The Spanlens REST API backs the dashboard and is stable for direct use. All authenticated endpoints require a Supabase JWT in Authorization: Bearer …. Proxy endpoints use a Spanlens API key.
Authentication
Two security schemes are used:
| Scheme | Header | Used for |
|---|---|---|
| BearerJWT | Authorization: Bearer <jwt> | All /api/v1/* dashboard endpoints |
| ApiKey | Authorization: Bearer sl_live_… | Proxy endpoints (/proxy/*) and SDK ingest (/ingest/*) |
JWTs are obtained from Supabase Auth (supabase.auth.getSession()) and expire after 1 hour. Spanlens API keys (sl_live_…) are created at /projects by clicking + New Spanlens key on the project card; they never expire (revoke explicitly via the toggle when rotating). For the cryptographic details + the per-SDK auth-header mapping, see Keys & encryption and Direct proxy.
Base URLs
| Environment | Base URL |
|---|---|
| Production (hosted) | https://server.spanlens.io |
| Local dev | http://localhost:3001 |
| Self-hosted | https://your-spanlens.example.com |
Endpoint groups
| Group | Prefix | Auth |
|---|---|---|
| Health | GET /health | None |
| Organizations | /api/v1/organizations | JWT |
| Projects | /api/v1/projects | JWT |
| API keys | /api/v1/api-keys | JWT |
| Provider keys | /api/v1/provider-keys | JWT |
| Requests | /api/v1/requests | JWT |
| Stats | /api/v1/stats | JWT |
| Traces | /api/v1/traces | JWT |
| Prompts | /api/v1/prompts | JWT |
| Anomalies | /api/v1/anomalies | JWT |
| Security | /api/v1/security | JWT |
| Alerts | /api/v1/alerts | JWT |
| Recommendations | /api/v1/recommendations | JWT |
| Evals | /api/v1/evaluators | JWT |
| Datasets | /api/v1/datasets | JWT |
| Experiments | /api/v1/experiments | JWT |
| Prompt experiments (A/B) | /api/v1/prompt-experiments | JWT |
| Prompt playground | /api/v1/prompts-playground/run | JWT |
| Human evals | /api/v1/human-evals | JWT |
| Annotation queue | /api/v1/annotation/queue | JWT |
| Webhooks | /api/v1/webhooks | JWT (admin/editor for writes) |
| Audit logs | /api/v1/audit-logs | JWT |
| Saved filters | /api/v1/saved-filters | JWT |
| Exports | /api/v1/exports/* | JWT |
| Members | /api/v1/organizations/:orgId/members | JWT (admin for writes) |
| Invitations | /api/v1/organizations/:orgId/invitations | JWT (admin) |
| Proxy, OpenAI | /proxy/openai/v1/* | API key |
| Proxy, Anthropic | /proxy/anthropic/v1/* | API key |
| Proxy, Gemini | /proxy/gemini/v1/* | API key |
| Proxy, Azure OpenAI | /proxy/azure/* | API key |
| SDK Ingest | /ingest/* | API key |
For the full interactive spec, request/response schemas, try-it-out, example curl commands, open the Swagger UI.
Plan-gated responses to know about
A few endpoints respond with HTTP 402 Payment Required when a plan limit is hit, so your client can distinguish "you ran out of headroom" from a generic 400/403:
POST /api/v1/organizationsreturns 402 with{ "code": "workspace_limit_reached", "error": "…", "owned": N, "limit": M, "effectivePlan": "…" }when the caller already owns the maximum workspaces their effective plan allows (Free 1, Pro 2, Team 5, Enterprise unlimited). Upgrade any owned workspace and retry. See Billing & quotas for the full per-plan table.