Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/coollabsio/jean/llms.txt

Use this file to discover all available pages before exploring further.

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

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us