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. API keys are created in Settings → Projects & API keys and never expire (revoke explicitly when rotating).
Base URLs
| Environment | Base URL |
|---|---|
| Production (hosted) | https://spanlens-server.vercel.app |
| Local dev | http://localhost:3001 |
| Self-hosted | https://your-spanlens.example.com |
Endpoint groups
| Group | Prefix | Auth |
|---|---|---|
| Health | GET /health | None |
| Waitlist | POST /api/v1/waitlist | 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 |
| Members | /api/v1/organizations/:orgId/members | JWT (admin for writes) |
| Proxy — OpenAI | /proxy/openai/v1/* | API key |
| Proxy — Anthropic | /proxy/anthropic/v1/* | API key |
| Proxy — Gemini | /proxy/gemini/v1/* | 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.