Chats – ProteusAI Reference

You interact with agents by exchanging messages in a chat. A chat is a conversation between an initiator and one or more participants. The initiator is the entity that created the chat; participants are the entities in it (including the initiator). A chat holds messages, attachments, and system messages.

See Chat.

Create Chat

POST /api/chats

Provide the participants you want in the chat (e.g. the agent you want to talk to). The authenticated entity is added automatically.

curl -L -X POST \
-H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f..." \
https://messaging-api.useproteus.ai/api/chats \
-d '{
      "participants": [
        { "id": "6819a0e484df0fc342cea506", "type": "AGENT" }
      ]
    }'

{
  "ok": true,
  "data": {
    "id": "682f4b313981b5f54e96ea4b",
    "key": null,
    "orgId": null,
    "state": null,
    "title": null,
    "systemMessages": [],
    "createdAt": "2025-05-22T16:05:05.453Z",
    "updatedAt": "2025-05-22T16:05:05.453Z"
  }
}

You can also pass a key to create or reuse a stable, logical chat (see chatKey on messages), a title, and an initial state object.

Get Messages

GET /api/chats/:chatId/messages

Retrieves the messages in a chat. Supports index-based and cursor-based pagination.

Index-based pagination

Query Parameter	Description	Default	Max
`@page`	Page number	`1`	—
`@limit`	Items per page	`20`	`100`

curl -L \
-H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f..." \
"https://messaging-api.useproteus.ai/api/chats/682f4b313981b5f54e96ea4b/messages?@page=2&@limit=10"

Cursor-based pagination

Query Parameter	Description	Default	Max
`@cursor`	Message ID to start from	—	—
`@limit`	Items per page	`20`	`100`

curl -L \
-H "Authorization: Bearer user-3a4d80a9c3cca7ffd1bc341f..." \
"https://messaging-api.useproteus.ai/api/chats/682f4b313981b5f54e96ea4b/messages?@cursor=6832df10b749a23a30105dba&@limit=20"

When @cursor is provided, the index-based parameter (@page) is ignored.

Joining a chat's realtime room

To receive messages and streamed responses for a chat in real time, join the chat over the realtime connection. With the SDK:

await proteus.chats.join(chat.id);
// ...later
await proteus.chats.leave(chat.id);

See Realtime for the underlying socket events.

Agents Messages