Workflows

These workflow guides map common build intents to concrete API call sequences.

They are designed for builders and coding agents who need a practical path through the public surface.

Build a persistent session flow

Purpose: Create a long-lived interaction that carries continuity across steps.

Sequence: POST /v1/sessions → POST /v1/sessions/{session_id}/step → GET /v1/runtime/summary.

Minimal request shape:

{"continuity_mode":"preserve"}

Typical response artifact: session_id and continuity-bearing payload from step.

Common next call: GET /v1/worlds/state when output depends on shared conditions.

Purpose: Read or use world state as part of a larger system.

Sequence: GET /v1/worlds/state → session routes as needed → evidence or summary routes as needed.

Minimal request shape: no body; include X-API-Key.

Typical response artifact: world objects, condition snapshots, and history markers.

Common next call: POST /v1/sessions/{session_id}/step using current world context.

Purpose: Bring bounded external state into the system.

Sequence: POST /v1/external-events/ingest → relevant session or world routes → evidence or reconciliation views if available.

Minimal request shape: {"event_id":"...","event_kind":"...","event_action":"...","payload":{...}}.

Typical response artifact: accepted event envelope with ingest timestamp/reference.

Common next call: GET /v1/worlds/state to verify world impact.

Purpose: Propose, inspect, and govern outbound operations.

Sequence: POST /v1/external-actions/propose → approval or inspection route if available → execution or follow-on retrieval routes as supported.

Minimal request shape: {"action_id":"...","action_kind":"...","action_intent":"...","approval_required":true}.

Typical response artifact: proposed action contract and policy state.

Common next call: GET /v1/external-actions/{action_id} for governance review state.

Purpose: Retrieve structured outputs that make the system’s behaviour legible.

Sequence: session or world routes → dossier or reporting route → artifact retrieval if relevant.

Minimal request shape: {"session_id":"sess_..."} where supported.

Typical response artifact: evidence bundle identifiers and artifact paths.

Common next call: GET /v1/artifacts/{artifact_path:path} to retrieve report output.