Runtime HTTP API

api/openapi/openapi.yaml is the canonical /v1 transport contract. The generated Go SDK and server route constants are checked against its generated public operation set.

The generated HTTP operation index lists the declared route, method, operation ID, and successful response statuses directly from that contract. It is an index, not a claim that the standalone development role provides production durability.

The v1 compatibility policy defines which route and vocabulary changes are additive versus breaking. A checked-in baseline test protects the current Agent, Policy, Tool, Event, and Failure vocabulary.

The API creates and reads immutable Agent and Policy revisions, creates and inspects Sessions, idempotently submits Input, observes Turns and cursor-addressed Product events, explicitly cancels a Turn, cancels a drained Session, and drain-closes a Session. Session cancellation is an owner-authenticated, idempotent command; it refuses to discard active or queued Turns. The public session.cancelled and session.failed events report safe terminal state but carry no provider or backend detail. Agent and Policy catalog operations require a tenant administrator. A Policy revision contains only a bounded named-Tool disposition (denied or requires_approval) and a canonical digest; it is not a credential or an execution capability. Session access is scoped to the authenticated tenant and principal; absent and unauthorized objects share the same safe not_found result.

All /v1 requests use bearer authentication and typed X-Request-ID correlation. Mutations also require Idempotency-Key. JSON and bodies are strict and bounded. Observation reconnects by requesting the next page after the last accepted opaque Cursor; a disconnect does not imply cancellation. Authenticated tenant and principal identities are canonical lower-case segments beginning with a lower-case letter or digit, with - or _ permitted after the first character. Malformed identities, including delimiters, are rejected before runtime dispatch.

Artifact streaming

GET /v1/artifacts/{artifact_id} authorizes the exact tenant, principal, and immutable Artifact metadata before it opens content storage. Its streaming form returns the media type plus X-Agent-Runtime-Artifact-Size and X-Agent-Runtime-Artifact-SHA256, transfers no more than the declared size, and emits Digest: sha-256=... only as an HTTP trailer after exact copied-byte verification. Missing, mismatched, short, or overlong bytes fail the transfer; an unfinished response must be closed to cancel its observation. Storage keys and credentials never cross this boundary.

The Go SDK keeps bounded ReadArtifact and adds a separate ArtifactStreamer capability implemented by Client.OpenArtifact. It intentionally does not widen RuntimeClient, preserving existing implementations. EOF verifies the exact size and digest; callers must close the body even after EOF.

The concrete Go client implements the separate additive SessionCanceller capability. Its CancelSession method maps to POST /v1/sessions/{session_id}/cancel; runtime-owned failure remains observation-only rather than a public mutation.

GET /v1/sessions/{session_id}/artifacts is the separate bounded, owner-scoped Artifact index used by Research Dossier. It returns metadata for Artifacts belonging to that exact Session (up to 256 entries) but never bytes, bucket names, keys, or download URLs. The additive SDK SessionArtifactLister capability and Client.ListSessionArtifacts preserve the existing RuntimeClient source contract. Each listed Artifact still needs an exact caller-authorized ReadArtifact or OpenArtifact request.

GET /healthz and GET /readyz are deliberately unauthenticated and return only the role and readiness state. The standalone process announces readiness only after strict configuration, credential lookup, and runtime composition succeed. Its readiness callback runs only once the listener is serving the health route and never after the process context is already cancelled.

Run the current local role

export AGENT_RUNTIME_ADMIN_TOKEN='replace-with-at-least-16-bytes'
export AGENT_RUNTIME_DEVELOPER_TOKEN='replace-with-at-least-16-bytes'
go run ./cmd/agent-runtime-api --config "$PWD/deploy/runtimeapi/api.example.json"

The example config contains only environment-variable names. It deliberately declares memory-unsafe storage, so state disappears on restart. This is a transport integration role, not production durability evidence. Use its plain HTTP listener only on loopback or behind an operator-owned protected transport boundary. max_request_bytes must be between 3 MiB and 16 MiB; the example uses 4 MiB.

The container composition check may instead supply that strict document through --config-env; an all-interface listener requires explicit "public_listen":true. --check validates configuration, required environment-value presence, and bearer-token shape without opening a listener or contacting PostgreSQL or object storage.

Optional request-completion logs

The standalone role emits no public /v1 API completion record by default. To opt into one JSON slog record per public API completion, add this strict configuration block and inject the named environment value at process start:

"observability": {
  "identity_correlation_key_environment": "AGENT_RUNTIME_OBSERVABILITY_KEY"
}

The key is an explicit secret of 32 to 4096 bytes. Each record contains only a canonical operation name, request ID, HTTP status, safe outcome/failure code, duration, and keyed HMAC tenant/principal correlations. It never contains the key, bearer token, idempotency key, request body, raw identity, raw URL, or backend identifier. This is a bounded process-log seam only: it is not an OTel exporter, dashboard, durable audit record, or cross-service correlation proof. Unauthenticated /healthz and /readyz probes intentionally remain outside this request-observation stream.