Sessions API

API endpoints for managing chat sessions

The Sessions API allows you to manage chat sessions within worktrees.

List Sessions

Get all sessions for a specific worktree.

worktreeId · string · required

The unique identifier of the worktree

Response

sessions · array

Array of session objects

Show Session Object

id · string

Unique session identifier

worktree_id · string

Parent worktree ID

name · string

Session name

created_at · number

Unix timestamp when session was created

execution_mode · string

Execution mode: plan, build, or yolo

model · string

AI model used for this session

thinking_level · string

Thinking level: off, think, megathink, or ultrathink

backend · string

AI backend: claude, codex, or opencode

archived_at · number

Unix timestamp when session was archived (if archived)

Example Request

cURL

curl -X GET "http://localhost:3456/api/worktrees/{worktreeId}/sessions" \
  -H "Authorization: Bearer YOUR_TOKEN"

Create Session

Create a new chat session in a worktree.

worktreeId · string · required

The unique identifier of the worktree

name · string

Session name (auto-generated if not provided)

execution_mode · string

Execution mode: plan, build, or yolo (default: plan)

model · string

AI model to use (inherits from project/global settings if not specified)

backend · string

AI backend: claude, codex, or opencode

Response

Returns the newly created session object.

Example Request

cURL

curl -X POST "http://localhost:3456/api/worktrees/{worktreeId}/sessions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Feature implementation",
    "execution_mode": "plan",
    "backend": "claude"
  }'

Get Session

Retrieve details about a specific session.

sessionId · string · required

The unique identifier of the session

Response

Returns a session object with full details including message history.

Example Request

cURL

curl -X GET "http://localhost:3456/api/sessions/{sessionId}" \
  -H "Authorization: Bearer YOUR_TOKEN"

Update Session

Update session properties.

sessionId · string · required

The unique identifier of the session

name · string

New session name

execution_mode · string

New execution mode

Example Request

cURL

curl -X PATCH "http://localhost:3456/api/sessions/{sessionId}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated feature name"
  }'

Archive Session

Archive a session (soft delete).

sessionId · string · required

The unique identifier of the session

Example Request

cURL

curl -X POST "http://localhost:3456/api/sessions/{sessionId}/archive" \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete Session

Permanently delete a session.

sessionId · string · required

The unique identifier of the session

This operation is irreversible. The session and all its message history will be permanently deleted.

Example Request

cURL

curl -X DELETE "http://localhost:3456/api/sessions/{sessionId}" \
  -H "Authorization: Bearer YOUR_TOKEN"

WebSocket Events

When connected to the WebSocket, you’ll receive real-time updates about session changes:

Session Created

{
  "event": "session-created",
  "data": {
    "session": { /* session object */ }
  }
}

Session Updated

{
  "event": "session-updated",
  "data": {
    "session_id": "uuid",
    "updates": { /* changed fields */ }
  }
}

Session Archived

{
  "event": "session-archived",
  "data": {
    "session_id": "uuid"
  }
}

Session Deleted

{
  "event": "session-deleted",
  "data": {
    "session_id": "uuid"
  }
}

Next Steps

Chat API

Send messages and receive responses in a session

Worktrees API

Manage worktrees that contain sessions