For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /docs/web/api.md (or send Accept: text/markdown).

Public API, keys and webhooks

The versioned REST surface your customers build against.

Ask about this guide

Before you begin

Open your downloaded supastack project in Visual Studio Code using File → Open Folder, then choose Terminal → New Terminal. The repository root is the folder containing package.json, apps and packages. Run the command below there and leave its terminal open. If a command is not recognized, finish the tool installation guide before continuing.

Read the platform tutorial first. A server is the app process that answers browser or phone requests. Web reads apps/web/.env.local, Expo reads apps/mobile/.env.local, and database migration commands read root .env. The no-database /dashboard demonstration is separate from real /auth accounts, which need migrated Postgres. A phone or desktop-only checkout needs a separately running Web backend.

corepack pnpm --filter @supastack/web dev

Setup and configuration

packages/api defines the versioned contract: zod schemas for every request and response, the error envelope, and the OpenAPI document served at /api/v1/openapi and rendered at /api/docs. Workspace API keys are created under Settings → Developers; plaintext is shown once, then only the hashed key persists.

Keys are prefixed (sk_<env>_…), scoped (read by default), and resolved to a workspace on every request. Outbound webhook subscriptions are managed from the same Developers surface.

GET  /api/v1/workspaces/current
GET  /api/v1/entitlements
GET  /api/v1/models/requirements
POST /api/v1/ai-tasks
GET  /api/v1/openapi           # machine-readable spec
GET  /api/docs                 # rendered reference

Authorization: Bearer sk_live_…

Implementation workflow

Authenticate with the Bearer key; the server resolves the workspace from the key, never from a client-supplied id. Keep response shapes versioned — additive changes inside v1, breaking changes behind a new version.

For outbound webhooks, subscribe an endpoint URL to the event catalog; deliveries are signed and recorded so consumers can verify and replay them. Use webhook-events.ts for the catalog and webhook-delivery.ts for attempts.

Verification and troubleshooting

Verify a revoked key returns 401, an underscoped key is denied, and the OpenAPI document parses. For webhooks, test signature verification, redelivery after failure, and that event payloads never carry provider secrets.