K2 Server API

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"

Create an API key

curl -X POST "https://your-name.k2.dev/cli/api-keys/create?token=<owner-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "ci-runner",
    "workspaces": ["my-project", "docs-site"],
    "provider": "anthropic",
    "capabilities": { "hostSessions": true, "canonicalMessage": false, "sandboxes": false }
  }'

// 200
{
  "id": "e7c1a0d4-…",
  "key": "k2sk_XXXXXXXXXXXXXXXXXXXX",
  "capabilities": { "hostSessions": true, "canonicalMessage": false, "sandboxes": false }
}

Bring your own LLM key

Pass anthropicKey(or the provider-appropriate credential) at key creation. K2 stores it per-key and, on every host-session spawn made with that key, injects it into the agent's process environment — so the agent runs on yourLLM billing, not the server's. The credential is set at create time only and is never logged.

Which environment variables get staged depends on the key's provider:

anthropic  →  ANTHROPIC_API_KEY
openai     →  OPENAI_API_KEY   (+ OPENAI_BASE_URL if baseUrl is set)
google     →  GEMINI_API_KEY, GOOGLE_API_KEY
xai        →  XAI_API_KEY

Capability discovery

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

Message a workspace's agent

curl -X POST https://your-name.k2.dev/v1/w/my-project/message \
  -H "Authorization: Bearer k2sk_..." \
  -H "Content-Type: application/json" \
  -d '{"text": "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.

// request — fresh spawn
{
  "prompt": "Run the test suite and report failures.",
  "timeout_secs": 600
}

// request — resume an earlier conversation (field name is "session")
{ "session": "6f0c9a52-…", "prompt": "Now fix the first failure." }

// 200 — fresh spawn
{
  "sessionId": "6f0c9a52-…",
  "agentName": "api-owner-8f3b1c20-…",
  "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, "resumed": true }

// owner opt-out: value must be exactly "0" or "1"
//   "1" = on (keep auto-approve)   "0" = opt out (strip auto-approve/danger flags)
curl -X POST "https://your-name.k2.dev/cli/workspace/set?token=<owner-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "/abs/path/to/my-project",
    "fields": { "api_skip_permissions": "0" }
  }'

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

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

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

{
  "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
}

curl -X POST https://your-name.k2.dev/v1/w/my-project/host-sessions/6f0c9a52-…/kill \
  -H "Authorization: Bearer k2sk_…"

// 200 — was live
{ "sessionId": "6f0c9a52-…", "killed": true }

// 200 — owned but already dead (idempotent)
{ "sessionId": "6f0c9a52-…", "killed": false, "reason": "not_live" }

// 404 — unknown, unowned, or wrong workspace (uniform; no existence oracle)

Capability envelope (multi-turn apps)

For multi-turn or long-running agents, pass a capabilities array at spawn (and re-send on each resume/message when you remint). The daemon mints short-lived capability JWTs the agent uses to call your app — not a substitute for the k2sk_control key. Verify tokens against the server's public JWKS:

curl https://your-name.k2.dev/v1/jwks

Full wire samples, remint rules, and resource namespaces: host-session capability envelope.

Streaming: the grid WebSocket

A spawn response carries stream.grid — e.g. /cli/sessions/grid?session=<uuid>&token=k2st_…— a relative path. Build the WebSocket URL from your subdomain and open it to watch the agent's terminal live:

wss://your-name.k2.dev/cli/sessions/grid?session=<uuid>&token=k2st_…

The connection is authorized by the per-session k2st_ stream token, not your API key. That token is scoped to this one session and is revoked when the session exits.

Every server-to-client frame is a JSON envelope { "event": "<kind>", "payload": { … } }. On connect you receive one read-only snapshot, then incremental delta frames, plus title, label_changed, pin_changed, and child_exit events.

// snapshot — full terminal state (camelCase)
{
  "event": "snapshot",
  "payload": {
    "paneId": "…", "cols": 120, "rows": 40,
    "grid": [ [ /* CellRun[] per row, run-length encoded */ ] ],
    "scrollback": [ /* rows of CellRun[] */ ],
    "cursor": { "row": 3, "col": 12, "visible": true },
    "version": 1, "displayOffset": 0, "altScreen": false
  }
}

// a CellRun — fg/bg are 0xRRGGBB ints, or null for the theme default
{ "text": "PASS", "fg": 39423, "bg": null,
  "bold": true, "italic": false, "underline": false }

// delta — apply on top of the last state
{
  "event": "delta",
  "payload": {
    "paneId": "…", "cols": 120, "rows": 40,
    "damagedRows": [ { "row": 7, "runs": [ /* CellRun[] */ ] } ],
    "scrollbackAppended": [ /* rows of CellRun[] */ ],
    "cursor": { "row": 8, "col": 0, "visible": true },
    "version": 2
  }
}

Apply a delta by replacing each damagedRows entry at its row index, appending scrollbackAppended, and absorbing the new cursor and version.

Drive the session by sending text frames back over the same socket:

{ "action": "input", "text": "yes\n" }
{ "action": "resize", "cols": 100, "rows": 30 }

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.