K2 Server API

Every K2 server exposes an HTTP API over its own your-name.k2.dev subdomain: message your agents, spawn fresh live agent sessions in any workspace, and read their answers back — from CI, from your own apps, from anywhere. The agent working the session replies with k2 respond; you read the conversation with a plain GET.

The API is agent-agnostic: workspaces configured for Claude Code, Codex, Gemini, Grok, Pi, Cursor, Hermes, or your own custom agent all speak the same endpoints. See the K2 agent contract for what a custom agent needs to participate.

Requirements. A K2 server on v0.40.30+ with the API enabled (K2 Cloud servers ship with it on; self-hosted daemons set K2_API=1), reachable through a Pro subdomain — API calls over the tunnel are a Pro feature. Host-session listing/resume needs v0.40.30; the message API works on earlier 0.40.2x servers too.

Authentication

Create an API key on the server (K2 app → Settings → API Keys, or over the owner CLI). Keys look like k2sk_… and are shown once at creation — K2 stores only a hash. Present the key on every request; the Authorization header is preferred (keeps it out of URLs and logs), ?token= works as a curl fallback.

curl https://your-name.k2.dev/v1/ping \
  -H "Authorization: Bearer k2sk_XXXXXXXXXXXXXXXXXXXX"

Capability discovery

GET/v1/ping

Liveness plus what this server has enabled — probe this first and feature-gate your client on it.

{
  "ok": true,
  "api": {
    "enabled": true,
    "hostSessions": true,     // spawn/list/resume live agent sessions
    "sandboxes": "none"       // "microvm" on Dedicated servers
  }
}

Message a workspace's agent

POST/v1/w/<workspace>/message

Deliver a message into the workspace's canonical agent session (the same session you see in the app), waking it if needed. <workspace> is the workspace name as shown in K2.

curl -X POST https://your-name.k2.dev/v1/w/my-project/message \
  -H "Authorization: Bearer k2sk_..." \
  -H "Content-Type: application/json" \
  -d '{"message": "Summarize today's failing tests."}'

Host sessions — spawn agents that answer back

Host sessions are fresh, API-owned agent sessions: each spawn boots the workspace's configured agent in a real terminal, briefs it that an API caller is listening, and gives it a private scoped token so its k2 respond output lands in your conversation — and only yours. One session is one conversation; for concurrent requests, spawn concurrent sessions.

POST/v1/w/<workspace>/host-sessions

Spawn a session with an initial prompt. Pass "session"with a previously returned id to resume that conversation instead — if it's still live the message is delivered into the running agent (no double-boot); if it has exited, the agent is relaunched resuming the same conversation.

// request
{ "prompt": "Run the test suite and report failures." }

// 200 — fresh spawn
{
  "sessionId": "6f0c9a52-…",
  "agentName": "api-20260707-…",
  "workspace": "my-project",
  "sandbox": "none",
  "stream": { "grid": "/cli/sessions/grid?session=…&token=k2st_…" }
}

// 200 — resume of a still-live session
{ "sessionId": "6f0c9a52-…", "delivered": true, "live": true }

By default the agent runs with its auto-approve flags stripped — an unattended server never bypasses permission prompts just because a request came in over the wire. Opt a workspace in deliberately with the api_skip_permissions workspace setting.

GET/v1/w/<workspace>/host-sessions

List this workspace's API-spawned sessions.

{
  "workspace": "my-project",
  "sessions": [
    { "sessionId": "6f0c9a52-…", "agentName": "api-…", "live": true, "lastSeenAt": "…" }
  ]
}

POST/v1/w/<workspace>/host-sessions/<id>

Send a follow-up message into a live session's terminal.

// request
{ "message": "Now fix the first failure." }

// 200
{ "sessionId": "6f0c9a52-…", "delivered": true, "live": true }

GET/v1/w/<workspace>/host-sessions/<id>/messages?since=<seq>

Read the agent's replies. seq is monotonic per session and reads are non-destructive — keep your last latest_seq as a cursor and poll. Entries with "final": true are the agent's k2 respond --final answers.

{
  "messages": [
    { "seq": 1, "text": "3 tests failing in auth.rs — details follow.", "ts": 1783460000, "final": false },
    { "seq": 2, "text": "Fixed. All 214 tests pass.", "ts": 1783460420, "final": true }
  ],
  "latest_seq": 2
}

Errors

Unknown workspaces, unknown sessions, and things you're not allowed to see are indistinguishable by design — all return the same 404 body, so the API never confirms what exists. Malformed requests return 400 with a plain error string; session-spawn quotas return 429 with an error and code.

404 { "error": "no such workspace" }

Sandboxes (Dedicated)

Dedicated servers add a hardened microVM sandbox API — the same session model, but each agent boots inside its own isolated Linux virtual machine, built for untrusted workloads and agent fleets. Capability shows as "sandboxes": "microvm" on /v1/ping. Full sandbox documentation ships alongside Dedicated availability.

Questions or missing endpoints? Ask in Discord or open an issue on GitHub.