HELM AI Kernel HTTP API Reference

The public HTTP contract is anchored in api/openapi/helm.openapi.yaml. Runtime route ownership is mirrored in core/cmd/helm-ai-kernel/route_registry.go, enforced by route_auth.go, and wired into the local server through subsystems.go, contract_routes.go, receipt_routes.go, and console_routes.go.

Audience

Use this page if you call HELM AI Kernel over HTTP, generate a client from OpenAPI, configure auth headers, or debug route drift between the runtime and public docs.

Outcome

After this page you should know each public route family, its auth class, the source file that owns it, and the tests that catch route/OpenAPI drift.

Source Truth

This page is source-backed by api/openapi/helm.openapi.yaml, core/cmd/helm-ai-kernel/route_registry.go, core/cmd/helm-ai-kernel/route_auth.go, core/cmd/helm-ai-kernel/contract_routes.go, core/cmd/helm-ai-kernel/receipt_routes.go, core/cmd/helm-ai-kernel/console_routes.go, and route parity tests under core/cmd/helm-ai-kernel.

Contract Flow

flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        OpenAPI["api/openapi/helm.openapi.yaml"]
        Auth["route_auth.go"]
        Mux["serve/server mux"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        Registry["RuntimeRouteSpecs"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Handlers["contract, receipt, console, subsystem handlers"]
        Stores["receipts, boundary registry, services"]
        Response["JSON, SSE, or EvidencePack bytes"]
    end

    %% Operational Flow Edges
    OpenAPI --> Registry
    Registry --> Auth
    Auth --> Mux
    Mux --> Handlers
    Handlers --> Stores
    Stores --> Response

    %% Premium Styling Rules
    style Registry fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style Handlers fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Stores fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Response fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff

flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        OpenAPI["api/openapi/helm.openapi.yaml"]
        Auth["route_auth.go"]
        Mux["serve/server mux"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        Registry["RuntimeRouteSpecs"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        Handlers["contract, receipt, console, subsystem handlers"]
        Stores["receipts, boundary registry, services"]
        Response["JSON, SSE, or EvidencePack bytes"]
    end

    %% Operational Flow Edges
    OpenAPI --> Registry
    Registry --> Auth
    Auth --> Mux
    Mux --> Handlers
    Handlers --> Stores
    Stores --> Response

    %% Premium Styling Rules
    style Registry fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style Handlers fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Stores fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff
    style Response fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff

Runtime Auth Classes

The OpenAPI security blocks describe the external contract. route_auth.go is the runtime source for local OSS enforcement.

Public Route Families

api/openapi/helm.openapi.yaml is the public HTTP source truth. Routes mounted directly by subsystems.go but absent from OpenAPI are implementation or compatibility routes until they are added to the OpenAPI contract and parity tests.

helm-ai-kernel server runs API routes on HELM_PORT or 8080 by default. Its health server is separate and uses HELM_HEALTH_PORT or 8081 by default; helm-ai-kernel serve keeps the local policy boundary default at 127.0.0.1:7714.

Request And Response Notes

• JSON routes return HELM error envelopes through core/pkg/api/apierror.go.
• GET /api/v1/receipts/tail is an SSE stream. The HTTP route can stream without an agent query; the CLI wrapper helm-ai-kernel receipts tail requires --agent.
• POST /api/v1/evidence/export returns EvidencePack bytes and sets X-Helm-Evidence-Hash.
• Boundary and evidence verification endpoints are offline-first. Online ledger checks are additive and never replace native receipts or EvidencePack roots.

Validation

cd core
go test ./cmd/helm-ai-kernel -run 'Test.*Route|Test.*OpenAPI|Test.*Receipt|Test.*Boundary' -count=1
cd ..
make docs-truth

Troubleshooting