REST API Reference

Audience: developer integrating with the Cortex REST API.

All routes are mounted under /api (e.g. GET http://localhost:9096/api/atoms). The API uses the envelope format { ok: true, data: ... } for success and { ok: false, error: { message, code } } for errors.

Authentication is via API key passed in the Authorization header as Bearer <key>. Role-based access is enforced per route.

---

Modes

Cortex supports two modes controlled by the CORTEX_MODE environment variable:

• full (default): all routes are mounted.
• lib: read-only catalogue routes only (atoms, search, templates, governance, catalogue, library, navigation, documents, account).

Routes marked full below are only available in full mode.

---

Atoms

Method	Path	Role	Mode	Description
GET	/atoms	—	lib	Search atoms by taxonomy. Query: famille, sousFamille, type (FEUILLE/COMPOSE), occurrence, limit.
GET	/atoms/stats	—	lib	Atom distribution statistics (total, byFamille, bySousFamille, byType).
GET	/atoms/governance	—	lib	Governance atoms grouped by sous-famille.
GET	/atoms/:id	—	lib	Atom detail (all 6 layers). Returns 404 if not found.

---

Catalogue — Blocs

Method	Path	Role	Mode	Description
GET	/catalogue/blocs	reader	lib	List blocs. Query: type (skill/expertise/methode/tool/scope, supports CSV), category, tags (CSV), limit, offset. Response includes usedByCount.
GET	/catalogue/blocs/search?q=...	reader	lib	Full-text search blocs. Query: q (required).
GET	/catalogue/blocs/:id	reader	lib	Get a single bloc. Query: version (optional semver for history).
POST	/catalogue/blocs	contributor	lib	Deposit a new bloc. Body: DepositBlocBody. Returns 201.
PATCH	/catalogue/blocs/:id	contributor	lib	Update an existing bloc. Body: UpdateBlocBody.
DELETE	/catalogue/blocs/:id	admin	lib	Delete an orphan bloc.
GET	/catalogue/stats	reader	lib	Catalogue statistics by type/category.

---

Catalogue — Modeles

Method	Path	Role	Mode	Description
GET	/catalogue/modeles	reader	lib	List all modeles.
GET	/catalogue/modeles/:id	reader	lib	Get a single modele. Returns 404 if not found.
POST	/catalogue/modeles	contributor	lib	Deposit a new modele. Body: DepositModeleBody. Returns 201.
DELETE	/catalogue/modeles/:id	admin	lib	Delete a modele.

---

Catalogue — Profils HYOS

Method	Path	Role	Mode	Description
GET	/profils	reader	lib	List profils. Query: origin (modele/sur_mesure/variante), owner, limit, summary (boolean, returns minimal fields).
GET	/profils/search?q=...	reader	lib	Full-text search profils. Query: q (required).
GET	/profils/:id	reader	lib	Get a single profil with blocs and variantes.
GET	/profils/:id/card	reader	lib	Get a profil card (summary with bloc counts and variant count).
POST	/profils	contributor	lib	Create a profil (alias of forger). Body: ForgerProfilBody. Returns 201.
POST	/profils/forger	contributor	lib	Forge a new profil from blocs. Body: ForgerProfilBody. Returns 201.
POST	/profils/pack-hyos	—	lib	Pack HYOS for agent onboarding. Body: { id, project_id?, bloc_types? }. Returns profil + blocs + governance.
POST	/profils/:id/enrichir	contributor	lib	Add blocs to a profil. Body: { blocIds: string[] }.
POST	/profils/:id/detacher	contributor	lib	Detach blocs from a profil. Body: { blocIds: string[] }.
POST	/profils/:id/variante	contributor	lib	Create a variante. Body: CreerVarianteBody. Returns 201.
PATCH	/profils/:id	contributor	lib	Edit profil fields (role, mission, mindset, keywords, sectors, scope, responsibilities, metiers). Bumps semver.
PATCH	/profils/:id/blocs/:blocId	contributor	lib	Change the weight (poids) of an attached bloc. Body: { poids: 'core' | 'support' }.
DELETE	/profils/:id	admin	lib	Delete a profil (fails if it has variantes or active instances).

---

Ingestion (HYOS pipeline)

Method	Path	Role	Mode	Description
POST	/blocs	contributor	full	Ingest a single bloc via the ingestion pipeline. Body: arka.hcm.block.v1 JSON. Rate limited (600/min).
POST	/blocs/dry-run	contributor	full	Validate a bloc without persisting. Same body.
POST	/blocs/batch	admin	full	Batch ingest up to 200 blocs. Body: JSON array.
POST	/profils/ingest	contributor	full	Ingest a single profil via the ingestion pipeline. Body: arka.hcm.profil.v1 JSON. Rate limited (200/min).
POST	/profils/ingest/batch	admin	full	Batch ingest profils. Body: JSON array.

---

Deposit (low-level graph writes)

Method	Path	Role	Mode	Description
POST	/deposit	contributor	full	Deposit a single node + edges. Body: DepositBody. Returns 201.
POST	/deposit/batch	contributor	full	Deposit up to 100 nodes. Body: { items: DepositBody[] }. Returns 201.
POST	/enrich	contributor	full	Merge data into an existing node. Body: EnrichBody.
DELETE	/nodes/:id	contributor	full	Remove a node.

---

Search

Method	Path	Role	Mode	Description
POST	/search	—	lib	Faceted search (MeiliSearch). Body: { query, filters?, facets?, sort?, limit?, offset? }.
GET	/search/atoms?q=...	—	lib	Search atoms by occurrence.
GET	/search/stats	admin	lib	MeiliSearch index statistics.

---

Workspace

Method	Path	Role	Mode	Description
GET	/workspace/overview	—	full	Workspace overview (projects, totals).
GET	/workspace/scope	—	full	Adaptive scope. Query: project, mission, library (off/consumed/all).
GET	/workspace/projects	—	full	List projects. Query: includeArchived (boolean).
GET	/workspace/projects/:id	—	full	Project detail + missions + counts.
GET	/workspace/projects/:id/agents	—	full	Project agents (team).
GET	/workspace/projects/:id/mcts	—	full	Project MCT list.
GET	/workspace/projects/:id/odms	—	full	Project ODM list.
GET	/workspace/projects/:id/crs	—	full	Project CR list.
POST	/workspace/projects	—	full	Create a project. Body: CreateProjectBody.
PATCH	/workspace/projects/:id	—	full	Update a project. Body: UpdateProjectBody.
GET	/workspace/missions/:id	—	full	Mission detail + ODMs + CRs.
GET	/workspace/missions/:id/mct	—	full	Mission MCT.
POST	/workspace/missions	—	full	Create a mission. Body: CreateMissionBody.
PATCH	/workspace/missions/:id	—	full	Update a mission. Body: UpdateMissionBody.
POST	/workspace/missions/:id/links	—	full	Add a link to a mission. Body: MissionLinkBody.
DELETE	/workspace/missions/:id/links/:targetId	—	full	Remove a link from a mission.
GET	/workspace/missions/:id/links	—	full	List mission links.
GET	/workspace/mcts/:id	—	full	MCT detail.
POST	/workspace/odms	—	full	Create an ODM. Body: CreateOdmBody.
GET	/workspace/odms/:id	—	full	ODM detail + tasks + CRs.
PATCH	/workspace/odms/:id	—	full	Update an ODM. Body: PatchOdmBody.
POST	/workspace/crs	—	full	Create a CR. Body: CreateCrBody.
GET	/workspace/crs/:id	—	full	CR detail.
PATCH	/workspace/crs/:id	—	full	Update a CR. Body: PatchCrBody.

---

Memory

Method	Path	Role	Mode	Description
GET	/memory/agent/:agentId/project/:projectId/resume	—	full	Agent memory resume for a project.
GET	/memory/project/:projectId/resume	—	full	Project memory resume.
GET	/memory/project/:projectId/decisions	—	full	Project decisions. Query: status, limit.
GET	/memory/agent/:agentId/decisions	—	full	Agent decisions. Query: status, projectId.
GET	/memory/agent/:agentId/erreurs	—	full	Agent errors. Query: status, projectId.
GET	/memory/agent/:agentId/patterns	—	full	Agent patterns. Query: projectId.
GET	/memory/agent/:agentId/feedbacks	—	full	Agent feedbacks. Query: projectId.
PUT	/memory/agent/resume	—	full	Update agent resume.
PUT	/memory/project/resume	—	full	Update project resume.
POST	/memory/atoms	—	full	Deposit a memory atom (decision, erreur, pattern, feedback).
PATCH	/memory/atoms/status	—	full	Update memory atom status.

---

Governance

Method	Path	Role	Mode	Description
GET	/governance/praxis	—	lib	List Praxis bricks.
GET	/governance/praxis/:id	—	lib	Get a single Praxis brick. Returns 404 if not found.
GET	/governance/atoms	—	lib	Governance atoms grouped by sous-famille.

---

Navigation (graph queries)

Method	Path	Role	Mode	Description
GET	/context/:id	—	lib	360-degree context of an entity (node + edges + neighbors).
GET	/impact/:id	—	lib	Blast radius analysis. Query: direction (upstream/downstream), maxDepth.
GET	/nodes/:id	—	lib	Get a single node.
GET	/edges/:id	—	lib	Get edges for a node.
GET	/traverse/:id	—	lib	Traverse from a node. Query: direction, edgeType, depth.
GET	/nodes/type/:type	—	lib	List nodes by type.
GET	/subgraph/:id	—	lib	Alias for traverse.
POST	/query	admin	lib	Raw SurrealQL query (SELECT only).
GET	/diff	—	lib	Graph diff since timestamp.

---

Templates

Method	Path	Role	Mode	Description
GET	/templates	—	lib	List all template types (17 types).
GET	/templates/:type	—	lib	Get template definition by type.
POST	/templates/build	—	full	Build an entity from a template + data. Body: TemplateBuildBody.
GET	/tasks	—	lib	List tasks. Query: odm (filter by ODM ID).

---

Documents

Method	Path	Role	Mode	Description
POST	/documents	contributor	lib	Ingest a document. Body: IngestDocumentBody. Returns 201.
GET	/documents	—	lib	List documents. Query: tags (CSV), since, until, query, limit, offset.
GET	/documents/search?q=...	—	lib	Search documents.
GET	/documents/:id	—	lib	Get a document.
GET	/documents/ref/:ref	—	lib	Get a document by ref.
GET	/documents/:id/history	—	lib	Document version history.
DELETE	/documents/:id	contributor	lib	Delete a document.

---

Library

Method	Path	Role	Mode	Description
GET	/library/families	—	lib	List families. Query: limit, offset.
GET	/library/families/:id/children	—	lib	Get sub-families of a family.
GET	/library/families/:fid/sub-families	—	lib	Alias for children.
GET	/library/sub-families/:sfid/sub-sub-families	—	lib	Get sub-sub-families.
GET	/library/sub-sub-families/:id/links	—	lib	Get links of a sub-sub-family.

---

Versioning

Method	Path	Role	Mode	Description
GET	/versioning/current/:nodeId	—	full	Current version of a node.
GET	/versioning/history/:sourceId	—	full	Version history. Query: since.
GET	/versioning/instances/:projectId	—	full	Project instances.
GET	/versioning/instances/context/:type/:id	—	full	Context instances.
GET	/versioning/diff/:instanceId	—	full	Diff an instance. Query: includeFieldDiffs.
GET	/versioning/drift/:projectId	—	full	Project drift analysis. Query: includeFieldDiffs. Rate limited (10/min).
GET	/versioning/content/:instanceId	—	full	Instance content.
POST	/versioning/instantiate	—	full	Instantiate a node. Body: InstantiateBody.

---

Divergence / Snapshots

Method	Path	Role	Mode	Description
GET	/divergence/snapshot	admin	full	Export instance snapshot. Query: include_content.
GET	/divergence/souche	admin	full	Get current souche.
GET	/divergence/souche/version	reader	full	Get souche version.
POST	/divergence/souche/update	admin	full	Update souche.
POST	/divergence/souche/init	admin	full	Initialize souche.
POST	/divergence/compare	admin	full	Compare two snapshots.
GET	/divergence/vs-souche	admin	full	Compare instance vs souche.
POST	/divergence/detect-cross-pollination	admin	full	Detect cross-pollination signals.
GET	/divergence/signals	admin	full	List cross-pollination signals.
POST	/divergence/signals/:id/promote	admin	full	Promote a signal.
POST	/divergence/signals/:id/ignore	admin	full	Ignore a signal.

---

Audit

Method	Path	Role	Mode	Description
POST	/audit/generate	admin	full	Generate an audit document.
GET	/audit	—	full	List audit documents. Query: type, projectId, limit.
GET	/audit/:id	—	full	Get an audit document.
GET	/audit/:id/verify	—	full	Verify an audit document.

---

Admin

Method	Path	Role	Mode	Description
GET	/admin/status	admin	full	System status (version, node/edge/document counts).
POST	/admin/reindex	admin	full	Reindex MeiliSearch.
GET	/admin/audit-trail	admin	full	Audit trail. Query: limit.

---

Diff

Method	Path	Role	Mode	Description
POST	/diff/snapshot	contributor	full	Capture a diff snapshot. Body: { scope? }.
GET	/diff/snapshots	—	full	List snapshots. Query: limit, offset.

---

Account

Method	Path	Role	Mode	Description
Various	/account/*	varies	lib	API key management, OAuth client management, provider credentials (admin).

---

Events (SSE)

Method	Path	Role	Mode	Description
Various	/events/*	—	full	Server-Sent Events token endpoint.

---

Health

Method	Path	Description
GET	/health	Health check (mounted outside /api, at server root). Returns { status: 'ok' }.