Sessions

Overview

Sessions represent active conversation contexts between users and agents. They track conversation state, user context, and interaction history across multiple messages.

List Sessions

Endpoint

GET /agents/{agentId}/sessions

Retrieves all active and recent sessions for an agent.

Request

Path Parameters

agentId

string

required

Unique identifier (UUID) of the agent

Query Parameters

status

string

Filter by session status: active, idle, closed

userId

string

Filter by user ID

limit

number

default:"50"

Maximum number of sessions to return

offset

number

default:"0"

Number of sessions to skip

Response

success

boolean

required

Indicates if the request was successful

data

array

required

Array of session objects

data[].sessionId

string

required

Unique session identifier (UUID)

data[].agentId

string

required

Agent ID

data[].userId

string

required

User ID

data[].roomId

string

required

Associated room ID

data[].status

string

required

Session status: active, idle, or closed

data[].messageCount

number

Number of messages in the session

data[].createdAt

number

Unix timestamp when session was created

data[].lastActivityAt

number

Unix timestamp of last activity

data[].metadata

object

Session metadata and context

Example

curl -X GET "http://localhost:3000/agents/550e8400-e29b-41d4-a716-446655440000/sessions?status=active" \
  -H "Content-Type: application/json"

Response Example

{
  "success": true,
  "data": [
    {
      "sessionId": "session-880e8400-e29b-41d4-a716-446655440030",
      "agentId": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "user-123",
      "roomId": "room-660e8400-e29b-41d4-a716-446655440004",
      "status": "active",
      "messageCount": 8,
      "createdAt": 1709683200000,
      "lastActivityAt": 1709683800000,
      "metadata": {
        "channel": "web",
        "topic": "customer-support"
      }
    }
  ]
}

Get Session Details

Endpoint

GET /agents/{agentId}/sessions/{sessionId}

Retrieves detailed information about a specific session.

Request

Path Parameters

agentId

string

required

Unique identifier (UUID) of the agent

sessionId

string

required

Unique identifier (UUID) of the session

Response

success

boolean

required

Indicates if the request was successful

data

object

required

Session details including full context and conversation state

Example

curl -X GET http://localhost:3000/agents/550e8400-e29b-41d4-a716-446655440000/sessions/session-880e8400-e29b-41d4-a716-446655440030 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Session

Endpoint

POST /agents/{agentId}/sessions

Creates a new conversation session.

Request

Body Parameters

userId

string

required

User ID for the session

userName

string

User display name

metadata

object

Session metadata and context

Example

curl -X POST http://localhost:3000/agents/550e8400-e29b-41d4-a716-446655440000/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-123",
    "userName": "Alice Smith",
    "metadata": {
      "channel": "web",
      "source": "landing-page"
    }
  }'

Update Session

Endpoint

PUT /agents/{agentId}/sessions/{sessionId}

Updates session status or metadata.

Request

Body Parameters

status

string

New status: active, idle, or closed

metadata

object

Updated metadata

Example

curl -X PUT http://localhost:3000/agents/550e8400-e29b-41d4-a716-446655440000/sessions/session-880e8400-e29b-41d4-a716-446655440030 \
  -H "Content-Type: application/json" \
  -d '{
    "status": "closed"
  }'

Code Examples

JavaScript/Node.js

const agentId = "550e8400-e29b-41d4-a716-446655440000";

// List active sessions
const listSessions = async () => {
  const response = await fetch(
    `http://localhost:3000/agents/${agentId}/sessions?status=active`,
    {
      headers: { 'Content-Type': 'application/json' }
    }
  );
  
  const { success, data } = await response.json();
  
  if (success) {
    console.log(`Found ${data.length} active sessions`);
    return data;
  }
};

// Create a new session
const createSession = async (userId, userName) => {
  const response = await fetch(
    `http://localhost:3000/agents/${agentId}/sessions`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        userId,
        userName,
        metadata: {
          channel: 'web',
          timestamp: Date.now()
        }
      })
    }
  );
  
  const { success, data } = await response.json();
  
  if (success) {
    console.log(`Session created: ${data.sessionId}`);
    return data;
  }
};

// Close a session
const closeSession = async (sessionId) => {
  await fetch(
    `http://localhost:3000/agents/${agentId}/sessions/${sessionId}`,
    {
      method: 'PUT',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ status: 'closed' })
    }
  );
};

// Usage
const sessions = await listSessions();
const newSession = await createSession('user-123', 'Alice');
await closeSession(newSession.sessionId);

Python

import requests

agent_id = "550e8400-e29b-41d4-a716-446655440000"

def list_sessions(status: str = "active"):
    response = requests.get(
        f'http://localhost:3000/agents/{agent_id}/sessions',
        params={'status': status}
    )
    
    data = response.json()
    
    if data['success']:
        print(f"Found {len(data['data'])} sessions")
        return data['data']

def create_session(user_id: str, user_name: str):
    response = requests.post(
        f'http://localhost:3000/agents/{agent_id}/sessions',
        json={
            'userId': user_id,
            'userName': user_name,
            'metadata': {
                'channel': 'web'
            }
        }
    )
    
    data = response.json()
    
    if data['success']:
        print(f"Session created: {data['data']['sessionId']}")
        return data['data']

def close_session(session_id: str):
    requests.put(
        f'http://localhost:3000/agents/{agent_id}/sessions/{session_id}',
        json={'status': 'closed'}
    )

# Usage
sessions = list_sessions('active')
new_session = create_session('user-123', 'Alice')
close_session(new_session['sessionId'])

TypeScript

interface Session {
  sessionId: string;
  agentId: string;
  userId: string;
  roomId: string;
  status: 'active' | 'idle' | 'closed';
  messageCount?: number;
  createdAt?: number;
  lastActivityAt?: number;
  metadata?: Record<string, any>;
}

class SessionManager {
  constructor(private agentId: string, private baseUrl: string) {}
  
  async listSessions(status?: string): Promise<Session[]> {
    const params = status ? `?status=${status}` : '';
    const response = await fetch(
      `${this.baseUrl}/agents/${this.agentId}/sessions${params}`
    );
    
    const { success, data } = await response.json();
    return success ? data : [];
  }
  
  async createSession(userId: string, userName: string): Promise<Session> {
    const response = await fetch(
      `${this.baseUrl}/agents/${this.agentId}/sessions`,
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ userId, userName })
      }
    );
    
    const { success, data } = await response.json();
    return data;
  }
  
  async closeSession(sessionId: string): Promise<void> {
    await fetch(
      `${this.baseUrl}/agents/${this.agentId}/sessions/${sessionId}`,
      {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ status: 'closed' })
      }
    );
  }
}

// Usage
const manager = new SessionManager(
  "550e8400-e29b-41d4-a716-446655440000",
  "http://localhost:3000"
);

const sessions = await manager.listSessions('active');
const newSession = await manager.createSession('user-123', 'Alice');
await manager.closeSession(newSession.sessionId);

Session Lifecycle

Created - New session initialized
Active - User is actively messaging
Idle - No recent activity (configurable timeout)
Closed - Session explicitly closed or expired

Auto-Cleanup

Sessions automatically transition to idle after inactivity and can be configured to close after a timeout period.

Next Steps

Send Message

Send messages within a session

Get Messages

Retrieve session message history

Create Channel

Set up communication channels

Overview

Agents

Messaging

Overview

List Sessions

Endpoint

Request

Path Parameters

Query Parameters

Response

Example

Response Example

Get Session Details

Endpoint

Request

Path Parameters

Response

Example

Create Session

Endpoint

Request

Body Parameters

Example

Update Session

Endpoint

Request

Body Parameters

Example

Code Examples

JavaScript/Node.js

Python

TypeScript

Session Lifecycle

Auto-Cleanup

Next Steps

Send Message

Get Messages

Create Channel

Build docs developers (and LLMs) love

Overview

Agents

Messaging

​Overview

​List Sessions

​Endpoint

​Request

​Path Parameters

​Query Parameters

​Response

​Example

​Response Example

​Get Session Details

​Endpoint

​Request

​Path Parameters

​Response

​Example

​Create Session

​Endpoint

​Request

​Body Parameters

​Example

​Update Session

​Endpoint

​Request

​Body Parameters

​Example

​Code Examples

​JavaScript/Node.js

​Python

​TypeScript

​Session Lifecycle

​Auto-Cleanup

​Next Steps

Send Message

Get Messages

Create Channel

Build docs developers (and LLMs) love

Overview

List Sessions

Endpoint

Request

Path Parameters

Query Parameters

Response

Example

Response Example

Get Session Details

Endpoint

Request

Path Parameters

Response

Example

Create Session

Endpoint

Request

Body Parameters

Example

Update Session

Endpoint

Request

Body Parameters

Example

Code Examples

JavaScript/Node.js

Python

TypeScript

Session Lifecycle

Auto-Cleanup

Next Steps