API Reference — Phase 1#

One page per Phase 1 endpoint surface. Each page has a flow diagram, request / response shape, DB tables touched, and links to the Jira ticket and ADRs.

All endpoints are versioned under /api/v1/… and require Authorization: Bearer <JWT> unless noted.

Modules#

API	Endpoint prefix	Writes	Jira
Auth	`/api/v1/auth`	—	BFC-13
User Access	`/api/v1/users/me/access`	—	BFC-14
Groups	`/api/v1/groups`	flag-gated	BFC-15
License	`/api/v1/license`	—	BFC-29
Help	`/api/v1/help`	—	BFC-30
Favorites	`/api/v1/users/me/favorites`	flag-gated	BFC-23
Navigation	`/api/v1/navigation/menu`	—	BFC-25
Settings	`/api/v1/settings`	flag-gated	BFC-22
Search	`/api/v1/search`	—	BFC-24

Response envelope#

Every successful response is wrapped:

{ "success": true, "data": <T>, "errors": null }

Errors return RFC 7807 ProblemDetails (HTTP 4xx / 5xx) with X-Correlation-ID header.

Cross-cutting#

Rate limit: per-user (JWT sub) or per-IP fallback, fixed window
CORS: whitelist from Cors:AllowedOrigins
Health: GET /health (liveness), GET /ready (SQL readiness)
Swagger: /docs in Development or when FeatureFlags:EnableSwagger=true