Skip to main content
A session id is cs_ followed by 16 characters. Fields of the Session object: API schema.

Status

Each change is a session.status_changed event with from and to.

Create and list

HTTP only: POST /sessions with a CreateSessionBody, and GET /sessions.
Every field is optional (API schema). id is a session id chosen by the client; input is the first message. Accepted values for model, effort, speed and mode are in the session’s capabilities.

Read

sessions.get (GET /sessions/{id}) returns the Session, including the active turn id, queued turns, open asks, running subagents and lastSeq. minSeq waits for the journal: Session journal.

Attach

sessions.attach (WebSocket only) subscribes the connection to the session’s events. It returns the session and its capabilities: models with their effort levels, permission modes, and features.

Update

sessions.update (PATCH /sessions/{id}) changes any of title, model, effort, speed, mode, archived and metadata. It returns the session and a seq.

Compact

sessions.compact (POST /sessions/{id}/compact) queues a compaction as a turn and returns the same result as turns.send. instructions (up to 10,000 characters) is passed to the harness’s /compact command. The session.compacted event gives beforeTokens, afterTokens and auto (true when the harness compacted on its own). See Context and compaction.

Suspend

sessions.suspend (POST /sessions/{id}/suspend) stops the session’s runner. The journal and workspace stay on the computer. Suspending cancels queued turns, stops running subagents, closes open asks as interrupted, and records runtime.suspended with reason: "requested". The other reasons are idle and lost.

Resume

sessions.resume (POST /sessions/{id}/resume) starts the runtime of a suspended session and returns at once; runtime.starting and runtime.connected events follow. On a session that is not suspended it returns the session unchanged. Sending a turn to a suspended session also starts it.