Add an API v1 endpoint
Extend the starter API surface with a thin route handler, explicit permissions, and stable envelopes.
Add an API v1 endpoint
Use this flow when your product needs a new machine-readable endpoint under /api/v1.
Choose the route
Add the route handler under src/app/api/v1. Keep the handler thin: parse request input, require an
API key, call feature/server modules, and return a stable response envelope.
Define permissions
Add a concrete permission for the new endpoint. If several endpoints belong together, add or extend a permission preset so users can configure keys without choosing every scope manually.
Require API key auth
Use the API key auth helpers. Browser sessions should not grant access to /api/v1; the caller must
send x-api-key.
Return stable responses
Successful responses should return { "data": ... }. Handled failures should return
{ "error": { "code": "...", "message": "..." } } with an appropriate status.
Document and test
Update API v1 reference, add or update OpenSpec requirements, and cover the route through API-focused E2E or integration tests.