# Sessions List chat sessions and retrieve messages from your AVCodex agent. --- Sessions represent individual chat conversations with your agent. Each session contains messages exchanged between a consumer (a tech, a programmer, an end-client) and your AI agent. ## List sessions ``` GET /api/v1/apps/{appId}/sessions ``` Returns a paginated list of chat sessions, newest first. ### Query parameters | Parameter | Type | Default | Description | |------------------|----------|---------|----------------------------------------------------------------------------| | `limit` | integer | 25 | Results per page (1-100). | | `cursor` | string | - | Pagination cursor from a previous response. | | `source` | string | - | Filter by channel. | | `consumer_id` | UUID | - | Filter by consumer. | | `started_after` | ISO 8601 | - | Sessions started after this date. | | `started_before` | ISO 8601 | - | Sessions started before this date. | | `search` | string | - | Case-insensitive substring search on session titles (max 200 chars). | **Source values:** `APP`, `API`, `WHATSAPP`, `SLACK`, `EMAIL`, `VOICE`, `WIDGET`, `ACP`. ### Example ```bash curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/sessions?limit=10&source=APP" \ -H "Authorization: Bearer avcodex_YOUR_API_KEY" ``` ### Response ```json { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "consumer_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "consumer": { "email": "jane@integrator.com", "name": "Jane Smith" }, "title": "Boardroom 4 commissioning Q&A", "source": "APP", "mode": "default", "is_bookmarked": false, "is_multiplayer": false, "message_count": 12, "started_at": "2025-06-15T14:30:00Z", "ended_at": "2025-06-15T14:45:00Z", "last_activity_at": "2025-06-15T14:45:00Z" } ], "pagination": { "has_more": true, "next_cursor": "eyJpZCI6IjU1MGU4NDAw...", "limit": 10 } } ``` ### Filtering by date range ```bash curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/sessions?started_after=2025-06-01T00:00:00Z&started_before=2025-06-30T23:59:59Z" \ -H "Authorization: Bearer avcodex_YOUR_API_KEY" ``` ### Filtering by consumer ```bash curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/sessions?consumer_id=7c9e6679-7425-40de-944b-e07fc1f90ae7" \ -H "Authorization: Bearer avcodex_YOUR_API_KEY" ``` --- ## Get session ``` GET /api/v1/apps/{appId}/sessions/{sessionId} ``` Returns a single session by ID. ### Example ```bash curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/sessions/550e8400-e29b-41d4-a716-446655440000" \ -H "Authorization: Bearer avcodex_YOUR_API_KEY" ``` ### Response ```json { "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "consumer_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "consumer": { "email": "jane@integrator.com", "name": "Jane Smith" }, "title": "Boardroom 4 commissioning Q&A", "source": "APP", "mode": "default", "is_bookmarked": false, "is_multiplayer": false, "message_count": 12, "started_at": "2025-06-15T14:30:00Z", "ended_at": "2025-06-15T14:45:00Z", "last_activity_at": "2025-06-15T14:45:00Z" } } ``` ### Error: session not found (404) ```json { "error": { "code": "not_found", "message": "Session not found" } } ``` --- ## List session messages ``` GET /api/v1/apps/{appId}/sessions/{sessionId}/messages ``` Returns the messages in a session, ordered chronologically. ### Query parameters | Parameter | Type | Default | Description | |------------------|----------|---------|--------------------------------------------------------------------------| | `limit` | integer | 25 | Results per page (1-100). | | `cursor` | string | - | Pagination cursor from a previous response. | | `role` | string | - | Filter by role: `user`, `assistant`, `system`, or `tool`. | | `created_after` | ISO 8601 | - | Messages created after this date. | | `created_before` | ISO 8601 | - | Messages created before this date. | | `include` | string | - | Comma-separated list of extra fields to include. | **Include values** - `tool_details` - adds `tool_calls` and `tool_results` fields to each message. Arrays when the message invoked tools, `null` when it did not. ### Example ```bash curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/sessions/550e8400-e29b-41d4-a716-446655440000/messages?limit=50" \ -H "Authorization: Bearer avcodex_YOUR_API_KEY" ``` ### Response ```json { "data": [ { "id": "msg-001", "session_id": "550e8400-e29b-41d4-a716-446655440000", "role": "user", "content": "How do I get the Q-SYS Core back online after a power loss?", "model": null, "token_count": 42, "latency_ms": null, "audio_url": null, "audio_duration_ms": null, "tags": [], "feedback": null, "created_at": "2025-06-15T14:30:00Z" }, { "id": "msg-002", "session_id": "550e8400-e29b-41d4-a716-446655440000", "role": "assistant", "content": "Here's the recovery procedure for the Q-SYS Core...", "model": "gpt-4.1", "token_count": 150, "latency_ms": 1200, "audio_url": null, "audio_duration_ms": null, "tags": [{ "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "qsys", "color": "#3b82f6" }], "feedback": null, "created_at": "2025-06-15T14:30:05Z" } ], "pagination": { "has_more": false, "next_cursor": null, "limit": 50 } } ``` ### Response fields | Field | Type | Description | |--------------------|------------------|------------------------------------------------------------------------------------------------------| | `id` | string | Unique message identifier. | | `session_id` | UUID | The session this message belongs to. | | `role` | string | `user`, `assistant`, `system`, or `tool`. | | `content` | string | Message text content. | | `model` | string or null | LLM model used (null for user messages). | | `token_count` | integer or null | Token count for this message. | | `latency_ms` | integer or null | Response latency in milliseconds. | | `audio_url` | string or null | URL to audio recording, if applicable. | | `audio_duration_ms`| integer or null | Audio duration in milliseconds. | | `tags` | array of objects | Tags applied to this message. Each object has `id` (UUID), `name` (string), and `color` (hex string). | | `feedback` | object or null | Feedback on this message, if any. | | `created_at` | ISO 8601 | When the message was created. | ### With tool details ```bash curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/sessions/SESSION_ID/messages?include=tool_details" \ -H "Authorization: Bearer avcodex_YOUR_API_KEY" ``` ```json { "data": [ { "id": "msg-003", "session_id": "550e8400-e29b-41d4-a716-446655440000", "role": "assistant", "content": "Let me look that up for you.", "model": "gpt-4.1", "token_count": 180, "latency_ms": 2400, "audio_url": null, "audio_duration_ms": null, "tags": [], "feedback": null, "created_at": "2025-06-15T14:31:00Z", "tool_calls": [ { "tool_name": "search_knowledge", "status": "completed" } ], "tool_results": [ { "tool_name": "search_knowledge", "result": "..." } ] } ], "pagination": { "has_more": false, "next_cursor": null, "limit": 25 } } ``` ### Filtering by role To retrieve only user messages (useful for extracting tech questions): ```bash curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/sessions/SESSION_ID/messages?role=user" \ -H "Authorization: Bearer avcodex_YOUR_API_KEY" ``` *AVCodex ยท Your AV expertise. Amplified by AI.*