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 (→ blocked).
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).

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 (→ cold_read).	🔑
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 ErrorEvents 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.	👤

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