DocsReference
REST API
The routes under /api/v1, the response envelope every one of them uses, authentication and the errors to expect. Each server also documents itself at /docs.
The interactive reference
A running BBM-Atlas serves its full API reference, generated from the code, at /docs (Swagger UI) and /redoc: every route, its request and its response, ready to try.
Requests and the envelope
curl -s http://127.0.0.1:8000/api/v1/retrieval/search \ -H "X-API-Key: $BBM_ATLAS_API_KEY" -H "Content-Type: application/json" \ -d '{"repository_id": "<repository_id>", "query": "how does checkout work?"}'Every response - success or failure, including the server's own errors - has the same shape:
{ "success": true, "data": { … }, "metadata": { … }, "errors": []}On failure success is false and each entry of errors has a code (the HTTP status), a message and, where useful, details - an ambiguous name's candidates, for example. /metrics is the one exception: it is Prometheus text.
Authentication
When the server requires keys, send one as X-API-Key: <key> or Authorization: Bearer <key>. With the Enterprise Edition, an account's bbma_ key, an identity provider's access token, or the console's session all work.
Routes
| Area | Routes |
|---|---|
| Repositories | POST /api/v1/repositories (index), GET /api/v1/repositories[/{id}], GET …/{id}/symbols?path=, GET …/{id}/symbols/at?path=&line=, DELETE /api/v1/repositories/{id} |
| Index jobs | POST /api/v1/jobs/index, GET /api/v1/jobs[/{id}], DELETE /api/v1/jobs/{id} (cancel) |
| Search and impact | POST /api/v1/retrieval/search, POST /api/v1/impact/analyze |
| Knowledge graph | POST /api/v1/graph/query, /neighbors, /path, /outcome; GET /api/v1/graph/node/{id}, /cycles/{repo}, /god-nodes/{repo}, /communities/{repo}, /stats/{repo}, /ambiguous/{repo}, /lessons/{repo} |
| Facts | POST /api/v1/facts/remember, POST /api/v1/facts/recall, DELETE /api/v1/facts/{id}?repository_id= |
| Agents | POST /api/v1/agents/run |
| Compression | POST /api/v1/compress, POST /api/v1/compress/retrieve, GET /api/v1/compress/stats, GET /api/v1/compress/dashboard |
| Administration | GET /api/v1/admin/status, GET /api/v1/admin/feature-flags, PUT /api/v1/admin/feature-flags/{name} |
| Enterprise | /api/v1/enterprise/: license, me and me/keys, roles, principals and their keys, organizations, audit, and the sign-in routes under sso/ and saml/ |
| Operations | GET /health, GET /health/ready, GET /metrics, /mcp, /console/, GET /api/v1/auth/methods |
Errors
| Status | Means |
|---|---|
| 400 | The request can't be done as asked: a path that isn't a directory, a fact of another repository |
| 401 | No key, or one the server doesn't accept |
| 403 | The key is accepted, but its role doesn't allow this (the message names the permission), or the path is outside the directories the server may index |
| 404 | Not found - or another organisation's, which reads the same |
| 409 | A conflict: an ambiguous symbol name (its candidates are in details), a repository already being indexed, or the last administrator |
| 413 | The request body is larger than the server accepts |
| 422 | The request doesn't match the route's schema; details says where |
| 429 | Over the rate limit; Retry-After says how many seconds to wait |
| 503 | A store is unreachable, or agents are switched off |