API operating reference

thumb:'up'|'down'?, comment?, ab_test_id? } Persists a row to the event-store under workflow_id=AB_FEEDBACK_WORKFLOW so ab-metrics.aggregate() can read it. Also fans the row to the W720 self-improvement queue when deps.selfImprovement.enqueue is wired.

Body: { namespace, force?:boolean, thresholds?:{...} } When `force=true` we bypass the decide() gate and promote variant_b immediately. Otherwise we run the full evaluate() pipeline and only promote when decide() returns 'promote'.

Returns: {ok, ab_test_id, request_hash, arm, frozen, reason, version} Auth-gated via req.tenant_record. Tenant fence forced from session, never from request body. Distinct prefix /v1/ab-tests/* so parallel agents on cannot collide on these route paths.

Enterprise control-center intake alias. This exposes the advertised canonical event envelope directly from the account surface.

/v1/account/audit-log surfaces the audit ledger for the calling tenant. The audit-log.html page renders {entries:[{at,actor,op,payload}]}. added ?format=csv (defaults to json) so the page's export button and `kolm audit --format csv` CLI verb hit the same route. Also added ?since=<iso|epoch> filter so the CLI can scope to a recent window.

tenant's audit ledger (no body). Returns { ok, verified, chain_length, broken_at? } so the audit-log page can render a green/red state.

Billing summary the account-billing page reads: plan, status, period, credit balance, tax fields, Full Readiness entitlements, continuous subscription, recent invoices, dunning state, and whether the portal can be opened.

M13 - capture VAT number / tax id (+ optional company + country) for the invoice header and Stripe automatic_tax. Tenant-fenced + audited.

M9 - open a Stripe Billing Portal session so the customer can self-serve payment-method updates, cancellation/downgrade, and receipt downloads. 503 when no Stripe secret key is configured; 409 when the tenant has no Stripe customer yet (no paid subscription has ever been created for them).

Self-serve cancel / downgrade-to-free. Any paid tenant can drop to the free tier without contacting anyone.

Self-serve plan changes. Free is applied instantly (this is also the downgrade / cancel path). Paid plans return a Stripe Payment Link with `client_reference_id=<tenant_id>`; the plan is flipped only when the webhook receives `checkout.session.completed`. This guarantees the tenant cannot get paid features without paying.

Compiler overview - a backend-owned application contract for the main product surface. The UI can render this instead of hard-coding an audit dashboard as the first-run experience.

can read end-to-end. Tenant metadata + signed receipts + audit log + BAA-ready org details + control mapping snapshot. JSON only (no PHI ever transits this endpoint - receipts are payload-free by design). Auditors who want a literal ZIP can pipe `curl ... | jq -r .b64_zip | base64 -d`, but the JSON shape is the canonical artifact.

Self-serve account delete. Soft-delete the tenant; receipts and artifacts already shipped to users keep verifying since the cloud signing key is unchanged. The tenant can no longer authenticate. If they had an active Stripe subscription we ask Stripe to cancel it so they aren't charged again - best-effort, never blocks deletion.

Self-serve data export (/privacy promises this). Returns a JSON bundle of the tenant's row plus every concept, compile job, observation, and invocation we have on file for them. We strip secrets (api_key_hash, stripe_customer_id keeps existing for portability, billing tokens drop). Content-Disposition nudges browsers to save the file.

M11 - list the tenant's invoices / receipts (newest first). Reads the local ledger populated by the invoice.payment_succeeded webhook.

Provider-key vault: per-employee / per-team upstream provider keys The core of "every employee's AI use, in one place you control": a member stores their OpenAI/Anthropic/etc. key here; the gateway routes their traffic under it (see dispatch) and the call lands in the team lake attributed to them. Responses are always redacted (never the raw secret).

Drop a specific previous key from the verification ring. Receipts signed with that key will no longer verify against this tenant after this call. The current key cannot be pruned - rotate first to retire it.

List receipt-signing key metadata for the calling tenant. Secrets are never returned - only the key_id, status, and rotation timestamps.

Rotate the per-tenant receipt-signing secret. Previous secret is preserved so older signed artifacts and audit rows still verify.

SP metadata is a static document an IdP fetches at federation-config time. It does NOT depend on entitlement (publishing the SP entity ID is fine even for tenants who can't yet bind to it).

Scoped member API keys (multi-key, least-privilege) Mint keys with a subset of scopes (e.g. capture:read, lake:export, namespace:<slug>, or *) so a teammate or a CI job gets only what it needs. Non-breaking: the tenant-primary key (rotate via /v1/account/keys) is full.

Generate (or rotate) the per-tenant SCIM bearer token an IdP uses to drive SCIM 2.0 provisioning. Returned in plaintext exactly ONCE (on generation); only the hash is persisted. Rotating invalidates the previous token. The token is never written to logs or the audit payload.

/account/overview "What's next" engine reads. Returns artifact + capture + namespace counts, the age of the last artifact, age of the primary api key, plus a flat `signals` array each rule in whats-next.js matches on. Auth-gated (NOT in PUBLIC_API) - cross-tenant state leaks were what made /v1/intent/next add tenant_id scoping in W432.

Plain empty-state: if active-learning-queue.js isn't on disk yet (sibling agent still building, or this is a fresh deploy), return ok:true with module_missing:true so the dashboard can render a useful empty state instead of a 500.

M13 - admin-issued refund. Owner/admin only (req.is_admin). Issues a Stripe refund against a charge, records a credit-memo in the tenant ledger, audits the action, and notifies the tenant. 503 when Stripe is not configured.

agent telemetry routes fence on req.tenant_record and forward req.tenant_record.id as tenant_id into the helper so cross-tenant rows never appear in the rollup. _tenantScope() returns null for admin (cross-tenant reads allowed) and the canonical tenant_id otherwise.

/v1/airgap/jobs - bare collection GET that lists tenant air-gapped distill + sneakernet jobs. Each W831 job is keyed by run_id; the actual status route is /v1/airgap/distill/status/:id. This bare GET returns an empty envelope until a wave wires the per-tenant job index.

All four auth-gate on req.tenant_record. W411 defense-in-depth: every route binds tenant into the args so a future schema change cannot leak across tenants.

Anonymous CLI auth (robots / agents) Bootstrap: returns an anon_token that the CLI stores locally. 30-day TTL. No email, no signup. Designed for agents that need to start working in <1 second.

Claim: convert an anonymous workspace into a permanent account. if email matches an existing real tenant: merge the anon's recipes into it, return existing key else: upgrade the anon tenant in-place to a real tenant, rotate to ks_*, return new key WC14 - share the bootstrap limiter (50/24h/ip) so brute-forcing kao_ tokens through this endpoint is bounded.

Tenant fence: tenant_id forced from req.tenant_record.id. Status transitions return plain invalid_transition envelopes - never silently re-write state. version stamp matches /^w782-/.

for callers that have the manifest hashes block in hand (e.g. a CLI that just downloaded the artifact and parsed its manifest.json). No auth required - the check is pure: recompute CID from hashes, compare to the claimed CID. Returns `manifest_hash_mismatch` envelope on disagreement, `verified:true` + recomputed cid on match.

for an artifact. Returns 404 when the artifact has no evidence DAG on disk. The shape is { ok, artifact_id, dag: {nodes, edges} } so the caller can re-build the DAG client-side and walk it.

Natural-language assistant Scoped to req.tenant_record; never calls an external LLM; deterministic.

chat widget on every authed /account page. Routes through the W888-P AssistantClient three-layer fallback (local GGUF -> kolm.ai -> gateway frontier). Tier-gated to paid plans; rate-limited to 60 calls/hour/tenant. Returns the W888-P envelope verbatim plus the canonical aliases (provider_used / latency_ms) the widget consumes.

(formatted as a docs-anchored system prompt). The response surfaces the sources back to the client so the UI renders the same URLs it sent in. KOLM_ASSISTANT_TEST_SHIM=1 wires deterministic shims for tests; this same env var is used by tests/wave888p-cli-nl-routing.test.js.

Same shape, workspace-level - the artifact-derived claims are omitted and only the vault-derived jurisdiction claim + the 8 required control rows remain.

stamped by captureAudioMessage (NEVER the raw audio bytes). All three are tenant-fenced via req.tenant_record.id (W411). Plain envelopes on bad input - no silent passthrough.

audio routes. Real proxy when configured; fixture returns deterministic bodies; otherwise plain 501 with a structured "not yet supported" envelope so SDKs see something better than 404. These concrete audio endpoints use the OpenAI connector when a key is present.

Auth-gated. Returns the worker doctor envelope - reports python3 presence + transformers/torch/librosa/soundfile availability + which tokenizer command is wired.

audio routes. Real proxy when configured; fixture returns deterministic bodies; otherwise plain 501 with a structured "not yet supported" envelope so SDKs see something better than 404. These concrete audio endpoints use the OpenAI connector when a key is present.

audio routes. Real proxy when configured; fixture returns deterministic bodies; otherwise plain 501 with a structured "not yet supported" envelope so SDKs see something better than 404. These concrete audio endpoints use the OpenAI connector when a key is present.

OSCAL assessment-results JSON; ?format=poam returns the POA&M-style remediation table. kolm MAPS to standards; this is an assessment-results export, never a certification. Read-only view over the SAME signed report. Tiers: Full Readiness ($15,000) and Continuous-Plus ($3,500/mo).

foreign / unknown id is 404, never another tenant's data. No re-sign here; runFixRetest is pure + never throws (the diff is computeAuditDelta). Tier: a Continuous ($299/$999 per month) on-demand tick, or a follow-on $750 Signed Readiness Report that embeds result.delta.

immediate re-attestation for the caller's active subscription(s). Auth-gated by the tenant's own API key (call it from CI after a deploy).

every Continuous subscription whose re-attestation is due. Driven by an EXTERNAL scheduler hitting this with x-kolm-cron-secret (containers restart, so no in-process timer). Idempotent: claim-then-run, never double-signs.

preview without offering a backdoor full dump. All three routes auth-gate on req.tenant_record. Plain envelope on bad format / missing tenant - no silent passthrough.

Tier-A bridge: source 'kolm-capture' skips the inline/url transport and audits the CALLING tenant's own stored gateway captures (grade A). The label is reserved - source_label may never claim it for vendor logs.

server signs evidence reports with, so a buyer (or the /verify page's trusted-issuer keyring) can pin against the authoritative source instead of trusting whatever key a report embeds. Returns ONLY the public half; the private key never leaves the signer. Never throws.

reason:'issuer_key_revoked' for any report signed by that key, and the public status endpoint reports valid:false. Gated by ADMIN_KEY (Bearer ADMIN_KEY via authMiddleware -> req.is_admin, or an x-admin-key header). body: { reason? }

issuer key fingerprint: 'live' | 'rotated' | 'revoked' + valid flag, so a buyer's verifier can confirm the key that signed a report is still trusted RIGHT NOW (a signature that verifies against a REVOKED key must be refused). Pure read over the persisted key-revocation store; never throws.

write path with HMAC-chained signatures); this implementation gives the dashboard real entries from day one without that wiring. Probe-safe: when unauth'd, returns the same 200 envelope with entries=[] rather than 401/503 so frontend probes don't fall over.

plus -> $3,500/mo Continuous-Plus (flows through the existing subscription path; activated by activateSubscription with product_key 'plus'). Env-gated 503 degrade: when the product is not wired, createAsrCheckout throws BillingNotConfiguredError (statusCode 503) listing the exact env vars.

Signed Readiness Report for a specific audit. body: { audit_id }. The audit must belong to the caller and already have a (watermarked) report.

issuer.recognized - tier 2: that key is one this product publishes (the live signer or a key in public/keys/kolm-issuers.json). trusted - verify.ok AND issuer.recognized. A consumer that only checks verify.ok would accept a rogue-signed forgery; check trusted.

audit/report this tenant owns (scan previews + paid reports) plus which ASR products are currently purchasable. Powers public/dashboard.html.

tenant's own stored gateway captures/receipts instead of a vendor export. The resulting report carries evidence grade A (first-party capture). The source value is reserved: supplying it WITH logs is a clean 400, so vendor logs can never masquerade as gateway captures.

by session id (audses_*) OR report id (asrr_*). BOTH ids must resolve to a report owned by this tenant - a foreign / unknown id is {ok:false} (404/403), never another tenant's data. No re-sign; computeAuditDelta is pure + never throws. The :id is "current"; ?against=<id> is the prior baseline.

The signed report reshaped into a procurement-ingestible artifact. Auth gated + tenant-fenced exactly like the sibling /report route (the export is a view over the SAME signed envelope - it carries the key fingerprint + verify URL so an importer can always trace it back to the signed source).

(AUTH, tenant-fenced) - the openable GET alias of the POST above, so a seller can pull their session's autofilled questionnaire from a browser / a simple link. Identical auth + tenant fence + pure-view semantics; query-only (no body). The POST form stays for callers that prefer to send { template }.

(AUTH, tenant-fenced) - the SELLER pre-fills a questionnaire from their own session's signed report (e.g. to attach to an RFP response before sharing). Tenant-fenced exactly like the sibling /report + /export routes. body may carry { template, format } as an alternative to the query string.

Returns the bare signed envelope (json), rendered HTML, or a PDF stream each is a downloadable deliverable, not an {ok}-wrapped API envelope.

Verify the HMAC chain over this tenant's audit_events rows. Returns ok=true when every row hashes to its declared event_hash given the previous row's hash, ok=false with the list of breaks otherwise.

4 - short OAuth aliases: GET /v1/auth/github redirects to the canonical /v1/oauth/github/start (preserving any ?redirect= query). Same for /v1/auth/github/callback (forwards code+state to the canonical callback). When env vars are missing, the canonical route returns the operator-facing 503 oauth_not_configured envelope.

API key (ks_*/kao_*) + OAuth; there is no password endpoint. We add live deprecation aliases that 410 Gone with redirect hints so the routes are not "dead" - the deprecated-endpoint lock-in in W890-9 expects every routed path to have a handler. Both alias handlers carry the canonical {ok:false, error:'<id>'} envelope so W890-9 lock-in 9 stays green.

All five are tenant-fenced via req.tenant_record.id (W411 law). The route layer ALWAYS forces tenant_id from auth - body.tenant_id is ignored even if the client tries to pass one.

NEW full-lifecycle tick. The GET /v1/autopilot/tick route above stays the heartbeat (tests/wave775-autopilot.test.js asserts action:'disabled'); this POST handler runs the full lifecycle via tickAutopilotFull.

Bakeoff run - evaluates a set of contestant models against a dataset and returns ranked rows + winner. Body: { dataset_id (required), contestants, opts }. Used by /account/bakeoffs and `kolm bakeoff run`.

/v1/bakeoffs - list + run alias for /v1/bakeoff/run. The bakeoff module does not persist runs to a registry (each call returns a fresh result), so GET returns an empty array; the page already handles that shape via `{bakeoffs: []}` in its .catch fallback.

Bakeoffs run alias - SDK-friendly synonym for /v1/bakeoff/run with the added W411 tenant fence at the dataset boundary (cross-tenant dataset_id returns 404). Same body: { dataset_id, contestants, opts }.

envelope when called without a tester-supplied DI seam. The routes import lazily so the bench modules don't pay startup cost on cold daemons that never call them.

it walks the team's member tenants and rolls up. Tenant fence: tenant_id is forced from req.tenant_record.id - never read from the request body or query string. Team caller is forced to be a member of the named team (non-members get 403 forbidden).

Returns the static catalog of legacy W384 meters merged with the W409y billing-unit catalog (10 units the auditor signed off on). The W409y entries carry tier_soft + tier_hard limits resolved from the caller's tenant plan when an authenticated key is present.

P0-3 closure: /v1/billing/tiers as a public alias of /v1/plans so the CLI `kolm billing tiers` (+ alias `plans`) returns useful data without requiring auth. Includes a billing_configured flag tied to the actual STRIPE_PAYMENT_LINK_* env presence so the UI can demote when unwired.

Returns the current-period usage map for the caller's tenant. The dashboard at /account/billing reads this endpoint; the CLI `kolm billing usage [--period]` hits it directly.

After ≥4 calls with the same template signature we surface a synthesis suggestion. 1: persists via insertCapture (durable contract). 503 on store failure - same envelope as the capture proxy handlers.

builder UI's results pane: returns k_score, first 3 train rows, first 3 holdout rows, production_ready verdict + gate reasons, and the synth metadata. Public + rate-limited; no artifact write, no charge. Accepts {spec, seeds_jsonl_text}. Errors map to 400 (validation) or 500.

Build strategy brain - shared planner for capture, prompt/RAG/routing, training, distillation, cloud compute, compilation, quantization, and local runtime. It never launches work and never returns secret values.

{task, examples} payload into a real compile job. Validation matches /v1/builder/preview so a Preview→Compile flow that passes preview also passes here; the only added requirement is the API key (handled by authMiddleware mounted above this line). Recipe class and namespace are forced so builder-originated artifacts are distinguishable in audits.

Rate-limited; no auth. Inputs are validated tightly so this cannot be used as a generic compute oracle. The 10 KB per-example cap matches the body limit on /v1/compile and keeps the synthesis cost bounded.

/v1/builds - aliases the compile-job list for /account/builds.html. builds.html expects {builds:[{job_id, status, ...}]}; the canonical /v1/compile/jobs returns {jobs:[...]}, so we adapt the shape here.

an HTTP response would balloon memory, leak the server's checkout layout, and lock the route into one host's filesystem. The CLI is the supported path - `kolm bundle airgap --out <path>`. The route still exists so surface discovery + docs can link to it and so a future CDN-backed implementation has a stable URL.

owning tenant via req.tenant_record.id. A buyer seat lives under the EXISTING Continuous $999/mo shape - no new price or tier. body: { slug, label? }

Attestation callback - UNAUTH (no API key). Identifies via enroll_token, which was minted by the deploy endpoint and embedded in the deploy script. The token is single-use-equivalent: if an attacker has the token they could spoof the public_url, but the deployment row is owned by a specific tenant_id and the URL is visible in their dashboard - they'll notice.

Customer deploys a .kolm artifact to their own Fly / AWS Nitro / GCP CVM / Azure CVM / Docker host. We issue a signed deploy manifest + a deploy script the customer runs. The deployed instance POSTs an attestation (image SHA, plus TEE measurement on confidential targets) back to /v1/byoc/attestation. kolm.ai never runs the artifact.

Capability build - constructs a capability descriptor block from an artifact manifest, declaring what the artifact can do (modalities, budgets, K-floor, attestation requirements). Pairs with /v1/lineage/build.

Capability validate - checks a capability descriptor block for structural consistency and that declared budgets/K-floor are internally coherent. Returns {ok:true, block} on success, {ok:false, error} otherwise.

OPENAI_BASE_URL=https://kolm.ai/v1/capture/openai → POST .../v1/chat/completions The suffix is discarded; the flat provider-specific capture endpoints use the same handler. Express's `?` makes the suffix optional, and the wildcard absorbs any depth. The body is the upstream Anthropic Messages payload, unmodified.

/v1/capture/browse / /v1/capture/bulk / /v1/capture/export - page surface for the captures.html admin view. Browse paginates, bulk acts on a set of capture ids, export streams JSONL/CSV. Empty-tenant safe.

POST shim so account/captures.html bulk-export button (sends {capture_ids:[...]} in body) doesn't 404. Filters to the listed ids and returns the rows inline as JSON so the page can blob-download client-side.

Gemini capture and OpenAI-compatible aliases. These route to Google's /v1beta/openai compatibility surface so OpenAI SDK clients can set base_url=https://kolm.ai/v1/capture/gemini and keep using chat.completions.

the next insertCapture call will persist beyond a single lambda. Used by the /captures + /security pages and the `kolm doctor` flow.

Capture media - multipart upload endpoint for image/audio/video/blob captures. Streams parts through mediaStoreBlob and appends one event per blob to the tenant-scoped lake. Requires Content-Type: multipart/form-data.

OpenRouter capture and base-URL aliases. The direct base-URL forms support SDKs that point BASE_URL at https://kolm.ai/v1/openrouter.

OpenRouter capture chat completions alias for clients whose base URL is https://kolm.ai/v1/capture/openrouter and which append /chat/completions.

Payload shape is the CLI/UI contract (W258-BE-6): capture_id / captured_at / namespace / model / provider / latency_us / status / prompt_head / response_head / x_kolm_capture_durable. The raw store row is shimmed here so the dashboard and `kolm tail captures` see the same shape without one of them having to translate.

W-G wrapper-completion - GET /v1/captures/:id/inspect Single-row inspection (full prompt + response + receipt + chain hash).

W-G wrapper-completion - POST /v1/captures/:id/review Approve / reject / quarantine a capture. Body: {action: 'approve'|'reject'|'quarantine', reason?}. Bulk variant: POST /v1/captures/review-bulk {ids:[...], action, reason?}.

W-G wrapper-completion - GET /v1/captures/list Paginated capture browser feed for /account/captures.html. Filters: ?namespace, ?status (pending|approved|rejected|quarantined, multi-comma), ?risk_min, ?risk_max (0..1), ?pii (multi-comma), ?from, ?to (ISO), ?q (substring), ?limit (1-200), ?offset.

Body shape: { namespace, conversation_id, conversation:[{role,content,tool_calls?,timestamp}], parent_message_id? }

Body shape: { namespace, kind, payload, hash?, redaction_receipt? } If hash is omitted we compute one from the canonical payload so the caller can be lazy. kind MUST be in MULTIMODAL_KINDS.

→ savingsReport envelope comparing local run vs frontier baseline. Auth required (same pattern as billing/breakdown). Every envelope carries methodology='public-research-estimate' so a downstream consumer cannot mistake the estimate for a measured value. W786 candor contract.

Confidential-compute shape - returns the expected JSON shape for an attestation report of the given kind (pccs, snp-report, nitro-attestation, nras). 404 if the kind is unknown. Lets callers validate before /v1/cc/verify.

Confidential-compute verify - validates an attestation report against its declared kind. Returns {state:'shape_ok'|...,verified:false} until a tenant registers a real crypto verifier via registerAttestationVerifier. Body: { kind, report, opts }.

public changelog - marketing surface, no auth, no tenant scoping. Source of truth lives in src/changelog.js (a single static WAVES array).

-> stream body w/ per-format Content-Type Tenant fence: tenant_id forced from req.tenant_record.id; query/body never override. version stamp matches /^w783-/.

the standard hosted-inference path with accelerated:false on the body so the caller can still get a real chat completion. Defense-in-depth tenant fence: any accelerated call without req.tenant_record is hard 401-rejected - we never run the accelerated path anonymously, even on the local daemon, because the bench dashboard keys on tenant_id.

CID lookup - content-addressed resolution within the caller's tenant scope. Two compiles that produce the same bytes (same task spec, same recipes, same evals, same base model pointer) yield the same CID; this route is how downstream tools dedupe by content rather than job_id. CID format is strictly validated to keep the path safe from injection.

Constraint-first compute planner for local, SSH, rented GPU, managed training, customer cloud, and edge runtime. This is a planning endpoint only: it never launches infrastructure and never returns secret values.

Secret-safe deploy catalog for account UI, CLI, CI, and unauthenticated evaluators. This does not create infrastructure and never returns secret values; it returns the concrete commands and env-secret references needed for BYOC, edge, GPU, and self-hosted deployments.

NOTE: meter route registered BEFORE the ':job_id' route so the router matches /meter/:job_id literally and does not interpret 'meter' as a job_id.

Tenant fence: tenant_id forced from req.tenant_record.id; body/path never override. Backend candor: when KOLM_CLOUD_DISTILL_ENDPOINT is unset, the submit response carries cloud_backend_status='no_pool_configured' so the caller knows the work is queued but not yet executing. version stamp /^w785-/.

Cloud readiness is exposed directly for account UI, CI, and self-hosted operators. It reports configured categories and missing variable names, but never returns secret values.

Compile job creation - queues a tenant-scoped build and returns job_id, status, and poll URL. Validates task/model/output options, bills usage, and writes the compile audit record.

Dispatches a compile to a partner GPU (modal/runpod/vast/lambda) using server-side credentials (KOLM_RUNPOD_TOKEN / KOLM_MODAL_TOKEN in env). Body: { backend, namespace, spec?, confirm, budget_usd, base_model? }. Without confirm:true we return a quote so the caller sees the cost first.

would call the LLM bridge; this returns a deterministic sample so the Describe-tab "Generate preview" button works without any keys.

overlay. Reload-safe via ?cursor. See src/compile-stream.js for the event contract.

* /governance-report runs the loop body with a per-row tenant re-check so a future schema bug cannot leak across tenants. Distinct from sibling W767-cert / W768-modelcard / W769-residency / audit-export routes - no path collision possible.

Compliance certification packet - local evidence exists, external auditor and legal certifications remain explicitly gated.

Compliance certification manifest template - the exact evidence bundle a live auditor/legal/certification claim must provide before Kolm can call compliance certifications complete.

Compliance certification manifest validation - fails closed on missing auditor/legal evidence, unsigned proof hashes, non-HTTPS evidence URLs, placeholder fields, and secret-looking values.

Compose - dispatches one query across the top-k matching kolm artifacts and returns each artifact's output. Billable per non-cache, non-error dispatch. Body: { query, input, k=5, strategy='attention', tag }.

Connectors - lists upstream provider connectors (openai, anthropic, openrouter, etc.) with per-provider config status (key present, base URL, last reachable check). Read by /docs/connectors and `kolm connectors`.

connector tile on the Connect tab. Appends to data/connector-waitlist.jsonl. Best-effort: never breaks the UI.

heuristic (flag_reason starts with `copyright_heuristic:`). Plain contract: this is HEURISTIC, not legal advice. The route stamps version:'w750-followup-vN.M' on every envelope so consumers can version-pin via regex (/^w750-followup-/).

Returns: { valid: boolean, reason?: string, spec, type } This validates the HMAC signature using the server's receipt secret. For a future Ed25519 swap, the public key would live at /.well-known/ and verification would not need server auth. Today this endpoint is open.

HTTP control plane: POST /v1/deploy + /v1/deploy/canary + /v1/test-device + /v1/test-quants. All require auth (auth.js gates via PUBLIC_API allowlist; these paths are NOT in PUBLIC_API, so an unauth request returns 401 from the auth middleware). The handlers below simply do shape-validation + delegate to the same modules the CLI calls.

Guarded so we DO NOT intercept the legacy DELETE /v1/devices/:id/install/:artifact_id (Express route ordering means specific routes registered earlier win; we are below /v1/devices/:id/install handler so :id here only matches single segment).

per-file store so existing dashboards stay working. NOTE: this is registered LAST so the more specific /v1/devices/detect, /v1/devices/list, /v1/devices/recommend, /v1/devices/installed routes above keep matching ahead of it.

browser-form translator for /account/fleet "Add device" modal. The form posts {name, type, tags, connection:{host,user,key_path|base_url|kubeconfig,namespace}} which we flatten to DeviceRegistry.register() args.

Body matches DeviceRegistry.register() args: { id, name?, host?, port?, user?, type, keyPath?, tags?, hardware_hint? }

POST shim for /v1/devices/remove (fleet.html "Remove" button uses POST not DELETE). Accepts {name|id, hard?}. Soft delete by default.

POST mirror - body carries artifact_cid (matches existing /v1/pipeline/run + /v1/bakeoffs body shape).

Distill from captures - turns the caller's namespace captures into either a recipe (template-cluster >=4 captures) or a specialist distill job (when total captures >=1000 or mode='specialist' is forced). Returns the synth result for recipes, {job_id, poll_url, bridge_source} (202) for specialists. Body: { namespace, min_pairs, mode, name }.

Commit (POST) picks recipe vs specialist by count (<1000 vs >=1000), forwards to /v1/bridges/auto-synthesize (recipe) or KOLM_TRAINER_BRIDGE_URL (specialist). Errors surface as 503 (capture-store) / 400 (not_enough/ no_cluster). W364: specialist arm always returns 202 with job_id (either remote bridge or in-tree worker via src/distill-bridge.js).

Run an on-policy distillation against a teacher-student pair via the tenant-installed trainer plug-in. Auth-gated. Body: { pairs_path, student_path, out_dir, namespace, max_steps }. Returns trainer envelope or no_trainer_installed.

Public trainer doctors. These report only local trainer availability and install hints, so CLIs can decide whether a host is train-capable before a tenant exists. Training jobs themselves remain authenticated below.

Train a preference-pair objective (dpo/simpo/orpo/kto) via the tenant installed trainer plug-in. Auth-gated. Body: { pairs_path, student_path, objective, out_dir, namespace, beta }. Returns trainer envelope.

Preference distillation doctor - unauthenticated capability report for the DPO/SIMPO/ORPO/KTO training path and its local dependency hints.

Reads ~/.kolm/distill-runs/run_<id>/{run-meta.json, progress.jsonl, manifest.json}. Tenant-scoped: listDistillRuns filters by req.tenant_record.id (fail closed on missing tag). The progress.jsonl events are emitted from distill() each step so the dashboard can replay the loss curve without re-running the job.

Distill run detail - reads ~/.kolm/distill-runs/run_<id>/{run-meta.json, progress.jsonl, manifest.json} for one run. Tenant-scoped - 404 when run belongs to another tenant or id doesn't match /^run_[a-z0-9_]+$/i.

Distill strategy plan - ranks the next backend action from current data, holdout, privacy, teacher, preference, latency, and budget constraints. This planner does not launch training or call providers.

Distill strategy catalog - static decision vocabulary for data collection, rule/cache first paths, supervised fine-tune, teacher distillation, preference optimization, on-policy improvement, and speculative decoding.

so authed callers can later resume; anon callers also get an id but the persistence flag is false (the page falls back to localStorage).

Drift detect - compares two drift snapshots (baseline vs current) and returns signals + verdict ('within' | 'drift' | 'breach') with breach/drift counts. Body: { baseline_snapshot, current_snapshot, tolerances }.

Drift report - builds a full drift report (signals + narrative + tolerance block + caller notes) from two snapshots. Same inputs as /v1/drift/detect but returns the formatted report ready for archival or UI rendering.

unless config.auto_remediate_drift === true AND body.dry_run !== true. dry_run defaults to TRUE so a misclick cannot kick off a re-distill. All five are tenant-fenced via req.tenant_record.id (W411 law).

the 12-step compile→verify→run→drift→retrain loop. W434 exposes three tenant-scoped POST routes that wrap the existing pure functions. The routes are stateless (no server-side persistence) - the report's hash is verifiable client-side, so the round-trip is just "validate my inputs + compute signals + return the report you can persist anywhere."

:namespace path param. The dashboard pages call these endpoints without a selected namespace before the user picks one; previously they 404'd. We forward to the existing :namespace handler with namespace='default' so the account UI<->server parity test (W409f #4) passes and the page renders an empty-state from a real envelope instead of a 404.

tie-in: when shouldAlert() fires the route calls driftAlertStore.registerDriftWarning() so the NEXT W709 routing decision can stamp `drift_warning:true`. Plain fallback: if the W709 routing-events module is not loaded, the warning is still registered (it is in-memory) and the W709 hook simply never reads it.

Tokenize-and-ingest a path (or array of paths). The path must live on the server; for now we support self-host where the kolm cloud runs alongside a tenant's mounted corpus directory. For the SaaS path we'll add an upload endpoint in Sprint 2.

OpenAI-compatible passthrough for the responses, embeddings, and moderations endpoints. Each routes through __connectorProxy('openai', ...) so the upstream OpenAI API is reached with the configured key, and the request/response is captured into the tenant lake.

Benchmark evidence readiness for comparative claims. This route audits local evidence files and reports the exact public data lanes still needed; it never calls providers and never returns secret values.

Benchmark evidence template - returns the strict provider/runtime lane schema required before comparative benchmark claims can be marked public.

Benchmark evidence validation - validates a proposed provider matrix without saving it, calling providers, or exposing secrets.

K-score calibration - public, frozen benchmark contract for the score formula, 30-case suite, class mix, axis means, and manual-review leaderboard. This proves how K-score is computed; live model ranking claims require separate public benchmark evidence.

Quality judge calibration - public, deterministic fixture for the per-call quality judge. This is calibration evidence, not a broad claim that autonomous judging matches every review domain.

All four are authed (mounted below authMiddleware) and per-tenant scoped: a tenant can only read/write/delete corpora under its own tenant_id. The tenant_id is derived from req.tenant_record.id (the authenticated tenant) rather than accepted as a body field, so a forged tenant_id is impossible.

Looks up the owning artifact via the per-node reverse index; returns the verbatim node record (id, kind, plus any caller-supplied attrs). 404 when the node id is not in any artifact's DAG.

lifecycle revoke transition). Returns { revoked, needs_review[] }. The revoke verdict does NOT mutate the artifact's signed receipt - receipts seal bytes, not operational provenance - so propagation is a verdict written to the caller's audit trail, not a state-machine transition.

Evidence readiness - one public, secret-safe aggregate for every proof gate that can keep product copy from saying "final" too early. This mirrors `kolm evidence --json` so account UI, docs, CLI, and release audits share the same local/external boundary.

Body: { artifact_path, threshold? } The artifact must be operator-side (path on the server). Returns per-expert activation + prune candidates + estimated K-Score impact.

gguf/awq/exl2/mlx/onnx/tflite/coreml/openvino). Returns the plan + estimated size + invocation hint; actual export runs via the CLI worker.

Auth-gated via req.tenant_record. Tenant fence is forced from the authenticated record - any body.tenant value is overridden so a caller cannot point this at another tenant's namespace. The namespace IS read from the body because a single tenant routinely operates many namespaces and W816 closes the loop per-namespace.

/v1/federated/consortium - bare GET that points the TUI at the W830 members collection. The federated-consortium-routes module owns the tenant-scoped membership reads; here we add a no-query alias that returns the empty-state envelope when no consortium_id is supplied so the TUI view always has something to render.

Returns recent aggregation runs with status, epsilon spent, and participant count. Defense-in-depth: only returns rows where this tenant is a participant OR rows are visible to the consortium's listed members (default).

Returns the consortium-wide privacy budget: epsilon_spent (summed across recorded aggregation rounds) vs epsilon_allocated (from the consortium state). Also surfaces per-tenant epsilon_spent_by_self so a tenant can see how much budget THEY have burned.

Returns the list of opted-in members. Every member row includes its contribution_count + last_share_at so the UI can show "who's pulling their weight". The caller's own member row is always included.

Body: { consortium_id, scope?:[ns...], epsilon_allocated?:number, note? } Writes the member row into the consortium's single-tenant view + audits contribution_count=0 baseline + last_share_at=null.

Body: { artifact_id, test_inputs:[...], shadow_models?:[...], train_set?:[...], holdout_set?:[...], p_threshold? } Plain stub when shadow_models empty (returns mia_requires_shadow_models).

Body: { model_params_b, quant, vram_gb, context?, batch?, kv_precision? } Returns the same envelope as the CLI: {fits, est_total_gb, est_weights_gb, est_kv_gb, est_activations_gb, headroom_gb, recommendation}.

20 messages/day to tinker with the intent classifier; if a tenant key is attached the route upgrades to the full /v1/intent/ask snapshot. This is the SAME pipe pre-auth and post-auth, so the homepage chat box and the /account console chat box share the contract. Anon callers cannot read tenant state - snapshotContext is called with tenant_id=null.

W-G wrapper-completion - GET /v1/gateway/dashboard Aggregate routing breakdown + cost-savings + recent calls for the /account/gateway.html dashboard. Tenant-scoped via findByTenant.

6. Build the kolm-audit-1 receipt, sign it, persist + return. Every fallback marks `capture_eligible: true` so the flywheel picks up the cases where the local model fell short.

5 - public gateway liveness probe. Mirrors /health for the gateway sub-system: ok:true + version + module-loadable signal. Mounted before r.use(authMiddleware) so it is reachable without an API key. Ship-gate consumers use this to confirm the gateway dispatch path is wired without paying for a real upstream call.

Auth-gated (mounted after r.use(authMiddleware)). Probes both local backends with a 1-second HEAD timeout so a slow / unreachable backend never blocks the dashboard. The response surfaces the resolved mode (NOT the raw env value) so a callers sees what currentMode() actually decided.

W-G wrapper-completion - GET /v1/gateway/providers Return the 11 supported providers with the customer's per-tenant config overlaid (enabled, rate_limit, position-in-chain). Reads the registry for the canonical list, then merges per-tenant overrides if any.

W-G wrapper-completion - POST /v1/gateway/providers/config Persist per-tenant provider overrides (enabled toggle, position-in-chain, RPM limit). API keys are NEVER stored in the row - operators set them as environment variables; we only persist the FLAG that one is set.

W-G wrapper-completion - POST /v1/gateway/test-connection Fire a tiny ping against an upstream to verify the key works. Body: {provider: 'anthropic', api_key: 'sk-ant-...'}. Returns {ok, status, elapsed_ms} but never echoes the key back.

Unauthed: returns the operator's local accelerator profile so an Account UI running on the same host can render a "what fits" picker without auth.

Authenticated /v1/health - full snapshot including provider availability and feature flags. Admin-only because the booleans are useful signal for staff debugging but unnecessary surface for tenants. Public /health (above the authMiddleware) is the lightweight no-leak version.

body: { name, visibility?: 'public'|'private', artifact_b64, metadata? } Stores the artifact bytes + metadata. Returns { handle, owner, name, sha256, url }.

Both routes are auth-gated. The python3 parsers live in apps/import/{gguf,safetensors,onnx}.py and run in-process via spawnSync from src/import.js; missing python3 surfaces a 503 python3_missing envelope - never a 500, never a silent fake.

Body: { model_id?: string, kolm_path?: string } For HF id: fetches config.json over the public HF endpoint. For .kolm: reads manifest from disk (operator-side path) with signature bypass since inspection is read-only.

pair locally; this route runs it server-side so the post-auth dashboard can render the same top-N ranked actions without shelling out. Auth-gated. Response envelope: { ok, recommendations: [{action, command, why, rank}], generated_at, snapshot_summary: {captures, opps, ...} }

Job status (used by HF / URL queued jobs + W229 on-disk job registry + distill bridge). Order: corpus_jobs / specialists in-DB, then the src/jobs.js per-file on-disk registry.

Public keys list - returns registered Ed25519 verification keys and directory stats. additionally surface the default receipt signing pubkey under source:'system' so /v1/verify callers can discover it without going through the challenge→sign→register flow first.

only + safe to cache. Both POST routes require auth via the standard middleware path; submit additionally requires body.confirm:true as a spend-protection gate (the W411 confirm-pattern). Plain envelopes on every degraded path.

K-score time series for the namespaces flywheel chart (recorded by the autopilot lifecycle). Tenant-fenced; plain empty series when none.

full audit trail for a single event_id. Tests assert that every approval/reject/edit decision is recorded with reviewer + timestamp + before/after output. The legacy /v1/labels/:event_id returns the last label only; this endpoint returns the whole sequence.

The /account/labeling.html UI uses concrete label-queue aliases for the canonical labels routes. Rather than chase the legacy page (and break any client polling the old paths), we alias the known endpoints. The shapes also tolerate the older field names (label vs verdict, accepted vs approved, pending vs decided).

Returns the captured (input, output) pairs for a namespace as JSONL or a JSON envelope. This is what `kolm labels` downloads. Counts go to the status command so the customer can see "ready to distill at 1000 pairs." 1: reads via the durable capture-store (listCaptures) so the distillation corpus comes from the same backend the proxy writes to.

The W751 GET /v1/verticals/:id/fingerprint route already exists above; the module is consumed via the new pattern-lake helpers. New code paths (CLI lake subverbs, the W757 docs page) call these routes directly.

Lake repeated - finds clusters of repeated workflow inputs in the event store (the W384 "repeated workflows" surface). Returns up to ?limit (max 200, default 20) clusters with their representative input + member count.

Lake stats - per-tenant event-store roll-up: row counts, byte size, oldest and newest timestamps, namespace breakdown. Accepts ?namespace, ?since, ?provider, ?model, ?status, ?min_latency_ms, ?max_latency_ms, and ?exclude_errors filters. Scoped via _tenantScope; admin sees cross-tenant aggregate.

dashboard can show "Local storage: ~/.kolm/events/events.sqlite (12 MB)". Returns the same envelope storeInfo() emits, plus a coarse byte total.

Reads directly from the event-store (NOT capture-store). Default limit 50, capped at 500. Returns newest first.

* Wilson 95% CI gated at n>=30 PER LANGUAGE. Below that the per-lang k_score is null - never estimated. * augment-multilingual is dry_run by default. confirm:true required to incur translator cost. teacher_caller is DI'd from req.app.locals so tests never hit a real translation API.

Enterprise inquiry intake (KOLM-102) Public POST from /enterprise/inquiry. Validates 7 required fields, persists to in-memory enterpriseLeads, and emails sales@kolm.ai via Resend (best effort - sendMail() returns { skipped: true } when RESEND_API_KEY is unset).

Admin-only read of a single enterprise lead. Useful for ops triage and for verifying the in-memory store after a submit during e2e checks.

Library - returns the bundled kolm runtime library version and a human description string. Used by the SDKs and `kolm version` for the runtime-library identifier (separate from the API/server version).

Lineage validate - checks an artifact-lineage block for structural consistency (parent links, build steps, version pins). Returns {ok:true, block} when the lineage is well-formed, {ok:false, error} otherwise.

/v1/lingual/manifest - bare GET aliasing the W833 manifest collection. The shipped route is /v1/lingual/manifest/:artifact_id; without an artifact_id selected (the TUI default state) we return the tenant-wide language-mixture distribution so the view still renders.

Reads the per-language K-Score block off an artifact's manifest. Looks up the manifest via src/artifact.js (or registry.js) when available; falls back to an plain "no_manifest_found" envelope when the artifact isn't registered.

Tenant fence: tenant_id forced from req.tenant_record.id; query/body never override. Returns plain envelope (no_captures, insufficient_samples) rather than throwing. version stamp matches /^w781-/.

public anonymous "try it" demo of the capture-receipt shape. No auth, no write side-effects; visitors on /value-loop POST a prompt+response and see the exact same receipt envelope a real authenticated /v1/bridges/observe would emit, with `demo:true` + `durable:false` so the body cannot lie.

W339/W342 - install/download MUST refuse artifacts that don't pass productionReady(). Same gate the marketplace pill uses, so a user who sees no "Verified" badge ALSO can't `kolm marketplace install` it. force allowed via ?force=true query for CI testing / canary debug, matching `kolm run --force` semantics.

Auth-gated. Streams artifact_uri bytes; records download counter. 402 if listing.paid AND tenant lacks entitlement.

Pure read: returns the enum set so the UI sidebar can render filter chips without hard-coding the lists in two places.

IP per 24h (see marketplaceInterestLimiter above). Returns { ok, position } where position is the row's stable 1-indexed place in the early-access list. Stable means the position does not change on dedupe (we read the existing row's position back out).

explicit list endpoint used by /marketplace.html client render. Always returns { artifacts: [...] } with live verified flag.

Auth-gated. Forecast-only: aggregates revenue ledger and emits payout audit rows. Returns the per-listing split.

Distinct from /v1/marketplace/publish-request (manual review queue) this endpoint is the programmatic publish path the CLI uses after pipeline-ship has already enforced the production gate locally.

* empty search results -> {ok:false, error:'marketplace_empty', hint:'no artifacts registered yet', results:[]} * unauth POST -> 401 + {error:'auth_required'} * invalid payload -> 400 + {error:'<code>', detail:<msg>}

Auth-gated. Body: {artifact_uri, manifest_sha256, signature_b64, public_key_pem, id, title, vertical, task_type, hardware_targets[], k_score, teacher_model, paid, price_micro_usd}. publisher_tenant_id is FORCED from req.tenant_record.id.

transport?: 'stdio'|'http'|'sse', server_id?: string, // MCP server registry id call_id?: string, // pin for a reproducible id now?: number|string // injected clock (tests / determinism) }

Tenant-fenced: only returns a receipt minted under THIS tenant. The verify result is deterministic (recompute canonical + Ed25519 check; no network).

Media redact - text-extractable media redactor. Accepts {media_uri | text, mime} and either redacts inline text or loads the blob, sniffs mime, and routes text-extractable kinds (text/json/yaml/xml) through /v1/redact. Non-text kinds (image/audio/video/pdf) return {deferred:true, deferral} with a worker hint instead of attempting heavy ML in-process.

envelope so the caller knows exactly what to install. Body: { media_uri | path, mime?, kind?, max_bytes?, model?, lang? } Sync mode (default): worker runs in-process via spawnSync. For long whisper passes, callers should pass {async:true} (deferred to W455).

worker self-doctor proxied through the API so `kolm media doctor --remote` can ask the server which extractors are wired.

Body: { base, head, method?, alpha?, dry_run? } Returns the merge envelope (lineage check, kscore delta heuristic, output path). When dry_run=true, no artifact is written.

Returns the durable merge_jobs record (status queued|running|completed| planned|failed). Tenant-scoped: a tenant can only read its own merge jobs.

{ok, manifest, source_metadata, ...}. Both are auth-gated. Discovery is local-filesystem only - no network call leaves the box. The python3 GGUF parser is reused; missing python3 surfaces a 503 envelope on the wrap path.

* The forget route ALWAYS writes the audit event before returning ok. Idempotency is checked inside src/capture-forget.js (existing marker returns the original audit_event_id without writing a second row). * Tenant fence everywhere: every read/write is keyed on req.tenant_record.id; defense-in-depth lives inside capture-forget.js.

MUST regex-match (W604 anti-brittleness). Modules import lazily so cold daemons that never hit this surface don't pay for the schema/emitter trees.

other teachers, but rows whose family hints at an Anthropic-shaped client probe are also surfaced under an `anthropic:`-prefixed alias so a probe via the Anthropic SDK can discover them without colliding with the canonical HF id.

Models cache - returns the local model-weights cache index for the API host (cache_dir, total_bytes, per-entry rows). Used by `kolm models cache` and the device-detect picker to know which weights are already on disk.

Models pull - 302-redirects to a resolved Hugging Face download URL for the requested model id+variant (default variant: q4_k_m). 404 for unknown variants, 410 when the variant exists but is marked unavailable.

Model recommendation + model info. Public and secret-free: this powers the post-auth model picker, CLI parity, and "which backbone should I use?" flows without requiring a tenant before the user understands the catalog.