> ## Documentation Index
> Fetch the complete documentation index at: https://elizalabs-force-cache-clear.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Sessions API Reference
> Complete API reference for the Sessions messaging system
The Sessions API provides a comprehensive set of endpoints for managing stateful conversations with ElizaOS agents. This reference covers all available endpoints, request/response schemas, and error handling.
## Base URL
```
http://localhost:3000/api/messaging/sessions
```
## Authentication
Currently, the Sessions API does not require authentication. In production environments, you should implement appropriate authentication mechanisms.
## Endpoints
### Create Session
Creates a new conversation session with an agent.
Create a new session with configurable timeout policies
**Request Body:**
```typescript
interface CreateSessionRequest {
agentId: string; // UUID of the agent
userId: string; // UUID of the user
metadata?: { // Optional session metadata
[key: string]: any;
};
timeoutConfig?: { // Optional timeout configuration
timeoutMinutes?: number; // 5-1440 minutes
autoRenew?: boolean; // Default: true
maxDurationMinutes?: number; // Maximum session duration
warningThresholdMinutes?: number; // When to warn about expiration
};
}
```
**Response (201 Created):**
```typescript
interface CreateSessionResponse {
sessionId: string;
agentId: string;
userId: string;
createdAt: Date;
metadata: object;
expiresAt: Date;
timeoutConfig: SessionTimeoutConfig;
}
```
**Example:**
```bash
curl -X POST http://localhost:3000/api/messaging/sessions \
-H "Content-Type: application/json" \
-d '{
"agentId": "123e4567-e89b-12d3-a456-426614174000",
"userId": "987f6543-e21b-12d3-a456-426614174000",
"timeoutConfig": {
"timeoutMinutes": 30,
"autoRenew": true
}
}'
```
***
### Get Session Information
Retrieves detailed information about a session including its current status.
Get session details and current status
**Response (200 OK):**
```typescript
interface SessionInfoResponse {
sessionId: string;
agentId: string;
userId: string;
createdAt: Date;
lastActivity: Date;
metadata: object;
expiresAt: Date;
timeoutConfig: SessionTimeoutConfig;
renewalCount: number;
timeRemaining: number; // Milliseconds until expiration
isNearExpiration: boolean; // True if within warning threshold
}
```
**Errors:**
* `404 Not Found` - Session does not exist
* `410 Gone` - Session has expired
***
### Send Message
Sends a message within a session. Automatically renews the session if auto-renewal is enabled.
Send a message in the conversation
**Request Body:**
```typescript
interface SendMessageRequest {
content: string; // Message content (max 4000 chars)
metadata?: { // Optional message metadata
[key: string]: any;
};
attachments?: any[]; // Optional attachments
}
```
**Response (201 Created):**
```typescript
interface MessageResponse {
id: string;
content: string;
authorId: string;
createdAt: Date;
metadata: object;
sessionStatus?: { // Session renewal information
expiresAt: Date;
renewalCount: number;
wasRenewed: boolean;
isNearExpiration: boolean;
};
}
```
**Errors:**
* `400 Bad Request` - Invalid content or metadata
* `404 Not Found` - Session not found
* `410 Gone` - Session expired
***
### Get Messages
Retrieves messages from a session with pagination support.
Retrieve conversation history
**Query Parameters:**
```typescript
interface GetMessagesQuery {
limit?: string; // Number of messages (1-100, default: 50)
before?: string; // Timestamp for pagination (older messages)
after?: string; // Timestamp for pagination (newer messages)
}
```
**Response (200 OK):**
```typescript
interface GetMessagesResponse {
messages: SimplifiedMessage[];
hasMore: boolean;
cursors?: {
before?: number; // Use for getting older messages
after?: number; // Use for getting newer messages
};
}
interface SimplifiedMessage {
id: string;
content: string;
authorId: string;
isAgent: boolean;
createdAt: Date;
metadata: {
thought?: string; // Agent's internal reasoning
actions?: string[]; // Actions taken by agent
[key: string]: any;
};
}
```
***
### Renew Session
Manually renews a session to extend its expiration time.
Manually extend session lifetime
**Response (200 OK):**
```typescript
interface SessionInfoResponse {
sessionId: string;
agentId: string;
userId: string;
createdAt: Date;
lastActivity: Date;
expiresAt: Date;
timeoutConfig: SessionTimeoutConfig;
renewalCount: number;
timeRemaining: number;
isNearExpiration: boolean;
}
```
**Errors:**
* `404 Not Found` - Session not found
* `410 Gone` - Session expired
* `422 Unprocessable Entity` - Cannot renew (max duration reached)
***
### Update Timeout Configuration
Updates the timeout configuration for an active session.
Modify session timeout settings
**Request Body:**
```typescript
interface SessionTimeoutConfig {
timeoutMinutes?: number; // 5-1440 minutes
autoRenew?: boolean;
maxDurationMinutes?: number;
warningThresholdMinutes?: number;
}
```
**Response (200 OK):**
Returns updated `SessionInfoResponse`
**Errors:**
* `400 Bad Request` - Invalid timeout configuration
* `404 Not Found` - Session not found
* `410 Gone` - Session expired
***
### Send Heartbeat
Keeps a session alive and optionally renews it if auto-renewal is enabled.
Keep session alive with periodic heartbeat
**Response (200 OK):**
Returns `SessionInfoResponse` with updated expiration information.
**Errors:**
* `404 Not Found` - Session not found
* `410 Gone` - Session expired
***
### Delete Session
Explicitly ends and removes a session.
End and delete a session
**Response (200 OK):**
```typescript
{
success: true,
message: "Session {sessionId} deleted successfully"
}
```
**Errors:**
* `404 Not Found` - Session not found
***
### List Sessions (Admin)
Lists all active sessions in the system. This is an administrative endpoint.
List all active sessions
**Response (200 OK):**
```typescript
interface ListSessionsResponse {
sessions: SessionInfoResponse[];
total: number;
stats: {
totalSessions: number;
activeSessions: number;
expiredSessions: number;
};
}
```
***
### Health Check
Checks the health status of the Sessions API service.
Check service health
**Response (200 OK):**
```typescript
interface HealthCheckResponse {
status: 'healthy' | 'degraded' | 'unhealthy';
activeSessions: number;
timestamp: string;
expiringSoon?: number; // Sessions near expiration
invalidSessions?: number; // Corrupted sessions detected
uptime?: number; // Service uptime in seconds
}
```
## Error Responses
All error responses follow a consistent format:
```typescript
interface ErrorResponse {
error: string; // Error message
details?: { // Additional context
[key: string]: any;
};
}
```
### Common Error Codes
| Status Code | Error Type | Description |
| ----------- | --------------------- | ---------------------------------------------------------- |
| `400` | Bad Request | Invalid input parameters or request body |
| `404` | Not Found | Session or resource not found |
| `410` | Gone | Session has expired |
| `422` | Unprocessable Entity | Operation cannot be completed (e.g., max duration reached) |
| `500` | Internal Server Error | Unexpected server error |
### Error Classes
The API uses specific error classes for different scenarios:
* `SessionNotFoundError` - Session does not exist
* `SessionExpiredError` - Session has exceeded its timeout
* `SessionCreationError` - Failed to create session
* `AgentNotFoundError` - Specified agent not found
* `InvalidUuidError` - Invalid UUID format
* `MissingFieldsError` - Required fields missing
* `InvalidContentError` - Message content validation failed
* `InvalidMetadataError` - Metadata exceeds size limit
* `InvalidPaginationError` - Invalid pagination parameters
* `InvalidTimeoutConfigError` - Invalid timeout configuration
* `SessionRenewalError` - Cannot renew session
* `MessageSendError` - Failed to send message
## Rate Limiting
Currently, the Sessions API does not implement rate limiting. In production, you should implement appropriate rate limiting based on your requirements.
## WebSocket Events
When using WebSocket connections alongside the Sessions API, the following events are available:
```typescript
// Join a session for real-time updates
socket.emit('join', { roomId: sessionId });
// Listen for new messages
socket.on('messageBroadcast', (message) => {
// Handle new message
});
// Session expiration warning
socket.on('sessionExpirationWarning', (data) => {
// data.sessionId, data.minutesRemaining
});
// Session expired
socket.on('sessionExpired', (data) => {
// data.sessionId, data.expiredAt
});
// Session renewed
socket.on('sessionRenewed', (data) => {
// data.sessionId, data.expiresAt, data.renewalCount
});
```
## Environment Variables
Configure the Sessions API behavior using these environment variables:
| Variable | Default | Description |
| ----------------------------------- | ------- | ----------------------------------------- |
| `SESSION_DEFAULT_TIMEOUT_MINUTES` | 30 | Default session timeout |
| `SESSION_MIN_TIMEOUT_MINUTES` | 5 | Minimum allowed timeout |
| `SESSION_MAX_TIMEOUT_MINUTES` | 1440 | Maximum allowed timeout (24 hours) |
| `SESSION_MAX_DURATION_MINUTES` | 720 | Maximum total session duration (12 hours) |
| `SESSION_WARNING_THRESHOLD_MINUTES` | 5 | When to trigger expiration warning |
| `SESSION_CLEANUP_INTERVAL_MINUTES` | 5 | How often to clean expired sessions |
| `CLEAR_SESSIONS_ON_SHUTDOWN` | false | Clear all sessions on server shutdown |
## SDK Examples
### JavaScript/TypeScript Client
```typescript
class SessionsAPIClient {
constructor(private baseUrl: string = 'http://localhost:3000') {}
async createSession(agentId: string, userId: string, config?: SessionTimeoutConfig) {
const response = await fetch(`${this.baseUrl}/api/messaging/sessions`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ agentId, userId, timeoutConfig: config })
});
if (!response.ok) throw new Error(`Failed to create session: ${response.status}`);
return response.json();
}
async sendMessage(sessionId: string, content: string, metadata?: object) {
const response = await fetch(
`${this.baseUrl}/api/messaging/sessions/${sessionId}/messages`,
{
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ content, metadata })
}
);
if (!response.ok) throw new Error(`Failed to send message: ${response.status}`);
return response.json();
}
async getMessages(sessionId: string, limit = 50, before?: number) {
const params = new URLSearchParams({ limit: limit.toString() });
if (before) params.append('before', before.toString());
const response = await fetch(
`${this.baseUrl}/api/messaging/sessions/${sessionId}/messages?${params}`
);
if (!response.ok) throw new Error(`Failed to get messages: ${response.status}`);
return response.json();
}
async renewSession(sessionId: string) {
const response = await fetch(
`${this.baseUrl}/api/messaging/sessions/${sessionId}/renew`,
{ method: 'POST' }
);
if (!response.ok) throw new Error(`Failed to renew session: ${response.status}`);
return response.json();
}
async sendHeartbeat(sessionId: string) {
const response = await fetch(
`${this.baseUrl}/api/messaging/sessions/${sessionId}/heartbeat`,
{ method: 'POST' }
);
if (!response.ok) throw new Error(`Heartbeat failed: ${response.status}`);
return response.json();
}
}
```
### Python Client
```python
import requests
from typing import Optional, Dict, Any
class SessionsAPIClient:
def __init__(self, base_url: str = "http://localhost:3000"):
self.base_url = base_url
self.session = requests.Session()
def create_session(
self,
agent_id: str,
user_id: str,
timeout_config: Optional[Dict[str, Any]] = None
) -> Dict[str, Any]:
"""Create a new session with an agent."""
payload = {
"agentId": agent_id,
"userId": user_id
}
if timeout_config:
payload["timeoutConfig"] = timeout_config
response = self.session.post(
f"{self.base_url}/api/messaging/sessions",
json=payload
)
response.raise_for_status()
return response.json()
def send_message(
self,
session_id: str,
content: str,
metadata: Optional[Dict[str, Any]] = None
) -> Dict[str, Any]:
"""Send a message in a session."""
payload = {"content": content}
if metadata:
payload["metadata"] = metadata
response = self.session.post(
f"{self.base_url}/api/messaging/sessions/{session_id}/messages",
json=payload
)
response.raise_for_status()
return response.json()
def get_messages(
self,
session_id: str,
limit: int = 50,
before: Optional[int] = None,
after: Optional[int] = None
) -> Dict[str, Any]:
"""Retrieve messages from a session."""
params = {"limit": str(limit)}
if before:
params["before"] = str(before)
if after:
params["after"] = str(after)
response = self.session.get(
f"{self.base_url}/api/messaging/sessions/{session_id}/messages",
params=params
)
response.raise_for_status()
return response.json()
def renew_session(self, session_id: str) -> Dict[str, Any]:
"""Manually renew a session."""
response = self.session.post(
f"{self.base_url}/api/messaging/sessions/{session_id}/renew"
)
response.raise_for_status()
return response.json()
def send_heartbeat(self, session_id: str) -> Dict[str, Any]:
"""Send a heartbeat to keep session alive."""
response = self.session.post(
f"{self.base_url}/api/messaging/sessions/{session_id}/heartbeat"
)
response.raise_for_status()
return response.json()
```
## Next Steps
Learn best practices and advanced patterns
Add real-time capabilities to your sessions
Understand ElizaOS architecture
Build custom plugins for your agents