API Overview

The FL Repos service exposes two APIs with intentionally different credentials:

Surface	Base path	Credential	Audience
Intelligence and operations	`/api`	`FL_API_TOKEN` bearer	Trusted automation, CLI, and internal services.
Commercial control plane	`/v1`	Organization-scoped service JWT or CLI credential	FL Web and tenant automation.

GET / and GET /health are public health checks. GET /v1/billing/plans is the public commercial plan catalog. The Polar webhook verifies its signature instead of using bearer authentication.

Start with an outcome

You need to…	Use	First request
Browse repository and code intelligence	Operations API	`GET /api/repos` with `FL_API_TOKEN`.
Find a code capability by intent or ontology	Semantic Search	`GET /api/search/hybrid`; refine with ontology and test filters.
Plan or run an internal fleet workflow	Fleet API or `FleetClient`	`GET /api/fleet/plan` before a run.
Manage tenant usage, checkout, CLI runs, or reports	Commercial API	Tenant-scoped `/v1/*` request with organization identity.

Response conventions

Most collection routes return either {items, total} or {items, total, page, page_size, total_pages}. Graph-backed item fields are enrichment-dependent; use the named fields in API Schemas and tolerate additional fields.

{"detail":"Human-readable error message"}

Errors use 401, 403, 404, 409, 422, 500, 502, or 503 as appropriate. See Authentication before choosing a credential.

If you receive…	Check this first	Recovery
`401`	The route’s credential plane	Use `FL_API_TOKEN` only for protected `/api/`; use tenant credentials for protected `/v1/`.
`403`	Organization, role, and permission	Confirm the tenant member or service principal has the required action.
`422`	Parameter name, type, and allowed range	Compare the request with the endpoint’s parameter table.
`503`	Required data store or service	Retry after the dependency recovers; embedding search also needs a populated local DuckDB store.

All intelligence endpoints

Group	Routes	Detail
Health	`GET /`, `GET /health`	Public status.
Repositories	`GET /api/repos`, `GET /api/repos/{name}`, `GET /api/search`, `GET /api/rankings`, `GET /api/stats`, `GET /api/tiers`	Repositories.
Code intelligence	`GET /api/functions`, `/classes`, `/models`, `/models/{model_name}/fields`, `/endpoints`, `/contributors`, `/security`, `/deep-stats`	Deep Insights.
Graph	`GET /api/graph`, `GET /api/graph/neighbors/{name}`, `POST /api/graph/node`, `PATCH /api/graph/node/{label}/{name}`, `POST /api/graph/edge`, `DELETE /api/graph/node/{label}/{name}`	Graph.
Search	`GET /api/search/hybrid`, `GET /api/skills/by-ontology`, `GET /api/embeddings/search` (local or mounted DuckDB only)	Semantic Search.
Fleet	`GET /api/fleet/plan`, `POST /api/fleet/run`, `GET /api/fleet/status`	Fleet and Operations.
Quality and audit	`GET /api/quality/history`, `/quality/current`, `POST /api/quality/snapshot`, `GET /api/audit/timeline`, `/audit/summary`	Fleet and Operations.
Benchmark and discovery	`GET /api/benchmark/tasks`, `/benchmark/tasks/{instance_id}`, `/benchmark/eval-results`, `/technical-discovery`	Fleet and Operations.
Administration	`POST /api/embeddings/generate`, `POST /api/admin/reload-graph`	Fleet and Operations.

All commercial endpoints

Group	Routes
Billing and usage	`GET /v1/billing/plans`, `GET /v1/billing/usage`, `GET /v1/billing/entitlements`, `POST /v1/usage/events`, `POST /v1/billing/checkout-session`, `POST /v1/billing/portal-session`, `POST /v1/billing/webhooks/polar`
CLI bridge	`POST /v1/cli/pair`, `GET/POST /v1/cli/runs`, `POST /v1/cli/publish`, `GET /v1/cli/config`, `POST /v1/tenant/service-principals/{credential_id}/revoke`
Reports	`POST /v1/reports`, `GET /v1/reports/{report_id}`

See Commercial Control Plane for role requirements and workflow order.