Skip to content
Cordum
Cordum
Documentation

API reference

The gateway is the canonical HTTP surface for Cordum. Route registration incore/controlplane/gatewayis the source of truth; the generated OpenAPI output is still a useful subset, but not the full route inventory.

Authentication
  • Protected REST routes expect X-API-Key or Authorization: Bearer ....
  • Protected /api/* routes also require X-Tenant-ID.
  • Public routes include GET /api/v1/auth/config, POST /api/v1/auth/login, and GET /health.
Idempotency

Job and workflow submission flows acceptIdempotency-Key,X-Idempotency-Key, or the equivalent query parameters. The common error body is{"error":"...","status":400}.

curl — submit a job
curl -sS -X POST https://localhost:8081/api/v1/jobs   --cacert ./certs/ca/ca.crt   -H "X-API-Key: $CORDUM_API_KEY"   -H "X-Tenant-ID: default"   -H "Content-Type: application/json"   -d '{
    "topic": "job.hello-pack.echo",
    "input": {"message": "hello from the gateway"}
  }'

Route groups

Auth and users

MethodPathDescription
GET/api/v1/auth/configPublic auth capability discovery.
POST/api/v1/auth/loginPublic login for user/password or API-key backed sessions.
GET/api/v1/auth/sessionValidate the active session or token.
POST/api/v1/auth/logoutInvalidate the active session.
POST/api/v1/auth/passwordChange the current user password.
GET/api/v1/auth/keysList API keys.

Jobs, workflows, and approvals

MethodPathDescription
POST/api/v1/jobsSubmit a job.
GET/api/v1/jobs/{id}Get job state, result pointers, safety, and output-safety metadata.
POST/api/v1/jobs/{id}/cancelCancel a running job.
POST/api/v1/jobs/{id}/remediateApply a remediation and resubmit.
POST/api/v1/workflowsCreate a workflow.
POST/api/v1/workflows/{id}/runsStart a workflow run.
GET/api/v1/workflow-runs/{id}/timelineRead the append-only run timeline.
POST/api/v1/workflow-runs/{id}/rerunRerun a workflow from a prior point.
POST/api/v1/approvals/{job_id}/approveResolve an approval-held job.
POST/api/v1/approvals/{job_id}/repairRepair a failed approval-held job and resubmit.

Config and policy

MethodPathDescription
GET/api/v1/configRead a config document by scope and scope_id.
PUT/api/v1/configWrite or update a config document.
GET/api/v1/config/effectiveRead merged config across scope hierarchy.
POST/api/v1/policy/evaluateEvaluate the active policy against a request.
POST/api/v1/policy/simulateSimulate policy behavior without applying changes.
POST/api/v1/policy/explainReturn matched rules and reasoning.
GET/api/v1/policy/bundlesList bundle documents used by Policy Studio.
POST/api/v1/policy/publishCapture and publish bundle snapshots.

Pools, workers, packs, schemas, and status

MethodPathDescription
GET/api/v1/workersList workers and current health snapshots.
GET/api/v1/poolsList worker pools and routing state.
PUT/api/v1/pools/{name}Create a pool.
PATCH/api/v1/pools/{name}Update pool configuration.
POST/api/v1/pools/{name}/drainDrain a pool.
GET/api/v1/packsList installed packs.
GET/api/v1/marketplace/packsRead merged pack catalogs with install state.
GET/api/v1/schemasList registered schemas.
GET/api/v1/dlqList DLQ entries.
GET/api/v1/statusGateway status plus NATS and Redis connectivity.

Licensing

MethodPathDescription
GET/api/v1/licenseRead the active license tier and entitlements.
GET/api/v1/license/usageRead current usage against tier limits (workers, RPS).
POST/api/v1/license/reloadHot-reload the license from disk or token without restarting.

Telemetry

MethodPathDescription
GET/api/v1/telemetry/statusRead the current telemetry mode and consent state.
GET/api/v1/telemetry/inspectInspect what telemetry data would be collected.
GET/api/v1/telemetry/exportExport collected telemetry data.
GET/api/v1/telemetry/usageRead aggregate usage metrics.
POST/api/v1/telemetry/consentUpdate the telemetry consent mode.

MCP and realtime streaming

MethodPathDescription
GET/mcp/sseOpen an MCP SSE session.
POST/mcp/messageSend JSON-RPC requests and notifications.
GET/mcp/statusInspect MCP runtime status.
GET/api/v1/mcp/sseAuthenticated API-prefixed alias for the SSE route.
WebSocket stream auth
const encoded = base64url(apiKey);
const ws = new WebSocket(
  "wss://localhost:8081/api/v1/stream",
  ["cordum-api-key", encoded],
);
Notes
  • The dashboard derives its websocket URL from the API base URL and listens on /api/v1/stream.
  • MCP HTTP mode uses /mcp/sse and /mcp/message with the same auth context.
  • The generated Swagger UI in /docs/api/openapi is helpful, but the gateway code currently exposes more routes than the generated subset.
Source of truth:docs/api-reference.md