Sessions enable stateful, multi-turn conversations with agents. Each session maintains conversation history and can be resumed or ended explicitly.
Base URL
All session endpoints are under:
https://api.superserve.ai/v1/sessions
Create Session
Create a new conversation session with an agent.
POST /v1/sessions
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
Agent ID (e.g., agt_abc123)
Optional session title for identification
Number of seconds of inactivity before the session automatically ends (default: 29 minutes)
Session ID (prefixed with ses_)
Agent ID this session is connected to
Session status: active, idle, or ended
Session title if provided
Number of messages exchanged in this session
ISO 8601 timestamp when the session was created
ISO 8601 timestamp of the last activity
{
"agent_id": "agt_abc123",
"title": "Customer support chat",
"idle_timeout_seconds": 1740
}
{
"id": "ses_xyz789",
"agent_id": "agt_abc123",
"agent_name": "my-agent",
"status": "active",
"title": "Customer support chat",
"message_count": 0,
"created_at": "2026-03-09T10:00:00Z",
"last_activity_at": "2026-03-09T10:00:00Z"
}
List Sessions
Retrieve sessions with optional filters.
GET /v1/sessions?limit=20&agent_id=agt_abc123&status=active
Authorization: Bearer YOUR_API_TOKEN
Maximum number of sessions to return
Filter by status: active, idle, or ended
Array of session objects (same schema as create session response)
{
"sessions": [
{
"id": "ses_xyz789",
"agent_id": "agt_abc123",
"agent_name": "my-agent",
"status": "active",
"title": "Customer support chat",
"message_count": 5,
"created_at": "2026-03-09T10:00:00Z",
"last_activity_at": "2026-03-09T10:15:00Z"
}
]
}
Get Session
Retrieve details for a specific session.
GET /v1/sessions/{session_id}
Authorization: Bearer YOUR_API_TOKEN
Session ID (e.g., ses_xyz789). Can be a short prefix for convenience.
{
"id": "ses_xyz789",
"agent_id": "agt_abc123",
"agent_name": "my-agent",
"status": "active",
"title": "Customer support chat",
"message_count": 5,
"created_at": "2026-03-09T10:00:00Z",
"last_activity_at": "2026-03-09T10:15:00Z"
}
End Session
Explicitly end a session and release resources.
POST /v1/sessions/{session_id}/end
Authorization: Bearer YOUR_API_TOKEN
Session ID (e.g., ses_xyz789)
status: "ended".
Example:
{
"id": "ses_xyz789",
"agent_id": "agt_abc123",
"agent_name": "my-agent",
"status": "ended",
"title": "Customer support chat",
"message_count": 10,
"created_at": "2026-03-09T10:00:00Z",
"last_activity_at": "2026-03-09T10:30:00Z"
}
Resume Session
Resume an idle session.
POST /v1/sessions/{session_id}/resume
Authorization: Bearer YOUR_API_TOKEN
Session ID (e.g., ses_xyz789)
status: "active".
Resolve Session ID
Resolve a short session ID prefix to the full ID.
GET /v1/sessions/resolve?id_prefix=xyz
Authorization: Bearer YOUR_API_TOKEN
Session ID prefix (e.g., xyz for ses_xyz789)
Array of matching session IDs
{
"ids": ["ses_xyz789abc123"]
}
If multiple sessions match the prefix, the API returns a 409 Conflict error. Provide a longer prefix to disambiguate.
Session Status
| Status | Description |
|---|
active | Session is ready to receive messages |
idle | Session timed out due to inactivity (can be resumed) |
ended | Session was explicitly ended (cannot be resumed) |
Error Responses
Common Errors:
| Status | Message |
|---|
| 401 | Not authenticated |
| 404 | Session not found |
| 409 | Ambiguous session ID prefix |
| 422 | Invalid session parameters |
