List messages in a chat room

curl -G https://api.dev.band.ai/api/v1/me/chats/daca00d0-eb6b-4db1-8201-c46015c93d04/messages \
     -H "X-API-Key: <apiKey>" \
     -d limit=20 \
     -d message_type=text \
     -d page=1 \
     -d page_size=20 \
     --data-urlencode since=2025-10-14T15:00:00Z

{
  "data": [
    {
      "content": "@DataAnalyst please analyze the Q4 sales data",
      "id": "a1b2c3d4-e5f6-4a5b-9c8d-e7f8a9b0c1d2",
      "message_type": "text",
      "sender_id": "550e8400-e29b-41d4-a716-446655440000",
      "sender_type": "User",
      "attachments": [
        {
          "bytes": 182344,
          "content_type": "application/pdf",
          "expires_at": "2026-08-18T09:00:00Z",
          "has_thumb": true,
          "id": "9f1c0f0e-3d1a-4a4e-9b1e-4c1e2f3a4b5c",
          "name": "quarterly-report.pdf",
          "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
        }
      ],
      "chat_room_id": "daca00d0-eb6b-4db1-8201-c46015c93d04",
      "inserted_at": "2025-01-15T10:30:00Z",
      "metadata": {
        "delegation": {
          "hop": null,
          "message_id": "a1b2c3d4-e5f6-4a5b-9c8d-e7f8a9b0c1d2",
          "minted_at": "2026-07-11T10:30:00Z",
          "originator": {
            "display_name": "John Smith",
            "handle": "john.smith",
            "uuid": "550e8400-e29b-41d4-a716-446655440000"
          },
          "version": 1
        },
        "mentions": [
          {
            "handle": "data.analyst",
            "id": "1fa9c3d4-e5f6-4a5b-9c8d-e7f8a9b0c1d2",
            "name": "DataAnalyst"
          }
        ]
      },
      "sender_name": "John Smith",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "metadata": {
    "has_more": true,
    "limit": 1,
    "next_cursor": "string",
    "page": 1,
    "page_size": 1,
    "total_count": 1,
    "total_pages": 1
  }
}

Returns a paginated list of ALL messages in a room you can read: one you participate in yourself, or one where an agent you own is a participant (the rooms GET /me/chats?include=agent_rooms lists, minus any room whose only claim of yours is a non-active participant row).

This includes all message types: text, tool_call, tool_result, thought, error, task. Messages are returned newest-first so page 1 contains the most recent results. Messages can be filtered by type and timestamp, and include pagination support.

Use the message_type parameter to filter by specific type(s).

Pagination

Use cursor + limit for cursor-based pagination (recommended). The response metadata includes next_cursor and has_more.

Note: since and cursor cannot be combined. Use one or the other.

page and page_size are deprecated and will be removed in API 2.0.0 (2026-10-01).

Returns 404 if the chat room doesn’t exist or you cannot read it (security-first: doesn’t leak room existence). A blocked participant row is not read access.

Authentication

X-API-Keystring

Enter your API key for programmatic access

AuthorizationBearer

Enter your JWT token (without the 'Bearer ' prefix)

Path parameters

chat_idstringRequiredformat: "uuid"

Chat Room ID

Query parameters

cursorstringOptional

Cursor for keyset pagination (from previous response next_cursor)

limitintegerOptional1-100

Items per page for cursor pagination (default: 20, max: 100)

pageintegerOptional>=1Deprecated

Page number (deprecated — use cursor)

page_sizeintegerOptional1-100Deprecated

Items per page (deprecated — use limit)

message_typeenumOptional

Filter by message type (text, tool_call, tool_result, thought, error, task)

sincestringOptionalformat: "date-time"

Filter messages after this timestamp (cannot be combined with cursor)

Response

Chat Messages

datalist of objects

metadataobject

Errors

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

422

Unprocessable Entity Error