Docs/Builder API/Builder API

    Sessions

    Last updated · MAR 2026·Read as Markdown

    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.

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

    Was this helpful?
    Edit this page →