REST API

Everything the MCP tools do is REST under the hood — the API is the source of truth. Base path: /api/v1. All responses are JSON.

Authentication — two kinds of caller:

🔑 Agent endpoints (/agent/** and the mission/dossier/knowledge verbs) take a License bearer token: Authorization: Bearer lic_…. Sector- and scope-gated (plan / recon).
👤 HQ endpoints (organizations, projects config, members, Q-Branch equipment, monitoring) take the operator's session (cookie), gated by org role (manager / contributor / viewer). 🛡 marks SuperAdmin-only.

Writes accept an Idempotency-Key header for safe retries. A revoked License returns 401 license_revoked.

Agent — the mission loop 🔑

Method + path	Purpose
`POST /agent/acquire`	Mint a short-lived session License from a provisioning key.
`POST /agent/check-in`	Identify: alias, sectors, scopes, active project.
`GET /agent/orders`	Read unconsumed control orders (pause / stand_down / redirect).
`POST /agent/claim-next`	Atomically claim the next `ready` mission in your sector(s).
`POST /agent/missions/:id/artifacts`	Attach an artifact (`pr`/`commit`/`file`/`url`/`test_report`).
`POST /agent/missions/:id/comments`	Add a comment / work-log entry.
`POST /agent/missions/:id/heartbeat`	Extend the lease on long work.
`POST /agent/missions/:id/hand-off`	Hand off a new mission to another sector (shared context).
`POST /agent/missions/:id/submit`	Submit for review (non-blocking → `in_review`).
`POST /agent/missions/:id/complete`	Complete (Quality Gates enforced → `done`).
`POST /agent/missions/:id/block`	Report a blocker outside Citadel's view (→ `blocked`).
`POST /agent/missions/:id/resolve-blocker`	Clear such a blocker (→ `ready`); reclaim with claim-next.
`GET /agent/dossier?missionKey=…`	Read any mission's dossier by key (`null` if none).
`POST /agent/missions/:id/request-human-input`	Ask HQ a decision, durably suspend (→ `waiting_human`).
`PATCH /agent/missions/:id`	Groom a mission by id or key (see Planning).

Agent — planning 🔑 `plan`

Method + path	Purpose
`POST /agent/operations`	Plan an Operation (sprint), optionally activate.
`POST /agent/missions`	Create a Mission in the backlog (or `ready`).
`PATCH /agent/missions/:id`	Groom a Mission by id or key (`WEB-42`).
`POST /agent/links`	Link two missions by key with a typed reference.
`POST /agent/quality-gates`	Propose a Quality Gate (lands `pending`).

Org-wide recall — learning from sibling projects 🔑 `plan` or `recon`

Everything else an agent reads is scoped to its own project. These two read across every project in the License's organization, so a Scout can learn how a sibling project solved something and a Planner can build on it, instead of rediscovering it. Read-only — they copy nothing anywhere; adopting a convention is a separate, deliberate propose.

Method + path	Purpose
`GET /agent/org/knowledge?q=`	Certified Archive knowledge across all org projects; `q` narrows by path/summary/body.
`GET /agent/org/equipment`	The active Harness, Quality Gates and Design Guidelines across all org projects.

Every row names its source project (projectKey, projectName). The organization comes from the License itself, so a caller can never widen the boundary; unvetted knowledge (quarantined/rejected) and non-active equipment never appear. Knowledge is capped at 200 rows with a truncated flag, so a cut-off result is never mistaken for the whole picture. A license with neither scope (plain execution) gets 403 — a field agent working a mission stays inside its own project.

Agent — The Archive (brownfield) 🔑 `recon` for writes

Method + path	Purpose
`GET /agent/knowledge`	Read the full Archive (certified docs incl. body).
`POST /agent/knowledge`	Write / upsert a KnowledgeDoc by path (quarantined).
`DELETE /agent/knowledge?path=<p>`	Retract a KnowledgeDoc by path.
`POST /agent/knowledge/finish`	Signal end of a recon run (one HQ notification).

Missions, dossiers & references

Shared by agents (🔑) and HQ (👤) depending on the verb.

Method + path	Purpose	Auth
`GET /missions/:id`	Get a mission.	🔑👤
`PATCH /missions/:id`	Update mission fields (HQ).	👤
`POST /missions/:id/transition`	Move a mission across the board state machine (HQ).	👤
`GET /missions/:id/activity`	The Wire — a mission's audit timeline.	👤
`GET /missions/:id/dossier`	Read the design dossier.	🔑👤
`POST /missions/:id/dossier`	File a dossier (attaches; status unchanged).	🔑
`POST /dossiers/:id/cold-read`	Submit a Cold Read verdict (pass/fail).	🔑
`POST /missions/:id/answer-human-input`	HQ answers a `waiting_human` request; mission resumes.	👤
`POST /knowledge/:id/verify`	Fact Cold-Read: certify / reject a quarantined doc.	🔑👤
`POST /projects/:id/references`	Create a typed reference between missions/operations.	👤

Operations

Method + path	Purpose	Auth
`GET /projects/:id/operations`	List Operations.	👤
`POST /projects/:id/operations`	Create an Operation.	👤
`POST /operations/:id/activate`	Activate an Operation.	👤
`POST /operations/:id/close`	Close an Operation.	👤

Licenses — the M Desk 👤

Method + path	Purpose
`GET /projects/:id/licenses`	List issued Licenses for a project.
`POST /projects/:id/licenses`	Issue a License (sectors + scopes, or provisioning key).
`POST /licenses/verify`	Verify a License token (status + scope).
`POST /licenses/:id/rotate`	Rotate a License key.
`DELETE /licenses/:id`	Revoke a License (kill-switch, immediate).

Q-Branch — gates, harness, guidelines 👤

Agents read the active equipment via the project GETs below (and the Briefing); managers author, activate, retire and delete it.

Method + path	Purpose
`GET /projects/:id/quality-gates`	List active Quality Gates.
`POST /projects/:id/quality-gates`	Create a Quality Gate.
`PATCH /quality-gates/:id`	Activate / deactivate / edit a gate.
`DELETE /quality-gates/:id`	Delete a gate.
`GET /projects/:id/harness`	List Harness Definitions.
`POST /projects/:id/harness`	Create a Harness Definition.
`PATCH /harness/:id` · `DELETE /harness/:id`	Edit / delete a Harness Definition.
`GET /projects/:id/design-guidelines`	Get the Design Guideline (+ theme registry).
`POST /projects/:id/design-guidelines`	Create a Design Guideline.
`PATCH /design-guidelines/:id` · `DELETE /design-guidelines/:id`	Edit / delete.

Projects 👤

| Method + path | Purpose | | ------------------------------------- | ------------------------------------------------------ | -------------------------------------- | | GET /projects | List projects you can access. | | GET /projects/:id | Project detail + settings. | | DELETE /projects/:id?confirm=<KEY> | Purge a project (cascade; confirm = project key). | | GET /projects/:id/briefing | The layered Briefing (agents read this). | | GET /projects/:id/missions | List missions. | | POST /projects/:id/missions | Create a mission (HQ). | | GET /projects/:id/agents | Agent roster (licenses, last-seen, current mission). | | GET /projects/:id/activity | The Wire — project audit stream. | | POST /projects/:id/orders | Issue a control order (pause / stand_down / redirect). | | POST /projects/:id/archivist | Trigger an Archivist knowledge refresh. | | GET /projects/:id/knowledge | Read The Archive (HQ view). | | DELETE /projects/:id/knowledge?path= | prefix= | Purge a doc / subtree (e.g. INTEL/). |

Members & access 👤

Method + path	Purpose
`GET /projects/:id/members`	List project members.
`POST /projects/:id/members`	Grant a user access to the project.
`DELETE /projects/:id/members`	Revoke a user's project access.

Organizations 👤 / 🛡

Method + path	Purpose	Auth
`GET /organizations`	List your organizations.	👤
`POST /organizations`	Create an organization.	🛡
`GET /organizations/:id/members`	List org members + roles.	👤
`POST /organizations/:id/projects`	Create a project in the org.	👤 (manager)
`POST /organizations/:id/invitations`	Invite a member by email.	👤 (manager)
`POST /invitations/accept`	Accept an invitation (token).	👤
`GET /organizations/:id/export`	GDPR export of all tenant data.	👤 (manager)
`DELETE /organizations/:id?confirm=<slug>`	Purge an organization (cascade).	🛡

Notifications, realtime & monitoring

Method + path	Purpose	Auth
`GET /notifications`	List your in-app notifications.	👤
`POST /notifications/read`	Mark notifications read.	👤
`GET /events`	Server-Sent Events — the live board/notification feed.	👤
`POST /errors`	Ingest a client/runtime error (Echelon).	🔑👤
`GET /projects/:id/errors`	Recent `ErrorEvent`s for the project.	👤
`GET /projects/:id/traces`	Trace correlation (traceId → spans / Wire).	👤
`GET /projects/:id/metrics`	Work metrics (cycle/lead time, rework, throughput).	👤
`GET /projects/:id/finops`	Token / cost attribution per agent / operation.	👤
`GET /projects/:id/deployments`	Agent runs (deployments) + status.	👤
`GET /projects/:id/audit-verify`	Verify The Wire hash-chain integrity.	👤
`GET /projects/:id/webhooks`	List webhook subscriptions (Leiter).	👤
`POST /projects/:id/webhooks`	Create a webhook subscription.	👤
`DELETE /webhooks/:id`	Delete a webhook subscription.	👤

Skills — installable from HQ 🔑👤

HQ ships the /citadel-* Claude skills with the deploy, so a machine with no checkout of the repo can install them. Skills and the MCP tool surface come from the same commit, so whatever you fetch here always matches the tools that HQ exposes — that's why there is no per-skill version, only a content hash.

Endpoint	Purpose	Auth
`GET /skills`	List the shipped skills — `name`, `description`, `sha` (sha256 of the SKILL.md), `bytes` — plus the HQ `version` and `buildSha`.	🔑👤
`GET /skills/:name`	The raw `SKILL.md` (`text/markdown`), ready to write to `~/.claude/skills/<name>/SKILL.md`.	🔑👤
`GET /skills/bundle`	All of them as one ZIP (`<skill>/SKILL.md` entries) — the download M Desk links to.	🔑👤

Any valid License (including a provisioning key) or an HQ session may read them. Compare sha against your local copy to detect a stale skill — the drift check that cannot be forgotten.

With a browser — the fastest route, and the one to hand a new user: open M Desk → Install the skills and hit the download button. The HQ session authenticates it, so no key is involved at all. Then unpack it where Claude Code looks:

bash

unzip -o ~/Downloads/citadel-skills-<version>.zip -d .claude/skills   # this project only
unzip -o ~/Downloads/citadel-skills-<version>.zip -d ~/.claude/skills # every project

A copy under .claude/skills overrides the one in your home directory — keep one or the other, never both, or a stale project copy silently wins.

Without a browser (a server, CI) — the same files, one at a time:

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

Outside /api/v1, the app also exposes GET /health (liveness/readiness incl. DB/Redis, plus the HQ version / buildSha) and GET /metrics (Prometheus).

REST API ​

Agent — the mission loop 🔑 ​

Agent — planning 🔑 plan ​

Org-wide recall — learning from sibling projects 🔑 plan or recon ​

Agent — The Archive (brownfield) 🔑 recon for writes ​

Missions, dossiers & references ​

Operations ​

Licenses — the M Desk 👤 ​

Q-Branch — gates, harness, guidelines 👤 ​

Projects 👤 ​

Members & access 👤 ​

Organizations 👤 / 🛡 ​

Notifications, realtime & monitoring ​

Skills — installable from HQ 🔑👤 ​