The Sessions API allows you to manage chat sessions within worktrees.
List Sessions
Get all sessions for a specific worktree.
The unique identifier of the worktree
Response
Array of session objects
Unique session identifier
Unix timestamp when session was created
Execution mode: plan, build, or yolo
AI model used for this session
Thinking level: off, think, megathink, or ultrathink
AI backend: claude, codex, or opencode
Unix timestamp when session was archived (if archived)
Example Request
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.
The unique identifier of the worktree
Session name (auto-generated if not provided)
Execution mode: plan, build, or yolo (default: plan)
AI model to use (inherits from project/global settings if not specified)
AI backend: claude, codex, or opencode
Response
Returns the newly created session object.
Example Request
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.
The unique identifier of the session
Response
Returns a session object with full details including message history.
Example Request
curl -X GET "http://localhost:3456/api/sessions/{sessionId}" \
-H "Authorization: Bearer YOUR_TOKEN"
Update Session
Update session properties.
The unique identifier of the session
Example Request
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).
The unique identifier of the session
Example Request
curl -X POST "http://localhost:3456/api/sessions/{sessionId}/archive" \
-H "Authorization: Bearer YOUR_TOKEN"
Delete Session
Permanently delete a session.
The unique identifier of the session
This operation is irreversible. The session and all its message history will be permanently deleted.
Example Request
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
