API HTTP

Liste des routes HTTP exposées par le serveur Fastify d’arka-deck, groupées par domaine fonctionnel.

Source de vérité : adapters/inbound/web/server/src/routes/.

---

Middleware global

• CORS : localhost + plages RFC1918 en mode LAN
• CSP : script-src 'self', connect-src localhost + LAN
• Rate limit : 900 writes/min (exemptions GET/loopback)
• Token : header X-Arka-Token obligatoire en mode LAN
• HSTS : désactivé (HTTP local, pas TLS)
• Request ID : UUID par requête, loggé

---

Système

Méthode	Path	Description
GET	/api/health	Health check (statut + version)
GET	/api/system/*	Métadonnées système (boot, token)
GET	/api/i18n/:lang	Traductions UI
GET	/api/preferences	Préférences utilisateur
PUT	/api/preferences	Mettre à jour les préférences

---

Workspaces et projets

Méthode	Path	Description
GET	/api/workspaces	Liste
GET	/api/workspaces/:id	Détail
POST	/api/workspaces	Créer
PUT	/api/workspaces/:id	Modifier
DELETE	/api/workspaces/:id	Supprimer (refuse si non-vide)
GET	/api/workspaces/:id/projects	Projets du workspace
GET	/api/projects	Liste tous projets
GET	/api/projects/:id	Détail
GET	/api/projects/find-by-cwd?path=...	Détection auto par marker
POST	/api/projects	Créer (vérifie allowlist + workspace)
PUT	/api/projects/:id	Modifier (path immuable)
DELETE	/api/projects/:id	Forget (204)
DELETE	/api/projects/:id?purge=true	Purge complet
POST	/api/projects/:id/touch	Mettre à jour lastUsedAt

---

Catalogue Cortex

Méthode	Path	Description
GET	/api/catalogue/profiles	Liste des profils HYOS
GET	/api/catalogue/profiles/:id	Détail d’un profil
DELETE	/api/catalogue/cache	Vider le cache catalogue

---

Chat et sessions

Méthode	Path	Description
POST	/api/chat/sessions	Démarrer une session
POST	/api/chat/sessions/:id/send-message	Envoyer un tour (SSE stream)
GET	/api/chat/sessions/:id/stream	Stream SSE de la session
GET	/api/chat/sessions	Lister les sessions d’un projet
GET	/api/chat/sessions/:id	Détail session

---

Mémoire

Méthode	Path	Description
GET	/api/memory/:projectId	Vue d’ensemble mémoire projet
POST	/api/memory/:projectId/entry	Capturer une entrée
GET	/api/memory/:projectId/entries	Lister les entrées

---

ArkaDoc

Méthode	Path	Description
GET	/api/arkadoc/:projectId	Liste documents
GET	/api/arkadoc/:projectId/:docId	Détail document
PATCH	/api/arkadoc/:projectId/:docId/status	Modifier statut
GET	/api/arkadoc/:projectId/:docId/render	Rendu Markdown

---

Documentation projet

Méthode	Path	Description
GET	/api/projects/:id/documentation/documents	Liste filtrée des livrables ArkaDoc du projet
GET	/api/projects/:id/documentation/documents/:docId/index	Index de consultation d’un document
GET	/api/projects/:id/documentation/documents/:docId/outline	Plan lisible du document
GET	/api/projects/:id/documentation/documents/:docId/neighbors	Relations entrantes/sortantes du document
GET	/api/projects/:id/documentation/documents/:docId/full	Lecture complète du document
GET	/api/projects/:id/documentation/documents/:docId/blocks/:blockId	Lecture d’un bloc précis

Ces routes lisent les documents ArkaDoc réels du projet. Elles servent l’UI Documentation et les tools MCP agents qui naviguent par index/blocs avant d’ouvrir un document complet.

---

Agent action cards & Cortex Actions

Méthode	Path	Description
GET	/api/projects/:id/agent-action-cards	Cartes pour le projet/la session, filtrables par run
POST	/api/projects/:id/agent-action-cards/:cardId/select	Sélectionner une carte avant tour ou commande d’orchestration
GET	/api/cortex-actions/tree	Arbre des blocs catalogue
GET	/api/cortex-actions/search?q=	Rechercher des blocs catalogue
GET	/api/cortex-actions/:type/:id/content	Lire le contenu d’un bloc catalogue
POST	/api/cortex-actions/:projectId/select	Enregistrer une sélection scopée projet pour le prochain tour
POST	/api/cortex-actions/:projectId/exec-log	Enregistrer un log d’exécution scopé projet
GET	/api/cortex-actions/:projectId/options	Lire les options Cortex Actions du projet
PUT	/api/cortex-actions/:projectId/options	Modifier les options Cortex Actions du projet
GET	/api/cortex-actions/:projectId/favorites	Lire les favoris projet
POST	/api/cortex-actions/:projectId/favorites	Ajouter un favori projet
DELETE	/api/cortex-actions/:projectId/favorites/:type/:id	Retirer un favori projet
POST	/api/cortex-actions/:projectId/favorites/suggest	Lancer le worker de suggestion scopé projet

Les cards d’approbation de dispatch sont générées depuis les documents ArkaDoc task ready et excluent les assignations uniquement QA. Les ids de cards existants sont réutilisés au rafraîchissement pour éviter les doublons.

---

Squad et orchestration

Méthode	Path	Description
GET	/api/squads/:projectId	Liste squads du projet
POST	/api/squads	Créer une squad
POST	/api/squads/:id/materialize-leader	Recruter le Pack Leader
GET	/api/orchestration/:projectId/missions	Liste missions
POST	/api/orchestration/missions	Démarrer mission
GET	/api/orchestration/missions/:id	État mission

---

Mission Guardian

Méthode	Path	Description
GET	/api/mission-guardian/:projectId/state	État phases + gates
POST	/api/mission-guardian/:projectId/decision	Enregistrer décision
GET	/api/mission-guardian/:projectId/evidence	Preuves capturées

Mission Guardian est l’autorité de gate. Mission Control est exposé aux agents via les surfaces runtime context/MCP.

---

Providers et runtimes

Méthode	Path	Description
GET	/api/providers/manifests	Manifests statiques (catalogue)
GET	/api/providers/instances	Liste instances configurées
POST	/api/providers/instances	Créer une instance
PUT	/api/providers/instances/:id	Modifier
DELETE	/api/providers/instances/:id	Supprimer
POST	/api/providers/instances/:id/test	Tester (check + live)
GET	/api/cortex-lite/projects/:id/state	État Cortex Lite projet
POST	/api/cortex-lite/projects/:id/sync	Synchroniser
GET	/api/cortex-runtime/status	Readiness endpoint runtime
POST	/api/cortex-runtime/sync	Synchroniser atoms/prompts runtime
GET	/api/projects/:id/runtime/snapshot	Snapshot runtime projet pour agents
GET	/api/projects/:id/runtime/docs	Résumés ArkaDoc runtime
GET	/api/projects/:id/runtime/docs/:docId	Détail ArkaDoc runtime
POST	/api/projects/:id/runtime/docs/search	Recherche ArkaDoc runtime
GET	/api/projects/:id/runtime/tasks	Résumés tasks runtime
GET	/api/projects/:id/runtime/memory	Mémoire runtime par scope

Pour le dispatch de task, les résumés runtime exposent l’id ArkaDoc comme dispatch_task_id. Un task_id métier du payload peut être affiché comme business_task_id, mais les commandes de dispatch doivent utiliser l’id ArkaDoc.

---

Connecteurs

Méthode	Path	Description
GET	/api/connectors/manifests	Connecteurs disponibles
GET	/api/connectors/installations/:projectId	Installations du projet
POST	/api/connectors/installations	Activer un connecteur
DELETE	/api/connectors/installations/:id	Désactiver
POST	/api/connectors/oauth/start	Démarrer flow OAuth
GET	/api/connectors/oauth/callback	Callback OAuth
POST	/api/connectors/executions	Exécuter une action
GET	/api/connectors/audit-log/:projectId	Audit trail

---

MCP projet

Méthode	Path	Description
GET	/api/projects/:id/mcp-connectors	Liste des MCP attachés au projet
POST	/api/projects/:id/mcp-connectors	Créer un MCP projet custom HTTP/SSE
POST	/api/projects/:id/mcp-connectors/from-installation/:installationId	Attacher le MCP exposé par une installation connecteur
GET	/api/projects/:id/mcp-connectors/:connectorId	Détail d’un MCP projet
PATCH	/api/projects/:id/mcp-connectors/:connectorId	Modifier nom, endpoint ou politique tools
POST	/api/projects/:id/mcp-connectors/:connectorId/test	Tester la disponibilité du serveur MCP
POST	/api/projects/:id/mcp-connectors/:connectorId/enable	Activer l’exposition aux agents du projet
POST	/api/projects/:id/mcp-connectors/:connectorId/disable	Désactiver l’exposition aux agents du projet
DELETE	/api/projects/:id/mcp-connectors/:connectorId	Retirer le MCP du projet

Les MCP projet sont scopés à un projet et exposés au runtime provider sous un nom connector_*. Les endpoints distants doivent utiliser HTTPS ; le HTTP est accepté uniquement en loopback. Les secrets ne sont pas copiés dans la configuration MCP projet.

---

Workers

Méthode	Path	Description
POST	/api/workers/:name/invoke	Invoquer un worker (1-shot)
GET	/api/workers/:name/logs	Logs d’invocation

---

Filesystem (allowlist)

Méthode	Path	Description
GET	/api/fs/read?path=...	Lire un fichier
POST	/api/fs/write	Écrire (allowlist)

---

Voir aussi

• CLI : ./cli
• Variables d’environnement : ./variables-env
• Politique URL runtime : ../architecture/stockage, ADR 0006