API Reference

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

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

Interface Map

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

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

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:

Individual API Classification

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

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