Console API

Audience

Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

Source Truth

• Public route: product/console-api
• Source document: helm-ai-enterprise/docs/public/product/console-api.md
• Control-plane router: apps/controlplane/internal/http/router.go
• Console route registry: apps/controlplane/internal/console/route_registry.go
• Console handler mount: apps/controlplane/internal/console/facade.go
• OpenAPI source: api/openapi/helm.openapi.yaml
• Public manifest: helm-ai-enterprise/docs/public-docs.manifest.json
• Source inventory: helm-ai-enterprise/docs/source-inventory.manifest.json
• Validation: corepack pnpm run docs:coverage, corepack pnpm run docs:truth, and go test ./apps/controlplane/internal/http ./apps/controlplane/internal/console

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

Troubleshooting

The HELM Operator Console uses apps/controlplane as its single browser API backend. All endpoints require authenticated session authority unless explicitly listed as public. The canonical Console route registry is apps/controlplane/internal/console/route_registry.go; this page is a public summary, not a second contract.

Authentication

Session, refresh, reauth, and WebAuthn ceremony endpoints live under /api/auth/*. Workspace-scoped routes derive tenant and workspace authority on the server. Public proof routes bypass private session context only when they return redaction-safe metadata.

Console/API Matrix

Endpoint Reference

Health And Session

Public Proof And Replay

Workspace And Operator State

Packs, Marketplace, Ops, And Billing

Console Route Registry Areas

Error Responses

Canonical Console /api/v1/* handlers return JSON errors with this shape:

{
  "error": "detail",
  "message": "operator-safe summary",
  "code": 400
}

Some compatibility handlers still use Go http.Error until they are converted. Do not document a route as fully canonical unless it is covered by the controlplane route registry and route-contract tests.

Redaction Boundary

Public Console API examples may include route names, sample IDs, receipt IDs, bundle IDs, hashes, public signing keys, and verification statuses. They must not include session cookies, customer payloads, provider credentials, private signing keys, raw evidence bundle contents, or production database URLs.

Public proof routes are read-only. Workspace, ops, billing, audit, and marketplace mutation routes require session authority and should not be presented as public integration endpoints.

Contract Rule

New Console capability work must be added to apps/controlplane, reflected in apps/controlplane/internal/console/route_registry.go when it is part of the Console /api/v1 surface, consumed through the canonical frontend API client layer, and covered by route-contract tests. Do not reintroduce a second browser backend or undocumented public proof surface.

Diagram

flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        source["Operator Console API"]
        auth["Session and WebAuthn"]
        snapshot["Authoritative Snapshot"]
        ops["Governed Ops"]
        controlplane["apps/controlplane"]
        registry["Route Registry and Contract Tests"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        proof["Public Proof"]
    end

    %% Operational Flow Edges
    source --> auth
    source --> snapshot
    source --> proof
    source --> ops
    auth --> controlplane
    snapshot --> controlplane
    proof --> controlplane
    ops --> controlplane
    controlplane --> registry

    %% Premium Styling Rules
    style proof fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff

flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        source["Operator Console API"]
        auth["Session and WebAuthn"]
        snapshot["Authoritative Snapshot"]
        ops["Governed Ops"]
        controlplane["apps/controlplane"]
        registry["Route Registry and Contract Tests"]
    end

    subgraph Ledger["4. Tamper-Evident Ledger Plane"]
        proof["Public Proof"]
    end

    %% Operational Flow Edges
    source --> auth
    source --> snapshot
    source --> proof
    source --> ops
    auth --> controlplane
    snapshot --> controlplane
    proof --> controlplane
    ops --> controlplane
    controlplane --> registry

    %% Premium Styling Rules
    style proof fill:#2f855a,stroke:#276749,stroke-width:2px,color:#fff