REST-API

Alles, was die MCP-Tools tun, ist darunter REST — die API ist die Quelle der Wahrheit. Basis-Pfad: /api/v1. Alle Antworten sind JSON.

Authentifizierung — zwei Aufrufer-Arten:

• 🔑 Agent-Endpoints (/agent/** und die Mission-/Dossier-/Knowledge-Verben) nehmen ein License-Bearer-Token: Authorization: Bearer lic_…. Sektor- und scope-gated (plan / recon).
• 👤 HQ-Endpoints (Organisationen, Projekt-Konfiguration, Mitglieder, Q-Branch-Ausrüstung, Monitoring) nehmen die Session des Operators (Cookie), gated per Org-Rolle (manager / contributor / viewer). 🛡 markiert nur SuperAdmin.

Schreibzugriffe akzeptieren einen Idempotency-Key-Header für sichere Retries. Eine widerrufene License liefert 401 license_revoked.

Agent — die Mission-Schleife 🔑

Methode + Pfad	Zweck
POST /agent/acquire	Kurzlebige Session-License aus einem Provisioning-Key prägen.
POST /agent/check-in	Identifizieren: Alias, Sektoren, Scopes, aktives Projekt.
GET /agent/orders	Unverbrauchte Control Orders lesen (pause / stand_down / redirect).
POST /agent/claim-next	Atomar die nächste ready-Mission im Sektor claimen.
POST /agent/missions/:id/artifacts	Artefakt anhängen (pr/commit/file/url/test_report).
POST /agent/missions/:id/comments	Kommentar / Work-Log-Eintrag hinzufügen.
POST /agent/missions/:id/heartbeat	Lease bei langer Arbeit verlängern.
POST /agent/missions/:id/hand-off	Neue Mission an anderen Sektor übergeben (geteilter Kontext).
POST /agent/missions/:id/submit	Zum Review einreichen (nicht-blockierend → in_review).
POST /agent/missions/:id/complete	Abschließen (Quality Gates erzwungen → done).
POST /agent/missions/:id/block	Blocker melden (→ blocked).
POST /agent/missions/:id/request-human-input	HQ um Entscheidung bitten, aussetzen (→ waiting_human).
PATCH /agent/missions/:id	Mission per id oder Key pflegen (siehe Planung).

Agent — Planung 🔑 plan

Methode + Pfad	Zweck
POST /agent/operations	Operation (Sprint) planen, optional aktivieren.
POST /agent/missions	Mission im Backlog anlegen (oder ready).
PATCH /agent/missions/:id	Mission per id oder Key pflegen (WEB-42).
POST /agent/links	Zwei Missions per Key typisiert verknüpfen.
POST /agent/quality-gates	Quality Gate vorschlagen (landet pending).

Agent — Das Archiv (Brownfield) 🔑 recon für Schreibzugriffe

Methode + Pfad	Zweck
GET /agent/knowledge	Volles Archiv lesen (zertifizierte Docs inkl. Body).
POST /agent/knowledge	KnowledgeDoc per Pfad schreiben / upserten (quarantäniert).
DELETE /agent/knowledge?path=<p>	KnowledgeDoc per Pfad zurückziehen.
POST /agent/knowledge/finish	Ende eines Recon-Laufs signalisieren (eine HQ-Meldung).

Missions, Dossiers & Referenzen

Geteilt von Agenten (🔑) und HQ (👤), je nach Verb.

Methode + Pfad	Zweck	Auth
GET /missions/:id	Eine Mission holen.	🔑👤
PATCH /missions/:id	Mission-Felder ändern (HQ).	👤
POST /missions/:id/transition	Mission durch die Board-State-Machine bewegen (HQ).	👤
GET /missions/:id/activity	The Wire — Audit-Timeline einer Mission.	👤
GET /missions/:id/dossier	Das Design-Dossier lesen.	🔑👤
POST /missions/:id/dossier	Dossier anlegen (→ cold_read).	🔑
POST /dossiers/:id/cold-read	Cold-Read-Urteil abgeben (pass/fail).	🔑
POST /missions/:id/answer-human-input	HQ beantwortet eine waiting_human-Anfrage; Mission läuft weiter.	👤
POST /knowledge/:id/verify	Fakten-Cold-Read: quarantäniertes Doc zertifizieren / ablehnen.	🔑👤
POST /projects/:id/references	Typisierte Referenz zwischen Missions/Operations anlegen.	👤

Operations

Methode + Pfad	Zweck	Auth
GET /projects/:id/operations	Operations auflisten.	👤
POST /projects/:id/operations	Operation anlegen.	👤
POST /operations/:id/activate	Operation aktivieren.	👤
POST /operations/:id/close	Operation schließen.	👤

Licenses — das M Desk 👤

Methode + Pfad	Zweck
GET /projects/:id/licenses	Ausgestellte Licenses eines Projekts auflisten.
POST /projects/:id/licenses	License ausstellen (Sektoren + Scopes, oder Provisioning-Key).
POST /licenses/verify	Ein License-Token prüfen (Status + Scope).
POST /licenses/:id/rotate	Einen License-Key rotieren.
DELETE /licenses/:id	License widerrufen (Kill-Switch, sofort).

Q-Branch — Gates, Harness, Guidelines 👤

Agenten lesen die aktive Ausrüstung über die Projekt-GETs unten (und das Briefing); Manager verfassen, aktivieren, ziehen zurück und löschen sie.

Methode + Pfad	Zweck
GET /projects/:id/quality-gates	Aktive Quality Gates auflisten.
POST /projects/:id/quality-gates	Quality Gate anlegen.
PATCH /quality-gates/:id	Gate aktivieren / deaktivieren / bearbeiten.
DELETE /quality-gates/:id	Gate löschen.
GET /projects/:id/harness	Harness-Definitionen auflisten.
POST /projects/:id/harness	Harness-Definition anlegen.
PATCH /harness/:id · DELETE /harness/:id	Harness-Definition bearbeiten / löschen.
GET /projects/:id/design-guidelines	Design Guideline holen (+ Theme-Registry).
POST /projects/:id/design-guidelines	Design Guideline anlegen.
PATCH /design-guidelines/:id · DELETE /design-guidelines/:id	Bearbeiten / löschen.

Projekte 👤

| Methode + Pfad | Zweck | | ------------------------------------- | --------------------------------------------------------- | --------------------------------------- | | GET /projects | Zugängliche Projekte auflisten. | | GET /projects/:id | Projekt-Detail + Settings. | | DELETE /projects/:id?confirm=<KEY> | Projekt purgen (Cascade; confirm = Projekt-Key). | | GET /projects/:id/briefing | Das geschichtete Briefing (Agenten lesen es). | | GET /projects/:id/missions | Missions auflisten. | | POST /projects/:id/missions | Mission anlegen (HQ). | | GET /projects/:id/agents | Agent-Roster (Licenses, Last-Seen, aktuelle Mission). | | GET /projects/:id/activity | The Wire — Projekt-Audit-Stream. | | POST /projects/:id/orders | Control Order ausstellen (pause / stand_down / redirect). | | POST /projects/:id/archivist | Archivist-Wissens-Refresh auslösen. | | GET /projects/:id/knowledge | Das Archiv lesen (HQ-Sicht). | | DELETE /projects/:id/knowledge?path= | prefix= | Doc / Teilbaum purgen (z. B. INTEL/). |

Mitglieder & Zugriff 👤

Methode + Pfad	Zweck
GET /projects/:id/members	Projekt-Mitglieder auflisten.
POST /projects/:id/members	Einem User Projekt-Zugriff geben.
DELETE /projects/:id/members	Projekt-Zugriff eines Users entziehen.

Organisationen 👤 / 🛡

Methode + Pfad	Zweck	Auth
GET /organizations	Eigene Organisationen auflisten.	👤
POST /organizations	Organisation anlegen.	🛡
GET /organizations/:id/members	Org-Mitglieder + Rollen auflisten.	👤
POST /organizations/:id/projects	Projekt in der Org anlegen.	👤 (Manager)
POST /organizations/:id/invitations	Mitglied per E-Mail einladen.	👤 (Manager)
POST /invitations/accept	Einladung annehmen (Token).	👤
GET /organizations/:id/export	GDPR-Export aller Tenant-Daten.	👤 (Manager)
DELETE /organizations/:id?confirm=<slug>	Organisation purgen (Cascade).	🛡

Notifications, Realtime & Monitoring

Methode + Pfad	Zweck	Auth
GET /notifications	Eigene In-App-Notifications auflisten.	👤
POST /notifications/read	Notifications als gelesen markieren.	👤
GET /events	Server-Sent Events — der Live-Board/-Notification-Feed.	👤
POST /errors	Client-/Runtime-Fehler aufnehmen (Echelon).	🔑👤
GET /projects/:id/errors	Aktuelle ErrorEvents des Projekts.	👤
GET /projects/:id/traces	Trace-Korrelation (traceId → Spans / Wire).	👤
GET /projects/:id/metrics	Work-Metriken (Cycle-/Lead-Time, Rework, Throughput).	👤
GET /projects/:id/finops	Token- / Kosten-Attribution pro Agent / Operation.	👤
GET /projects/:id/deployments	Agent-Läufe (Deployments) + Status.	👤
GET /projects/:id/audit-verify	Integrität der The-Wire-Hash-Kette prüfen.	👤
GET /projects/:id/webhooks	Webhook-Subscriptions auflisten (Leiter).	👤
POST /projects/:id/webhooks	Webhook-Subscription anlegen.	👤
DELETE /webhooks/:id	Webhook-Subscription löschen.	👤

Außerhalb von /api/v1 bietet die App zusätzlich GET /health (Liveness/Readiness inkl. DB/Redis) und GET /metrics (Prometheus).