Chat API

API endpoints for sending messages and receiving AI responses

The Chat API enables you to send messages to AI assistants and receive responses through HTTP requests or WebSocket connections.

Send Message

Send a message to an AI assistant in a chat session.

sessionId · string · required

The unique identifier of the session

message · string · required

The message text to send to the AI

files · array

Optional array of file paths to include as context

images · array

Optional array of image file paths to include

Response

message_id · string

Unique identifier for the sent message

status · string

Message status: sent, processing, or completed

Example Request

cURL

curl -X POST "http://localhost:3456/api/sessions/{sessionId}/messages" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Implement a new user authentication feature",
    "files": ["src/auth.ts", "src/types/user.ts"]
  }'

Example Response

{
  "message_id": "msg_abc123",
  "status": "processing"
}

Stream Messages (WebSocket)

For real-time chat interactions, use the WebSocket connection to stream messages and responses.

Connect to WebSocket

const ws = new WebSocket('ws://localhost:3456/ws?token=YOUR_TOKEN');

ws.onopen = () => {
  console.log('Connected to Jean WebSocket');
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

Send Message via WebSocket

ws.send(JSON.stringify({
  type: 'send_message',
  session_id: 'session_uuid',
  message: 'Add error handling to the login function',
  files: ['src/auth/login.ts']
}));

Receive Streaming Response

As the AI generates a response, you’ll receive multiple events:

Message Started

{
  "event": "message-started",
  "data": {
    "message_id": "msg_abc123",
    "session_id": "session_uuid"
  }
}

Content Delta

Streaming chunks of the AI’s response:

{
  "event": "content-delta",
  "data": {
    "message_id": "msg_abc123",
    "content": "I'll add comprehensive error handling...",
    "content_index": 0
  }
}

Tool Use

When the AI uses a tool (e.g., editing a file):

{
  "event": "tool-use",
  "data": {
    "message_id": "msg_abc123",
    "tool_name": "edit_file",
    "tool_input": {
      "file_path": "src/auth/login.ts",
      "old_content": "...",
      "new_content": "..."
    }
  }
}

Message Completed

{
  "event": "message-completed",
  "data": {
    "message_id": "msg_abc123",
    "session_id": "session_uuid",
    "stop_reason": "end_turn",
    "usage": {
      "input_tokens": 1250,
      "output_tokens": 856,
      "cache_creation_input_tokens": 0,
      "cache_read_input_tokens": 800
    }
  }
}

Message Error

{
  "event": "message-error",
  "data": {
    "message_id": "msg_abc123",
    "error": "Rate limit exceeded",
    "error_type": "rate_limit_error"
  }
}

Get Message History

Retrieve all messages in a session.

sessionId · string · required

The unique identifier of the session

limit · number

Maximum number of messages to return (default: 100)

offset · number

Number of messages to skip (for pagination)

Response

messages · array

Array of message objects

Show Message Object

id · string

Unique message identifier

role · string

Message role: user or assistant

content · array

Array of content blocks (text, tool use, tool result)

timestamp · number

Unix timestamp when message was created

usage · object

Token usage statistics

Example Request

cURL

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

Stop Generation

Stop the AI from generating a response mid-stream.

sessionId · string · required

The unique identifier of the session

Example Request

cURL

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

Approve Plan

When a session is in plan mode and has proposed changes, approve the plan to execute it.

sessionId · string · required

The unique identifier of the session

mode · string · required

Execution mode for approved plan: build or yolo

Example Request

cURL

curl -X POST "http://localhost:3456/api/sessions/{sessionId}/approve" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "build"
  }'

Answer Question

When the AI asks a question (waiting state), provide an answer.

sessionId · string · required

The unique identifier of the session

answer · string · required

The answer to the AI’s question

Example Request

cURL

curl -X POST "http://localhost:3456/api/sessions/{sessionId}/answer" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "answer": "Yes, please implement the retry logic with exponential backoff"
  }'

WebSocket Connection

The WebSocket connection provides bidirectional real-time communication.

Authentication

Include your token as a query parameter:

ws://localhost:3456/ws?token=YOUR_TOKEN

Dual Emission

Jean uses a dual emission pattern for WebSocket events:

1. Global broadcast: All events are sent to all connected clients
2. Targeted emission: Events related to a specific session are also sent to clients that have subscribed to that session

This allows you to:

• Listen to all activity across Jean (for dashboard views)
• Subscribe to specific sessions for focused updates

Subscribe to Session

ws.send(JSON.stringify({
  type: 'subscribe',
  session_id: 'session_uuid'
}));

Unsubscribe from Session

ws.send(JSON.stringify({
  type: 'unsubscribe',
  session_id: 'session_uuid'
}));

Error Responses

The Chat API returns standard HTTP error codes:

Status Code	Description
400	Bad Request - Invalid message format or parameters
401	Unauthorized - Missing or invalid token
404	Not Found - Session does not exist
429	Rate Limit Exceeded - Too many requests
500	Internal Server Error - Server-side error

Example Error Response

{
  "error": "Session not found",
  "error_type": "not_found",
  "session_id": "invalid_uuid"
}

Best Practices

Use WebSocket for interactive chat

For real-time chat interactions, use the WebSocket connection to receive streaming responses and immediate updates. HTTP requests are better suited for batch operations or simple queries.

Handle reconnection

WebSocket connections can drop. Implement reconnection logic with exponential backoff to maintain a stable connection.

let reconnectDelay = 1000;

ws.onclose = () => {
  setTimeout(() => {
    reconnect();
    reconnectDelay = Math.min(reconnectDelay * 2, 30000);
  }, reconnectDelay);
};

Store message history locally

Cache message history on the client side to reduce API calls and improve response times. Use the WebSocket events to keep the cache synchronized.

Implement typing indicators

Show typing indicators when receiving content-delta events to provide feedback to users during streaming responses.

Next Steps

Sessions API

Manage chat sessions within worktrees

Remote Access Guide

Learn more about Jean’s HTTP server and WebSocket API