API reference

Atlas exposes a single HTTP API on the gateway (atlas-gateway:58100, public surface at https://atlas.naburis.cloud/api/atlas/*). The list below is sourced from mountAPI in cmd/atlas-gateway/main.go — when the gateway changes, regenerate this page from the same function.

Conventions

• All authenticated routes require either an OIDC bearer token (machine-to-machine callers) or an atlas_session cookie (browser callers via the BFF flow).
• Browser callers must additionally send X-Atlas-CSRF: 1 on state-mutating methods (POST, PATCH, DELETE).
• Every request must carry the scope triple: X-Tenant-ID, X-Workspace-ID, X-Context-ID.
• Streaming endpoints emit text/event-stream with named events (start, evidence, token, milestone, citation, error, done); each data: line is a JSON object the client parses incrementally.

Infra

Method	Path	Auth	Purpose
GET	/health	none	Aggregate health (postgres + optional dependencies).
GET	/healthz /readyz /livez /startupz	none	Kubernetes-style probes.
GET	/metrics	none	Prometheus scrape.
GET	/auth/config	none	OIDC bootstrap for the SPA.
POST	/api/telemetry	none	Fire-and-forget SPA telemetry sink.
*	/auth/*	(varies)	BFF Zitadel code flow + backchannel logout.
GET	/api/auth/session	session	BFF session probe for the SPA.

Knowledge — resolve, traverse, plan, synthesise

Method	Path	Purpose
GET	/api/atlas/resolve/intents	Available intent IDs (e.g. migration_path, feature_lookup).
GET POST	/api/atlas/resolve	Hybrid retrieval (text → graph → vector).
POST	/api/atlas/traverse	Keystone graph traversal proxy.
GET	/api/atlas/plan/versions	SAP version families known to the planner.
POST	/api/atlas/plan	Generate a migration plan via the DJED AI gateway.
POST	/api/atlas/answer/stream	SSE synthesised answer (planner → keystone-oracle).

Corpus, artifacts, documents, guidance

Method	Path	Purpose
GET	/api/atlas/artifacts ?type=	List SAP artifacts.
GET	/api/atlas/artifacts/{id}	Get one artifact.
GET	/api/atlas/corpus	Unified search over the corpus.
GET	/api/atlas/corpus/{id}	Corpus item detail.
GET	/api/atlas/corpus/status	Per-collector freshness + last error.
POST	/api/atlas/corpus/recrawl	Trigger an immediate crawler refresh.
GET	/api/atlas/guidance	List guidance items (best practices, deprecations, replacements).
GET	/api/atlas/documents	List source documents.
GET	/api/atlas/documents/{id}	Get a source document.
GET	/api/atlas/crawl/status	Crawler job status.
POST	/api/atlas/graph/rebuild	Drain the graph outbox into Keystone.

Studio

Method	Path	Purpose
POST	/api/atlas/studio/classify	Classify a task into a pattern type.
POST	/api/atlas/studio/plan	Build a task graph.
POST	/api/atlas/studio/scaffold	Generate scaffolds.
POST	/api/atlas/studio/pipeline	End-to-end pipeline.
GET	/api/atlas/studio/generations	List generation archive.
POST	/api/atlas/studio/generations	Save a generation.
GET DELETE	/api/atlas/studio/generations/{id}	Get / delete one.
DELETE	/api/atlas/studio/generations	Wipe the archive.

Govern

Method	Path	Purpose
GET	/api/atlas/clean-core/readiness	Clean-core readiness summary + blockers.
GET	/api/atlas/control/scorecard	Clean-core scorecard, modules, top risks.

Cases

Method	Path	Purpose
POST GET	/api/atlas/cases	Create / list cases.
GET PATCH DELETE	/api/atlas/cases/{id}	Get / update / delete a case.
POST	/api/atlas/cases/{id}/duplicate	Duplicate.
POST	/api/atlas/cases/{id}/investigate	Run an investigation against the case scope.
GET	/api/atlas/cases/{id}/runs	List previous investigation runs.
GET	/api/atlas/cases/{id}/events	Audit timeline (every state change).
GET	/api/atlas/cases/{id}/summary	Generated case summary.
GET	/api/atlas/cases/{id}/evidence	Pinned + collected evidence.
POST GET	/api/atlas/cases/{id}/bundle(s)	Generate / list bundles.
POST GET	/api/atlas/cases/{id}/estimate(s)	Generate / list estimates.
GET	/api/atlas/cases/{id}/recommendations	List recommendations.
PATCH	/api/atlas/cases/{id}/recommendations/{recId}	Update a recommendation.
GET	/api/atlas/cases/{id}/feedback	List feedback events.
GET	/api/atlas/cases/{id}/audit	Download the case audit trail.

Status semantics

/readyz decomposes into per-dependency entries:

Key	Meaning of not_ready
postgres	Atlas DB unreachable. The gateway exits hot — expect a restart.
resolver planner keystone	Optional dependencies; downstream features degrade.
ai	DJED AI gateway key or readiness unavailable; planner falls back to baseline where possible.
openrouter	Deprecated compatibility alias for ai.
ontology	Atlas ontology not registered with Keystone — apply the ACL grant runbook.

When any optional dependency is configured but unreachable, the aggregate status flips from ok to degraded so make doctor reports the real failure mode rather than green-on-paper success.