API contract inventory

This page is the post-baseline inventory for Holon's HTTP control-plane API. It complements the HTTP control plane reference by recording the route list, request parameters, response shapes, and contract gaps that still need stabilization before scripts and integrations can rely on the API long term.

• Last reviewed against: holon v0.14.1, main at bff2293.
• Primary source: src/http.rs Axum router and request/response structs.
• Generated schema: openapi.json, produced by holon::openapi::generate_openapi_json() and checked by cargo test --test openapi_snapshot.
• Route/schema drift check: tests/snapshots/http_route_inventory.json, produced from the Axum route tree and generated OpenAPI baseline by cargo test --test http_route_snapshot.
• Client source: src/client.rs for the subset consumed by the TUI/CLI.
• Current status: pre-1.0 baseline. Treat shapes below as observed behavior, not a final compatibility promise. Milestone 8 established the first checked baseline; the remaining gaps are Phase 2 stabilization work.

Stability levels

Cross-cutting contracts

Transport and authentication

Ingress trust/auth boundaries

Common JSON and response behavior

Most successful responses are JSON, but Holon does not use one global success envelope. The stable policy is route-class based:

Representative current examples:

• / and /handshake return { "ok": true, ... }.
• /models returns { "available_models": ..., "model_availability": ... } without an ok field.
• /agents/list, /agents/:id/status, /agents/:id/state, /agents/:id/tasks, and similar read routes return direct records or arrays.
• /control/agents/:id/prompt, /control/agents/:id/wake, and workspace/model mutation routes return { "ok": true, ... }.
• /control/agents/:id/tasks, /control/agents/:id/work-items, and /control/agents/:id/timers return the created record directly.
• /agents/:id/events/stream returns Server-Sent Events rather than a JSON response body after the stream opens.

Handler-produced control-plane errors use one shared JSON envelope:

{
  "ok": false,
  "error": "message",
  "code": "machine_readable_code",
  "hint": "optional operator guidance"
}

For those handler-produced errors, ok is always false; error is a human-readable message. code and hint are optional shared fields. Routes may add documented route-specific extension fields alongside the shared fields. Framework-level rejections produced before a handler runs, such as Axum extractor failures for malformed JSON or request bodies rejected by DefaultBodyLimit, are not yet normalized into this envelope.

Status-code mapping:

Common route-specific error extensions currently include:

Known stable error code values:

src/client.rs decodes this envelope compatibly: it requires only error for display and preserves optional code and hint in LocalHttpError. Unknown extension fields are ignored by the client unless a caller inspects the raw response directly.

Endpoint inventory

Discovery and runtime

Agent read model

Default-agent aliases:

Events and streams

Event page cursors are exclusive: after_seq returns records with higher event_seq, before_seq returns records with lower event_seq, and combining both returns after_seq < event_seq < before_seq. SSE streams start after the current tail when after_seq is omitted, replay from the current replay window when after_seq=0, and return 404 cursor_not_found before opening the stream when a non-zero after_seq is outside that replay window.

Stable StreamEventEnvelope fields:

{
  "id": "event-uuid",
  "event_seq": 42,
  "ts": "2026-05-24T00:00:00Z",
  "agent_id": "main",
  "type": "task_created",
  "provenance": { "authority_class": "operator_instruction", "task_id": "task-..." },
  "payload": {}
}

Event payloads are the protocol standard and are included in full. The events page may filter event inclusion with max_level=info|verbose|debug; filtering does not alter payload. The live event stream is raw and does not support level filtering.

Breaking migration from the removed projection contract:

• delete projection=operator / projection=local_debug from event page and stream requests
• stop reading StreamEventEnvelope.projection; all envelopes now include the full standard payload
• use /agents/:id/events?max_level=info for an operator-density historical page and client-side filtering for the raw stream

Public ingress

EnqueueRequest fields:

Control actions

Tasks, work items, and timers

CreateCommandTaskRequest fields:

Workspace and model controls

Operator transport integration

OperatorTransportBindingRequest is strict (deny_unknown_fields) and contains binding_id?, transport, operator_actor_id, target_agent_id?, default_route_id, delivery_callback_url, delivery_auth, capabilities, provider?, provider_identity_ref?, and metadata?.

delivery_auth.kind = "bearer" requires a non-empty bearer_token. delivery_auth.kind = "hmac" is rejected until HMAC signing is implemented.

Skills

Callback capability ingress

Body decoding rules:

• JSON content types become MessageBody::Json.
• text/* content types become MessageBody::Text.
• Other typed bodies become JSON with content_type and body_base64.
• Untyped UTF-8 bodies become text; non-UTF-8 bodies become JSON with body_base64.

Shared record shapes to stabilize

The following response types are exposed by multiple endpoints and should be treated as schema surfaces, not incidental Rust structs:

Detected contract gaps

1. OpenAPI route/type metadata is still only partially colocated with implementation. Route coverage and schema snapshots now exist, but the generated baseline still depends on a conservative OpenAPI table. Phase 2 moves operation metadata closer to Axum route/type definitions.
2. Stable DTO schemas need tightening. Several task, work-item, timer, agent, event, and envelope responses are still represented broadly in the OpenAPI baseline and should become first-class typed components where they are stable client contracts.
3. Event level filtering needs more real-world coverage. max_level inclusion rules should be validated against real TUI/client sessions before they are treated as final.
4. WorkItem mutation APIs now cover focus/update/complete. HTTP can list/get/create/enqueue, pick focus, update objective/planning/blocker fields, and complete work items. Cancel/delete remains intentionally out of scope until a distinct lifecycle contract is needed.
5. Timer lifecycle APIs now cover cancellation. HTTP can create/list/get timers and cancel active timers. Delete/purge remains out of scope.
6. Deployment guidance still needs hardening. The HTTP ingress trust/auth table is documented, but production-facing guidance should still describe when to use bearer mode, local mode, callback capabilities, and dedicated operator adapters.
7. Tool schema is a separate API surface. Built-in tool input/result schemas now have their own checked inventory; this HTTP inventory should link to it rather than duplicate it.

Tracking issues

Milestone 8 baseline issues are complete. Phase 2 follow-up issues are grouped under the same CLI/API Stability Contracts milestone and tracked by #1444.

Suggested next work

1. Migrate the OpenAPI baseline toward aide route/type metadata (#1438).
2. Tighten DTO schemas for stable read models and control-plane results (#1439).
3. Define the stable operator-facing event payload subset (#1443).