API Overview

Cordum exposes a REST API and a gRPC service.

For the full gateway REST reference (all registered HTTP routes, request/response schemas, auth requirements, and error behaviors), see docs/api-reference.md.

REST API

Base URL (local compose): http://localhost:8081

Authentication:

• HTTP header: X-API-Key: <key> (or JWT via Authorization: Bearer <token>)
• Session token: Authorization: Bearer <session-token> (from /api/v1/auth/login)
• Tenant header: X-Tenant-ID: <tenant>
• WebSocket stream: Sec-WebSocket-Protocol: cordum-api-key, <base64url> + ?tenant_id=<tenant> All endpoints require auth and a tenant header (including /api/v1/status).

Auth endpoints (public — no auth required):

• GET /api/v1/auth/config - Get authentication configuration
• POST /api/v1/auth/login - Login with user/password or API key

Auth endpoints (authenticated — require a valid session or API key):

• GET /api/v1/auth/session - Validate current session
• POST /api/v1/auth/logout - Logout (no-op for stateless auth)
• POST /api/v1/auth/password - Change password

User management (admin only):

• POST /api/v1/users - Create a new user

Common endpoints:

• Status/stream: GET /api/v1/status, WebSocket GET /api/v1/stream
• Jobs: GET /api/v1/jobs, GET /api/v1/jobs/{id}, GET /api/v1/jobs/{id}/stream (WebSocket), GET /api/v1/jobs/{id}/decisions, POST /api/v1/jobs, POST /api/v1/jobs/{id}/cancel, POST /api/v1/jobs/{id}/remediate
• Traces: GET /api/v1/traces/{id}
• Workflows: GET/POST /api/v1/workflows, GET/DELETE /api/v1/workflows/{id}
• Runs: POST /api/v1/workflows/{id}/runs, GET /api/v1/workflows/{id}/runs, GET /api/v1/workflow-runs, GET /api/v1/workflow-runs/{id}, GET /api/v1/workflow-runs/{id}/timeline, GET /api/v1/workflow-runs/{id}/chat, POST /api/v1/workflow-runs/{id}/chat, POST /api/v1/workflow-runs/{id}/rerun, DELETE /api/v1/workflow-runs/{id}
• Approvals: POST /api/v1/approvals/{job_id}/approve, POST /api/v1/approvals/{job_id}/reject
• Policy: POST /api/v1/policy/evaluate, POST /api/v1/policy/simulate, POST /api/v1/policy/explain, GET /api/v1/policy/snapshots, GET/PUT /api/v1/policy/bundles/{id}, POST /api/v1/policy/bundles/{id}/simulate, POST /api/v1/policy/publish, POST /api/v1/policy/rollback, GET /api/v1/policy/audit
• Config: GET /api/v1/config?scope=...&scope_id=..., POST /api/v1/config, GET /api/v1/config/effective
• Schemas: GET/POST /api/v1/schemas, GET /api/v1/schemas/{id}, DELETE /api/v1/schemas/{id}
• Packs: GET /api/v1/packs, GET /api/v1/packs/{id}, POST /api/v1/packs/install, POST /api/v1/packs/{id}/verify, POST /api/v1/packs/{id}/uninstall
• Marketplace: GET /api/v1/marketplace/packs, POST /api/v1/marketplace/install
• Artifacts: POST /api/v1/artifacts, GET /api/v1/artifacts/{ptr}
• Locks: GET /api/v1/locks, POST /api/v1/locks/acquire, POST /api/v1/locks/release, POST /api/v1/locks/renew
• DLQ: GET /api/v1/dlq, GET /api/v1/dlq/page, DELETE /api/v1/dlq/{job_id}, POST /api/v1/dlq/{job_id}/retry
• Memory pointers: GET /api/v1/memory?ptr=...

Job event streaming (WebSocket)

Tags: websocket, jobs, streaming

Use GET /api/v1/jobs/{id}/stream to receive job events for a single job. The connection uses the same API key WebSocket protocol as /api/v1/stream and requires X-Tenant-ID (or ?tenant_id=) for tenant scoping.

Edge (Compliance Firewall)

The /api/v1/edge/* routes govern AI-agent actions (sessions, executions, policy evaluate, approvals, events, evidence export, MCP upstreams, runtime ingest, and shadow-agent findings). The operator-oriented reference — including request/response shapes, error codes, and write-side caps — lives on the Edge REST API page. Core routes:

Method	Path
POST	/api/v1/edge/sessions
GET	/api/v1/edge/sessions
GET	/api/v1/edge/sessions/{session_id}
POST	/api/v1/edge/sessions/{session_id}/heartbeat
POST	/api/v1/edge/sessions/{session_id}/end
GET	/api/v1/edge/sessions/{session_id}/events
POST	/api/v1/edge/sessions/{session_id}/export
POST	/api/v1/edge/executions
GET	/api/v1/edge/executions/{execution_id}
POST	/api/v1/edge/executions/{execution_id}/end
GET	/api/v1/edge/executions/{execution_id}/events
POST	/api/v1/edge/evaluate
POST	/api/v1/edge/events
POST	/api/v1/edge/events/batch
GET	/api/v1/edge/approvals
GET	/api/v1/edge/approvals/{approval_ref}
POST	/api/v1/edge/approvals/{approval_ref}/approve
POST	/api/v1/edge/approvals/{approval_ref}/reject
POST	/api/v1/edge/approvals/{approval_ref}/wait
POST	/api/v1/edge/runtime/events
GET/POST	/api/v1/edge/mcp/upstreams (+ /list, /{name}, /{name}/enable, /{name}/disable)
GET	/api/v1/edge/shadow-agents (+ /{finding_id} and /ignore, /suppress, /resolve, /remediation)
GET/POST	/api/v1/edge/shadow/exception(s)
POST	/api/v1/edge/binary-integrity/events

gRPC API

The gateway exposes CordumApi (see core/protocol/proto/v1/api.proto). Use the generated SDK under sdk/ or the protobufs in core/protocol/pb/v1.

For message types and envelopes, see docs/AGENT_PROTOCOL.md and the CAP repo (github.com/cordum-io/cap/v2).

OpenAPI (canonical)

Validate the canonical HTTP OpenAPI spec:

make openapi

The source of truth is docs/api/openapi/cordum-api.yaml. When docs are published, the Swagger UI lives at /swagger/ and loads that single canonical spec.