Lakuna · docs
Cloud API reference
| Route | Method | Auth | Request body | Response |
|---|---|---|---|---|
| /api/keys | GET | session | none | { apiKey, createdAt } (mints one on first visit) |
| /api/keys | POST | session | none | { apiKey, createdAt } (regenerates, retires the old key) |
| /api/route | POST | key | { text, clientLocalFailure?, collectTrainingData? } | RouteResult |
| /api/strategies | POST | key | { text } | { strategies: string[] } |
| /api/usage/report | POST | key | { tokensIn?, tokensOut?, latencyMs } | records a local-tier usage event |
| /api/usage | GET | session | none | UsageSummary |
| /api/training-data | GET | key | none | { pairs: { prompt, completion, createdAt }[] } |
session = signed-in Clerk browser session (cookie); these two back the dashboard and the agent never calls them. key = API key in Authorization: Bearer <key> or x-api-key; those routes return 401 without one.
POST /api/route
How the agent escalates. Send clientLocalFailure to skip straight to cloud with that reason. Returns { summary, tier, localSource, escalated, escalationReason?, costEstimateUsd, latencyMs } (app/lib/route-types.ts). Set collectTrainingData: true to opt this escalation into retention for fine-tuning - see GET /api/training-data below.
POST /api/strategies
Returns strategies from similar past cases, retrieved by embedding similarity.
GET /api/training-data
Returns this key's own accumulated { prompt, completion, createdAt } pairs - only from escalations that opted in with collectTrainingData: true. Empty for any key that never opted in. Fetched by lakuna --export-training-data to produce a fine-tuning-ready JSONL file.
POST /api/usage/report
Records a local-tier success. Only counts, never request or response text.
GET /api/usage
{ totalRequests, localRequests, cloudRequests, totalTokensIn, totalTokensOut, costUsd, costSavedUsd, avgLatencyMs, series }, where series is per-minute buckets (oldest first, non-empty only).
Cloud requests go to Cloudflare Workers AI's hosted @cf/zai-org/glm-5.2 (GLM-5.2, MIT-licensed and open-weight), called directly through its OpenAI-compatible endpoint - not through the Vercel AI Gateway, which does not carry Cloudflare Workers AI as a provider. Set CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN (a token scoped to Workers AI) in the deployment's environment.