Sessions — AVCodex Docs

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#

code

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#

code

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#

code

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.*