---
title: "API Reference"
canonical: "https://helm.docs.mindburn.org/reference"
source: "helm-ai-enterprise/docs/11_API_REFERENCE.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/11_API_REFERENCE.md"
section: "reference"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-05"
checksum_sha256: "sha256:f339b0209d8aa7a854d1d87b4af4831ad7aed67f3c9a0d04ed3bf70213c5d287"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# HELM Reference Hub

This hub organizes HELM interfaces across the control plane, Console `/api/v1` surface, Basic/commercial API, generated OpenAPI contract, WebSocket telemetry, SDKs, and verification tooling. It is a map. Exact request and response fields belong to the owning source files, OpenAPI contract, schemas, and route tests.

## Audience

Use this page if you are integrating with HELM, generating a client, debugging a denied action, operating Console, or evaluating the commercial API boundary.

## Outcome

After this page you should know which public route family owns each integration path, which source file is authoritative, which routes are Console, Basic, commercial, proof, or generated OpenAPI surfaces, and which validation commands catch drift before docs are published.

## Source Truth

| Surface | Source truth | Public docs |
| --- | --- | --- |
| Control-plane router | `apps/controlplane/internal/http/router.go` | This page and `docs/audit/API_ENDPOINTS.md`. |
| Console `/api/v1` registry | `apps/controlplane/internal/console/route_registry.go` | `docs/public/product/console-api.md`. |
| Console handlers | `apps/controlplane/internal/console/facade.go`, `apps/controlplane/internal/console/*_routes.go` | `docs/public/product/console.md`. |
| Individual API | `commercial/basic/server.go`, mounted by `apps/helm-ai-enterprise/main.go` at `/api/basic/` | `docs/public/product/agent-skills-governance.md`. |
| Commercial gateway | `apps/helm-ai-enterprise/main.go`, `apps/helm-ai-enterprise/*.go` | `docs/COMMERCIAL_OVERVIEW.md`, `docs/COMMERCIAL_DEPLOY.md`. |
| OpenAPI source | `api/openapi/helm.openapi.yaml` | `docs/api/openapi.yaml` generated public mirror. |
| Schema registry | `protocols/json-schemas/SCHEMA_INDEX.md`, `docs/audit/CONTRACT_REGISTRY.md` | `docs/12_SCHEMA_REFERENCE.md`. |
| CLI and verifier | `packages/mindburn-helm-ai-enterprise-cli/src/**`, `core/cmd/helm-ai-enterprise-*` | `docs/13_CLI_REFERENCE.md`. |

If this page disagrees with a route registry, handler, OpenAPI source, or contract test, the source artifact wins.

## Interface Map

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        app["Application / SDK"]
        openapi["OpenAPI-backed HTTP contract"]
        operator["HELM Console"]
        cp["apps/controlplane router"]
        consoleRegistry["Console /api/v1 route registry"]
        basic["/api/basic router"]
        cli["CLI and verifier"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        commercial["HELM AI Enterprise gateway"]
        enterprise["billing, SCIM, provisioning, trial, audit"]
        ops["ops, billing, audit, packs"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        redacted["redaction-safe metadata"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        proof["public proof and replay routes"]
        receipts["audit and evidence links"]
        evidence["evidence bundles"]
    end

    %% Operational Flow Edges
    app --> openapi
    operator --> cp
    cp --> consoleRegistry
    commercial --> basic
    commercial --> enterprise
    cp --> proof
    cp --> ops
    basic --> receipts
    proof --> redacted
    cli --> evidence

    %% Premium Styling Rules
    style commercial fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style enterprise fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style proof fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style ops fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff
    style receipts fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style redacted fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style evidence fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
```


## Console/API Matrix

| API family | Route shape | Owner | Auth boundary | Use when |
| --- | --- | --- | --- | --- |
| Health | `/health`, `/health/live`, `/health/ready` | `apps/controlplane/internal/http/router.go` | Public | Process and readiness probes. |
| Auth/session | `/api/auth/*`, `/api/session` | `internal/auth`, `internal/platform` | Session or ceremony-specific public login begin/finish | Browser session, refresh, reauth, and WebAuthn ceremonies. |
| Bootstrap/workspaces | `/api/bootstrap*`, `/api/workspaces*` | `internal/platform` | Session | Tenant/workspace bootstrap and member management. |
| Console canonical routes | `/api/v1/workspaces*`, `/api/v1/marketplace/connectors*`, `/api/v1/verify`, `/api/v1/replays*`, `/api/v1/signing-key` | `internal/console/route_registry.go` | Session except public signing key, verify, and replay reads | Console workspace operations, policy, approvals, receipts, evidence, legal holds, and connector marketplace flows. |
| Public proof | `/api/public/verify/{receiptId}`, `/api/public/evidence/{bundleId}`, `/api/public/approval/{approvalId}`, `/api/public/orgs/{org_id}/*` | `internal/platform`, `internal/runtime` | Public, redacted, read-only | External verification and evaluator-safe proof views. |
| Ops and connectors | `/api/ops*`, `/api/connectors*` | `internal/ops` | Session | Incidents, plans, blast radius, freeze/throttle/resume/quarantine/resync, drift, and shim activation. |
| Billing/entitlements | `/api/billing*`, `/api/entitlements*` | `internal/billing`, `internal/registry` | Session with tenant path checks where a tenant ID appears in the path | Plans, usage, budgets, and entitlement checks. |
| Audit/export | `/api/audit*`, `/api/evidence/{handle}` | `internal/audit`, `internal/evidence` | Session unless explicitly public | Audit bundles, pack build/export, verification, and evidence handles. |
| Runtime/research/genesis | `/api/org/runtime*`, `/api/org/research*`, `/api/org/genesis*` | `internal/runtime`, `internal/researchruntime`, `internal/genesis` | Mixed public read routes and session/private routes | Runtime state sync, public org status, research runtime, and genesis ceremony flows. |
| WebSocket hints | `/ws/console`, `/ws/telemetry` | `internal/ws` | Deployment/session dependent | Realtime hints; snapshot/API fetches remain authoritative. |
| Individual commercial API | protected `/api/basic` route family | `commercial/basic/server.go` | Commercial auth middleware | Individual workspaces, members, API keys, approvals, evidence, incidents, budgets, plans, blast radius, and notifications. Exact customer routes stay in authenticated customer docs. |
| Commercial admin/gateway | protected commercial route families | `apps/helm-ai-enterprise/main.go`, `apps/helm-ai-enterprise/provisioning.go`, `apps/helm-ai-enterprise/trial.go`, `apps/helm-ai-enterprise/scim_routes.go`, `apps/helm-ai-enterprise/activation.go`, `commercial/admin`, `commercial/billing`, `commercial/metering`, `commercial/retention`, `commercial/compliance` | Public only for explicitly allowlisted status/webhook routes; otherwise protected | Commercial activation, trial, identity provisioning, admin, compliance, and billing gateway flows. Exact operator and customer routes stay in authenticated customer or staff docs. |

Do not add new public docs for routes that are not registered by `apps/controlplane/internal/http/router.go`, `apps/controlplane/internal/console/route_registry.go`, `commercial/basic/server.go`, or `apps/helm-ai-enterprise/*.go`.

Treat the protected Basic route family as Basic-owned and keep billing,
provisioning, trial, identity provisioning, admin, and compliance routes in
the commercial gateway owner set above.
Compatibility aliases registered by `apps/controlplane/internal/http/router.go`
must be labeled as compatibility-only before they appear in public reference
tables.

## Generated OpenAPI

`api/openapi/helm.openapi.yaml` is the source OpenAPI contract. `docs/api/openapi.yaml` is the generated public mirror. Regenerate the mirror from the source; do not edit the mirror by hand.

The OpenAPI contract covers the public HTTP contract for proxying, approval, proof/evidence, conformance, org runtime, bootstrap/workspace, ops, and verification shapes. SDK docs and examples should link to the OpenAPI source or generated mirror when exact fields matter.

## Console `/api/v1` Registry

The Console route registry groups canonical routes by area:

| Area | Route examples | Notes |
| --- | --- | --- |
| Workspaces | `POST /api/v1/workspaces`, `GET /api/v1/workspaces/{id}` | Workspace CRUD. |
| Runs and receipts | `POST /api/v1/workspaces/{id}/runs`, `GET /api/v1/workspaces/{id}/runs/{run_id}`, `GET /api/v1/workspaces/{id}/runs/{run_id}/receipts` | Runs are receipted with policy and evidence metadata. |
| Approvals | `GET /api/v1/workspaces/{id}/approvals`, `POST /api/v1/workspaces/{id}/approvals/{approval_id}/resolve` | Approval records do not bypass kernel evaluation. |
| Tools and policy | `/tools`, `/policy/draft`, `/policy/compile`, `/policy/activate`, `/policy/active` | Policy activation must remain auditable. |
| Tasks/actions/channels | `/tasks*`, `/actions*`, `/channels*` | Operator action and collaboration surfaces. |
| Skills and knowledge | `/skills*`, `/knowledge/*` | Candidate promotion/rejection and knowledge claim review. |
| Evidence/legal/jurisdiction | `/evidence/*`, `/legal-holds*`, `/jurisdictions` | Export and retention-sensitive flows. |
| Public replay/verify | `/api/v1/replays*`, `/api/v1/verify`, `/api/v1/signing-key` | Public-safe verification surfaces. |
| Marketplace | `/api/v1/marketplace/connectors*` | Connector read, install, and disable flows behind authorization. |

## Individual API Classification

The Basic router is a commercial API mounted at `/api/basic/`. It is not the Console `/api/v1` registry.

| Class | Routes | Source |
| --- | --- | --- |
| Workspace administration | `/api/basic/workspaces`, `/api/basic/projects`, `/api/basic/environments`, `/api/basic/members` | `commercial/basic/server.go`, `workspace.go`, `rbac.go`. |
| Keys and approvals | `/api/basic/keys`, `/api/basic/approvals` | `apikey.go`, `approval.go`, `approval_audit.go`. |
| Evidence and health | `/api/basic/evidence`, `/api/basic/health` | `evidence_index.go`, `server.go`. |
| Incidents and budgets | `/api/basic/incidents`, `/api/basic/incidents/transition`, `/api/basic/budget/record`, `/api/basic/budget/summary` | `handler_incidents.go`, `handler_budget.go`. |
| Plans and blast radius | `/api/basic/plans`, `/api/basic/plans/approve`, `/api/basic/plans/commit`, `/api/basic/blastradius` | `handler_plans.go`, `handler_blastradius.go`. |
| Notifications | `/api/basic/notifications/subscribe`, `/api/basic/notifications/emit` | `handler_notifications.go`, `notifications.go`. |
| Runtime bridge | `/api/basic/runtime/start`, `/api/basic/runtime/stop`, `/api/basic/runtime/status` | `runtime_bridge.go`. |

## Redaction Boundary

Public examples may include route names, sample tenant/workspace IDs, receipt IDs, hash values, public signing keys, and redacted evidence metadata. They must not include session cookies, private tenant payloads, customer data, provider credentials, private signing keys, production database URLs, or raw evidence exports that contain private data.

Public proof routes should return verification status and metadata needed to validate a receipt. Workspace routes should require session authority and should not be described as public.

## Diagnostics Packet

When reporting an integration problem, collect:

- HELM version and deployment mode;
- endpoint, SDK method, or CLI command;
- request correlation ID;
- receipt ID or denial reason code;
- policy bundle ref or hash;
- sanitized request shape without secrets or private payloads;
- verifier output when an evidence pack exists.

## Versioning

HELM should preserve existing public integration paths unless a security fix requires a break. New fields should be additive where possible. Breaking changes need a migration note, compatibility section, changelog entry, and generated client update.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| Route exists in code but not public docs | Route registry or endpoint registry changed without doc update | Update `docs/audit/API_ENDPOINTS.md`, this page, and the relevant public product page. |
| Generated client rejects a field | OpenAPI or SDK is older than runtime | Regenerate or pin to the matching HELM version. |
| Console page has stale data after WebSocket event | WebSocket messages are hints only | Refetch `/api/snapshot` or the owning API route. |
| Public proof exposes too much data | Redaction boundary was not applied | Treat it as a security bug; reduce response to verification metadata. |
| Individual route behavior is unclear | Console and Individual APIs were conflated | Check `commercial/basic/server.go` and the Individual governance page. |