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 außerhalb Citadels Sicht melden (→ `blocked`).
`POST /agent/missions/:id/resolve-blocker`	Solchen Blocker auflösen (→ `ready`); mit claim-next neu claimen.
`GET /agent/dossier?missionKey=…`	Dossier einer Mission per Key lesen (`null`, wenn keins).
`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`).

Org-weiter Recall — von Nachbarprojekten lernen 🔑 `plan` oder `recon`

Alles andere, was ein Agent liest, ist auf sein eigenes Projekt beschränkt. Diese beiden lesen über alle Projekte der Organisation der License hinweg, damit ein Scout lernen kann, wie ein Nachbarprojekt etwas gelöst hat, und ein Planer darauf aufbauen kann, statt es neu zu entdecken. Rein lesend — sie kopieren nichts irgendwohin; das Übernehmen einer Konvention ist ein eigener, bewusster Vorschlag.

Methode + Pfad	Zweck
`GET /agent/org/knowledge?q=`	Zertifiziertes Archiv-Wissen aller Org-Projekte; `q` filtert über Pfad/Summary/Body.
`GET /agent/org/equipment`	Die aktive Harness, Quality Gates und Design-Guidelines aller Org-Projekte.

Jede Zeile nennt ihr Herkunftsprojekt (projectKey, projectName). Die Organisation kommt aus der License selbst — ein Aufrufer kann die Grenze nie erweitern; ungeprüftes Wissen (quarantäniert/abgelehnt) und nicht-aktive Ausrüstung erscheinen nie. Wissen ist auf 200 Zeilen gedeckelt, mit einem truncated-Flag, damit ein abgeschnittenes Ergebnis nie für das ganze Bild gehalten wird. Eine License ohne beide Scopes (reine Ausführung) bekommt 403 — ein Field-Agent, der eine Mission bearbeitet, bleibt in seinem Projekt.

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 (angehängt; Status unverändert).	🔑
`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 `ErrorEvent`s 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.	👤

Skills — aus HQ installierbar 🔑👤

HQ liefert die /citadel-*-Claude-Skills mit dem Deploy aus — ein Rechner ohne Checkout des Repos kann sie so installieren. Skills und MCP-Tool-Oberfläche stammen aus demselben Commit: Was du hier holst, passt immer zu den Tools, die dieses HQ bietet. Genau deshalb gibt es keine Version pro Skill, sondern nur einen Content-Hash.

Endpoint	Zweck	Auth
`GET /skills`	Die ausgelieferten Skills auflisten — `name`, `description`, `sha` (sha256 der SKILL.md), `bytes` — plus HQ-`version` und `buildSha`.	🔑👤
`GET /skills/:name`	Die rohe `SKILL.md` (`text/markdown`), direkt nach `~/.claude/skills/<name>/SKILL.md` schreibbar.	🔑👤
`GET /skills/bundle`	Alle zusammen als ein ZIP (Einträge `<skill>/SKILL.md`) — der Download, auf den M Desk verlinkt.	🔑👤

Jede gültige License (auch ein Provisioning-Key) oder eine HQ-Session darf lesen. Den sha mit der lokalen Kopie vergleichen, um einen veralteten Skill zu erkennen — der Drift-Check, den man nicht vergessen kann.

Mit Browser — der schnellste Weg und der, den man einem neuen Nutzer gibt: M Desk → Skills installieren öffnen und auf den Download-Button klicken. Die HQ-Session authentifiziert ihn, es ist also gar kein Key im Spiel. Dann dort entpacken, wo Claude Code sucht:

bash

unzip -o ~/Downloads/citadel-skills-<version>.zip -d .claude/skills   # nur dieses Projekt
unzip -o ~/Downloads/citadel-skills-<version>.zip -d ~/.claude/skills # alle Projekte

Eine Kopie unter .claude/skills übersteuert die im Home-Verzeichnis — nimm das eine oder das andere, nie beides, sonst gewinnt stillschweigend eine veraltete Projektkopie.

Ohne Browser (Server, CI) — dieselben Dateien, einzeln:

bash

for s in citadel-init citadel-scout citadel-harness; do
  mkdir -p ~/.claude/skills/$s
  curl -fsSL -H "Authorization: Bearer ${CITADEL_LICENSE:-$CITADEL_TOKEN}" \
    "$CITADEL_URL/api/v1/skills/$s" -o ~/.claude/skills/$s/SKILL.md
done

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

REST-API ​

Agent — die Mission-Schleife 🔑 ​

Agent — Planung 🔑 plan ​

Org-weiter Recall — von Nachbarprojekten lernen 🔑 plan oder recon ​

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

Missions, Dossiers & Referenzen ​

Operations ​

Licenses — das M Desk 👤 ​

Q-Branch — Gates, Harness, Guidelines 👤 ​

Projekte 👤 ​

Mitglieder & Zugriff 👤 ​

Organisationen 👤 / 🛡 ​

Notifications, Realtime & Monitoring ​

Skills — aus HQ installierbar 🔑👤 ​