Reference
API endpoints
A reference of the built-in API routes, grouped by area, with method, path, purpose, and auth requirement.
Every built-in API route lives under apps/web/app/api/ as a route.ts file. This page inventories them by area. It is a map, not an exhaustive contract — open the route file for exact request/response shapes.
Routes fall into a few auth buckets:
| Auth | How it's enforced |
|---|
| Public | No session required. |
| Session | auth.api.getSession({ headers }) — a signed-in user is required. |
| Session or API key | authenticateRequest() — accepts a session cookie or a Bearer sk_... / x-api-key developer key (when API keys are enabled). |
| Admin | requirePermission(req, PERMISSIONS.*) from lib/rbac — an admin session with the relevant permission. |
| Webhook signature | Verified against a provider signing secret (e.g. Stripe). |
| Internal | Server-to-server only, authorized by CRON_SECRET or AGENTS_INTERNAL_SECRET — never called from a browser. |
Every data route scopes its queries to the session's user id — never a hardcoded id. See Building → Add an API route.
| Method | Path | Purpose | Auth |
|---|
GET POST | /api/auth/[...all] | Better Auth catch-all: sign-in/up, session, OAuth callbacks, password reset, 2FA. Rate-limited. | Public (auth flows) |
GET | /api/auth/permissions | The current user's resolved RBAC permissions. | Session |
The items resource is the worked example of a CRUD API, opted into API-key auth. See API keys.
| Method | Path | Purpose | Auth |
|---|
GET POST | /api/items | List / create items for the current user. | Session or API key |
PATCH DELETE | /api/items/[id] | Update / delete one item. | Session or API key |
GET | /api/search | Full-text search across the user's items. | Session |
| Method | Path | Purpose | Auth |
|---|
GET POST | /api/api-keys | List / create per-user API keys. | Session |
PATCH DELETE | /api/api-keys/[id] | Rename / revoke a key. | Session |
| Method | Path | Purpose | Auth |
|---|
GET | /api/settings/account | Account metadata (provider, email-verified, created). | Session |
GET | /api/settings/activity | Recent account activity. | Session |
POST | /api/settings/avatar | Persist the user's avatar URL. | Session |
GET | /api/settings/export | Export all of the user's data as JSON. | Session |
POST | /api/settings/delete-account | Permanently delete the account and its data. | Session |
GET PUT | /api/settings/model-preference | Get / set the user's preferred chat model. | Session |
| Method | Path | Purpose | Auth |
|---|
GET | /api/chat/active-model | The catalog model the chat should run against now, after precedence resolution. | Session |
GET POST | /api/conversations | List / create chat conversations. | Session |
GET DELETE | /api/conversations/[id] | Fetch / delete one conversation. | Session |
GET POST | /api/conversations/[id]/messages | List / append messages in a conversation. | Session |
The chat message stream itself is not an API route — it runs over a WebSocket to the realtime Worker (apps/realtime). These routes manage conversation history. See AI chat.
| Method | Path | Purpose | Auth |
|---|
GET | /api/notifications | List the user's notifications. | Session |
POST | /api/notifications/[id]/read | Mark one notification read. | Session |
POST | /api/notifications/read-all | Mark all read. | Session |
POST DELETE | /api/push-tokens | Register / unregister an Expo push token (mobile). | Session |
| Method | Path | Purpose | Auth |
|---|
GET POST | /api/files | List / upload files (to R2, local, or an external backend). | Session |
GET DELETE | /api/files/[key] | Fetch / delete a stored file. | Session |
POST | /api/images | Upload a generated image. | Session |
GET | /api/images/[...key] | Serve a stored image. | Session |
| Method | Path | Purpose | Auth |
|---|
POST | /api/voice/speak | ElevenLabs text-to-speech proxy (API key stays server-side). | Session |
| Method | Path | Purpose | Auth |
|---|
POST | /api/stripe/create-checkout | Start a Stripe Checkout session. | Session |
GET | /api/stripe/portal | Get a Stripe customer-portal URL. | Session |
GET | /api/stripe/status | Current plan / subscription status. | Session |
POST | /api/stripe/webhook | Stripe event webhook (syncs subscription state). | Webhook signature |
| Method | Path | Purpose | Auth |
|---|
POST | /api/realtime-demo/ping | Publish a single event to the user's realtime channel (demo). | Session |
| Method | Path | Purpose | Auth |
|---|
GET | /api/flags | Evaluate feature flags with the user's context. Unauthenticated requests get global defaults. | Public / Session-aware |
| Method | Path | Purpose | Auth |
|---|
POST | /api/subscribe | Newsletter signup. Rate-limited. | Public |
GET POST | /api/unsubscribe | Unsubscribe via a signed token. | Public |
POST | /api/waitlist/join | Join the waitlist. Rate-limited. | Public |
GET | /api/waitlist/status | Waitlist mode / position status. | Public |
GET | /api/waitlist/validate-invite | Validate an invite code. | Public |
POST | /api/waitlist/redeem-invite | Redeem an invite code. | Session |
| Method | Path | Purpose | Auth |
|---|
GET | /api/email/open | Open-tracking pixel. | Public (signed token) |
GET | /api/email/click | Click-tracking redirect. | Public (signed token) |
| Method | Path | Purpose | Auth |
|---|
POST | /api/analytics/track | Record an analytics event. | Session |
GET | /api/health | Structured health snapshot (200 ok/degraded, 503 down) for external monitors. | Public |
| Method | Path | Purpose | Auth |
|---|
GET | /api/docs-search | Full-text search over the customer docs. | Public |
GET | /api/wiki-search | Full-text search over the admin dev wiki. | Admin |
Manage endpoints that Valcraven calls when events fire. See Webhooks.
| Method | Path | Purpose | Auth |
|---|
GET POST | /api/webhooks | List / create outbound webhook endpoints. | Session |
GET PATCH DELETE | /api/webhooks/[id] | Manage one endpoint. | Session |
GET | /api/webhooks/[id]/deliveries | Delivery history for an endpoint. | Session |
POST | /api/webhooks/[id]/test | Send a test event to an endpoint. | Session |
Server-to-server only — not called from a browser.
| Method | Path | Purpose | Auth |
|---|
GET | /api/cron | Enqueue and process due scheduled jobs. | CRON_SECRET |
POST | /api/internal/campaign-batch | Drain one campaign send batch (queue consumer). | CRON_SECRET |
POST | /api/internal/cache-purge | Purge cached public pages by tag. | CRON_SECRET |
POST | /api/internal/conversation-message | Persist an agent-generated chat message. | AGENTS_INTERNAL_SECRET |
POST | /api/internal/notifications | Create a notification from the realtime Worker. | AGENTS_INTERNAL_SECRET |
POST | /api/internal/docs-search | FTS5 search over the docs corpus (customer docs + dev wiki) for AI-chat retrieval. | AGENTS_INTERNAL_SECRET |
POST | /api/internal/docs-index/rebuild | Rebuild the docs FTS5 index from the current MDX. | AGENTS_INTERNAL_SECRET or CRON_SECRET |
All admin routes live under /api/admin/* and require an admin session with the matching permission (requirePermission). They power the admin console. See Admin.
| Area | Representative routes | Purpose |
|---|
| Users | GET /api/admin/users, GET /api/admin/users/[id], PATCH …/status, PATCH DELETE …/plan, GET PUT DELETE …/role, POST …/email, POST …/reset-pw | Browse and manage users, plans, status, roles, email, and password resets. |
| Roles (RBAC) | GET POST /api/admin/roles, GET PATCH DELETE /api/admin/roles/[id] | Manage roles and their permissions. |
| Analytics | GET /api/admin/analytics, …/growth, …/product, …/revenue | Dashboards: overview, growth, product, revenue. |
| AI models | GET PUT /api/admin/ai-models, PUT DELETE /api/admin/ai-models/keys, GET /api/admin/ai-usage | Configure the model catalog, provider keys, and view usage/cost. |
| Campaigns | GET POST /api/admin/campaigns, GET PATCH DELETE …/[id], POST …/send, …/schedule, …/cancel, …/resend, …/preview, GET …/analytics, POST …/audience-count, POST …/sync-delivery | Create, schedule, send, and analyze email campaigns. |
| Subscribers | GET PATCH POST DELETE /api/admin/subscribers, GET …/[email]/events, GET …/tags | Manage newsletter subscribers, tags, and per-subscriber events. |
| Blog | GET POST /api/admin/blog, GET PATCH DELETE /api/admin/blog/[id], POST …/preview | Author and manage blog posts. |
| Database browser | GET /api/admin/database/tables, GET PATCH DELETE /api/admin/database/[table] | Browse and edit database tables. |
| Waitlist | GET /api/admin/waitlist, POST …/invite | Review the waitlist and issue invites. |
| Ops | GET /api/admin/health, GET POST /api/admin/jobs, GET /api/admin/logs, GET /api/admin/audit-log | Health, scheduled jobs, logs, and the audit trail. |