Skip to main content

​
session.create

Create a new conversation session.

​
Request

{"jsonrpc":"2.0","id":1,"method":"session.create","params":{"title":"My Conversation"}}

​
Parameters

​
title
string
Optional title for the session

​
Response

​
session_id
string
required
Unique session identifier (UUID)
​
state
object
required
Full session state object (see session.get for structure)

​
Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "state": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "pending": false,
      "statusLabel": "ready",
      "messages": [],
      "history": [],
      "queue": [],
      "pendingSteerCount": 0,
      "conversationProvider": null,
      "activeSessionId": null,
      "contextTokenEstimate": 0,
      "contextTokenSource": "none",
      "contextTokenProvider": null,
      "contextTokenBreakdown": {}
    }
  }
}

​
session.get

Retrieve the current state of a session.

​
Request

{"jsonrpc":"2.0","id":2,"method":"session.get","params":{"session_id":"550e8400-e29b-41d4-a716-446655440000"}}

​
Parameters

​
session_id
string
required
The session ID to retrieve

​
Response

​
id
string
required
Session ID
​
createdAt
string
required
ISO 8601 timestamp of creation
​
updatedAt
string
required
ISO 8601 timestamp of last update
​
pending
boolean
required
Whether the session is currently processing
​
statusLabel
string
required
Human-readable status: "ready", "thinking...", "interrupting...", etc.
​
messages
array
required
Array of conversation messages
​
history
array
required
Full conversation history (internal format)
​
queue
array
required
Queued prompts waiting to be processed
​
pendingSteerCount
number
required
Number of pending steering interventions
​
conversationProvider
string
The provider used for this conversation: "openai", "openrouter", or "antigravity"
​
activeSessionId
string
Active Claude session ID (if any)
​
contextTokenEstimate
number
required
Estimated token count for current context
​
contextTokenSource
string
required
Source of token estimate
​
contextTokenProvider
string
Provider used for token estimation
​
contextTokenBreakdown
object
required
Detailed breakdown of token usage

​
Example

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:05.000Z",
    "pending": false,
    "statusLabel": "ready",
    "messages": [
      {"role": "user", "content": "Hello"},
      {"role": "assistant", "content": "Hi there!"}
    ],
    "history": [],
    "queue": [],
    "pendingSteerCount": 0,
    "conversationProvider": "openai",
    "activeSessionId": null,
    "contextTokenEstimate": 245,
    "contextTokenSource": "estimate",
    "contextTokenProvider": "openai",
    "contextTokenBreakdown": {}
  }
}

​
session.send

Send a user prompt to a session. The session will process the prompt asynchronously and emit events.

​
Request

{"jsonrpc":"2.0","id":3,"method":"session.send","params":{"session_id":"550e8400-e29b-41d4-a716-446655440000","text":"Write a hello world program"}}

​
Parameters

​
session_id
string
required
The session ID to send the prompt to
​
text
string
The user prompt text (required unless images are provided)
​
images
array
Array of image inputs (paths or data URLs)
​
enqueue
boolean
default:false
If true, queue the prompt if session is busy. If false (default), return error if busy.

​
Response

​
session_id
string
required
The session ID
​
turn_id
string
required
Unique turn identifier (UUID)
​
accepted
boolean
required
Whether the prompt was accepted
​
queued
boolean
required
Whether the prompt was queued (vs. started immediately)

​
Example

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "turn_id": "660e8400-e29b-41d4-a716-446655440001",
    "accepted": true,
    "queued": false
  }
}
After sending a prompt, listen for event notifications to track progress:
  • session.status - Status updates
  • session.stream.chunk - Streaming response chunks
  • session.tool.call.started - Tool calls
  • session.completed - Turn completed
  • session.error - Error occurred

​
session.steer

Inject a steering message during an active turn to guide the assistant’s behavior.

​
Request

{"jsonrpc":"2.0","id":4,"method":"session.steer","params":{"session_id":"550e8400-e29b-41d4-a716-446655440000","text":"Make it more concise"}}

​
Parameters

​
session_id
string
required
The session ID to steer
​
text
string
required
Steering instruction text (must be non-empty)

​
Response

​
session_id
string
required
The session ID
​
accepted
boolean
required
Whether the steering was accepted (only works during active turns)

​
Example

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "accepted": true
  }
}
Steering only works when a session is actively processing (pending=true). If the session is not busy, accepted will be false.

​
session.interrupt

Interrupt an active session turn. The assistant will stop processing and emit a session.interrupted event.

​
Request

{"jsonrpc":"2.0","id":5,"method":"session.interrupt","params":{"session_id":"550e8400-e29b-41d4-a716-446655440000"}}

​
Parameters

​
session_id
string
required
The session ID to interrupt

​
Response

​
session_id
string
required
The session ID
​
interrupted
boolean
required
Whether an active turn was interrupted. Returns false if no turn was active.

​
Example

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "interrupted": true
  }
}

​
session.queue.list

List queued prompts for a session.

​
Request

​
session_id
string
required
Session ID
{"jsonrpc":"2.0","id":6,"method":"session.queue.list","params":{"session_id":"ses_abc123"}}

​
Response

​
queue
array
required
Array of queued prompt objects
{"jsonrpc":"2.0","id":6,"result":{"queue":[{"text":"Write a function","queued_at":"2026-01-01T00:00:00.000Z"}]}}

​
session.queue.clear

Clear all queued prompts for a session.

​
Request

​
session_id
string
required
Session ID
{"jsonrpc":"2.0","id":7,"method":"session.queue.clear","params":{"session_id":"ses_abc123"}}

​
Response

{"jsonrpc":"2.0","id":7,"result":{"ok":true,"cleared":2}}

​
history.list

List saved chat sessions.

​
Request

​
limit
number
Maximum number of sessions to return (default: 50)
​
cursor
number
Pagination cursor (session index to start from)
{"jsonrpc":"2.0","id":8,"method":"history.list","params":{"limit":10}}

​
Response

​
sessions
array
required
Array of session summaries with id, title, created_at, updated_at, and message_count
{"jsonrpc":"2.0","id":8,"result":{"sessions":[{"id":"550e8400-e29b-41d4-a716-446655440000","title":"Building a React app","created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T01:00:00.000Z","message_count":12}]}}

​
history.get

Load a saved chat session.

​
Request

​
id
string
Session ID to load
​
last
boolean
default:false
If true, load the most recent session
​
rollout_path
string
Optional path to a specific JSONL session file
{"jsonrpc":"2.0","id":9,"method":"history.get","params":{"id":"550e8400-e29b-41d4-a716-446655440000"}}

​
Response

​
session
object
required
Complete session object with id, title, messages, and metadata
{"jsonrpc":"2.0","id":9,"result":{"session":{"id":"550e8400-e29b-41d4-a716-446655440000","title":"Building a React app","messages":[{"role":"user","content":"How do I create a React component?"}]}}}

​
history.clear_session

Clear conversation history for a specific session.

​
Request

​
session_id
string
required
Session ID to clear
{"jsonrpc":"2.0","id":10,"method":"history.clear_session","params":{"session_id":"ses_abc123"}}

​
Response

{"jsonrpc":"2.0","id":10,"result":{"ok":true}}

Build docs developers (and LLMs) love

Get started for freeTalk to us