Skip to main content

​
Control plane API

Kheish serves its operator-facing HTTP API under /v1/. Most endpoints return JSON. Three categories are intentionally different:
  • SSE streams:
    • GET /v1/events/stream
    • GET /v1/sessions/{session_id}/stream
    • GET /v1/runs/{run_id}/stream
    • GET /v1/flows/{flow_id}/stream
  • Raw bytes:
    • GET /v1/assets/{asset_id}/raw
  • Raw UTF-8 text:
    • GET /v1/runs/{run_id}/debug/artifacts/{artifact_id}

​
Auth boundaries

Kheish has three distinct HTTP trust zones:
  1. Control plane
    • Playbook, Flow, project, channel, session, run, runtime, task, schedule, agent, asset, persona, skill, observation-management, and derivation endpoints.
    • Protected by the daemon’s control-plane auth middleware when HTTP auth is enabled.
  2. Connector ingress
    • POST /v1/connectors/http/{name}
    • POST /v1/connectors/slack/{name}
    • POST /v1/connectors/telegram/{name}
    • GET /v1/connectors/external/{name}/credentials/{env_key}
    • Auth is connector-specific and separate from control-plane auth. The external connector credential route returns one raw secret value only when the caller presents a valid brokered lease token.
  3. Observation upload ingress
    • POST /v1/observation-sources/{source_id}/observations
    • Uses one source-scoped bearer token, not the admin control-plane token.

​
Common response patterns

The API does not wrap every result in a generic envelope. Most routes return the concrete view directly. Typical status codes:
  • 200 OK for reads and in-place mutations
  • 201 Created for resource creation such as personas, sessions, and schedules
  • 202 Accepted for detached run submissions and mailbox posts
  • 400 Bad Request for invalid payloads, malformed multimodal input, invalid route combinations, or invalid selection criteria
  • 404 Not Found for unknown sessions, runs, personas, assets, observations, derivations, skills, or connectors
  • 409 Conflict for runtime state conflicts such as persona/capability/credential rebinding while a session is not idle, connector mutation of file-backed config, or duplicate persona identifiers

​
Streaming surfaces

Use SSE when you need a live operator view instead of polling. 
curl -N http://127.0.0.1:4000/v1/events/stream
curl -N http://127.0.0.1:4000/v1/sessions/demo/stream
curl -N http://127.0.0.1:4000/v1/runs/run-1/stream
curl -N http://127.0.0.1:4000/v1/flows/flow-1/stream
Current SSE event names on the daemon bus include:
  • trace
  • session_state_changed
  • session_snapshot
  • output
  • run_updated
  • interrupted
  • runtime_updated
The session, run, and Flow stream endpoints are filtered views over that shared daemon event bus. Flow streaming is a proxy over the referenced root run stream; it does not create a second Flow event bus.

​
Reference map

Use the dedicated reference pages below instead of treating this page as the full API spec:
  • Runtime API for:
    • /v1/capabilities
    • /v1/runtime
    • /v1/runtime/learning-policy
    • /v1/runtime/secrets
    • /v1/runtime/auth/subjects/{subject_id}
    • /v1/runtime/auth/leases/{lease_id}
    • /v1/runtime/hooks
    • /v1/runtime/debug-level
    • /v1/events/stream
  • Channels API for:
    • /v1/channels
    • channel members
    • public messages
    • reactions
    • public turn leases
    • channel stimuli
    • canonical thread-work state
  • Projects API for:
    • /v1/projects
    • project members
    • linked channels
    • project tasks
    • project-task start
  • Playbooks and flows API for:
    • /v1/playbooks
    • /v1/playbooks/validate
    • /v1/playbooks/{playbook_id}/publish
    • /v1/playbooks/{playbook_id}/revoke
    • /v1/flows
    • /v1/flows/{flow_id}/stream
  • Sessions and runs API for:
    • /v1/sessions
    • /v1/runs
    • session input, route policy, capability scope, credential scope, reply targets, memory context, memory search, run external actions, and run debug
  • Learnings API for:
    • /v1/learning-candidates
    • /v1/learnings
    • /v1/learnings/revoke-matching
    • /v1/learning-skills
    • promoted procedural skills
  • Questions and approvals API for:
    • /v1/questions
    • /v1/sessions/{session_id}/approvals
    • /v1/sessions/{session_id}/questions
    • /v1/sessions/{session_id}/approval-runs
    • /v1/runs/{run_id}/approvals
    • /v1/runs/{run_id}/questions
  • Tasks, schedules, and agents API for:
    • /v1/sessions/{session_id}/tasks
    • /v1/schedules
    • /v1/agents
    • /v1/mailboxes
  • Observations and derivations API for:
    • /v1/observation-sources
    • /v1/observations
    • /v1/observation-materializations
    • /v1/derivations
  • Connectors API for:
    • /v1/runtime/connectors
    • /v1/connectors/http/{name}
    • /v1/connectors/slack/{name}
    • /v1/connectors/telegram/{name}
  • Assets API for:
    • /v1/assets
  • Personas API for:
    • /v1/personas
    • session persona binding endpoints
  • Skills API for:
    • /v1/skills

​
Route groups at a glance

The actual control-plane router currently exposes these groups:
  • capabilities and runtime
  • runtime secrets
  • runtime auth subjects and leases
  • runtime connectors
  • learning candidates, learnings, and promoted learning skills
  • assets
  • observation sources, observations, and observation materializations
  • derivations
  • skills
  • personas
  • channels
  • projects
  • playbooks and flows
  • sessions
  • runs
  • tasks
  • questions and approvals
  • schedules
  • agents and mailboxes
  • daemon-wide, session-scoped, and run-scoped event streams
Connector ingress and observation upload ingress are mounted separately and intentionally sit outside the operator control-plane auth middleware.

​
Evidence Note

  • Code verified: crates/kheish-daemon/src/api/handlers.rs, crates/kheish-daemon/src/cli/commands/playbooks.rs, crates/kheish-daemon/src/playbooks.rs.
  • CLI/API verified: Playbook/Flow route names and Flow stream behavior checked against the current router and CLI.
  • Daemon live tested for this note: no; this page is a route map.
  • Provider-specific tested for this note: no; these control-plane routes are provider-neutral.