Sessions

A session represents a single conversation thread between a user and an AI agent. Sessions preserve conversation history so the AI can provide contextual responses.

Create a Session

Creates a new chat session for the specified agent.

Request

POST /agents/{agentId}/sessions

Path Parameters

Parameter	Type	Required	Description
`agentId`	string (UUID)	Yes	The agent ID

Request Body

Field	Type	Required	Description
`name`	string	No	Session name. Defaults to a timestamp.
`externalUserId`	string (UUID)	No	Your user's ID for tracking. Auto-generated if omitted.

Example Body

{
  "name": "Support Chat - March 2026",
  "externalUserId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Response

201 Created

{
  "success": true,
  "session": {
    "id": "session-uuid",
    "name": "Support Chat - March 2026",
    "userSessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "createdAt": "2026-03-19T10:00:00.000Z"
  }
}

Code Examples

cURL

curl -X POST \
  -H "X-API-Key: api_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support Chat", "externalUserId": "user-123"}' \
  http://localhost:3002/agents/{agentId}/sessions

Node.js

const res = await fetch(
  `http://localhost:3002/agents/${agentId}/sessions`,
  {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.API_KEY!,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Support Chat',
      externalUserId: 'user-123'
    })
  }
);
const { session } = await res.json();

List Sessions

Returns all chat sessions for the specified agent.

Request

GET /agents/{agentId}/sessions

Query Parameters

Parameter	Type	Description
`externalUserId`	string (UUID)	Filter sessions by external user ID

Response

200 OK

{
  "success": true,
  "sessions": [
    {
      "id": "session-uuid",
      "name": "Support Chat",
      "userSessionId": "user-uuid",
      "totalMessages": 6,
      "lastMessageAt": "2026-03-19T10:05:00.000Z",
      "timeAgo": "5 minutes ago",
      "createdAt": "2026-03-19T10:00:00.000Z"
    }
  ]
}

Code Examples

cURL — All sessions

curl -H "X-API-Key: api_your_key" \
  http://localhost:3002/agents/{agentId}/sessions

cURL — Filtered by user

curl -H "X-API-Key: api_your_key" \
  "http://localhost:3002/agents/{agentId}/sessions?externalUserId=user-123"

Get Session Details

Returns session metadata and the full message history.

Request

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

Path Parameters

Parameter	Type	Required	Description
`agentId`	string (UUID)	Yes	The agent ID
`sessionId`	string (UUID)	Yes	The session ID

Response

200 OK

{
  "success": true,
  "session": {
    "id": "session-uuid",
    "name": "Support Chat",
    "createdAt": "2026-03-19T10:00:00.000Z"
  },
  "messages": [
    {
      "id": "msg-1",
      "role": "USER",
      "content": "Hello!",
      "createdAt": "2026-03-19T10:00:00.000Z"
    },
    {
      "id": "msg-2",
      "role": "AI",
      "content": "Hi! How can I help you today?",
      "createdAt": "2026-03-19T10:00:01.000Z"
    }
  ]
}

Update Session

Update session details such as the session name.

Request

PATCH /agents/{agentId}/sessions/{sessionId}

Request Body

Field	Type	Required	Description
`name`	string	Yes	New session name

Example Body

{
  "name": "Renamed Session"
}

Response

200 OK

{
  "success": true,
  "session": {
    "id": "session-uuid",
    "name": "Renamed Session",
    "updatedAt": "2026-03-19T10:10:00.000Z"
  }
}

Delete Session

Permanently deletes a chat session and all its messages.

Request

DELETE /agents/{agentId}/sessions/{sessionId}

This action is irreversible. All messages in the session will be permanently deleted.

Response

200 OK

{
  "success": true,
  "message": "Session deleted successfully"
}

Code Examples

cURL

curl -X DELETE \
  -H "X-API-Key: api_your_key" \
  http://localhost:3002/agents/{agentId}/sessions/{sessionId}

On this page