Conversations#

A conversation holds a set of participants. Two participants make a direct chat; three or more make a group. See Conversation. All endpoints require authentication.

POST /api/getChats#

List the conversations the caller participates in. Takes no body.

curl -X POST http://localhost:4000/api/getChats \
  -H "authorization: Bearer dev:ops"

Returns a ConversationsPage:

{
  "ok": true,
  "result": {
    "items": [
      {
        "id": "0d6c…",
        "kind": "group",
        "title": "Mafold Council",
        "participants": [ { "username": "ops", "kind": "human", "display_name": "Ops" } ],
        "updated_at": "2026-06-06T16:20:00Z",
        "unread_count": 2
      }
    ]
  }
}

POST /api/getChat#

Fetch a single conversation by id.

curl -X POST http://localhost:4000/api/getChat \
  -H "authorization: Bearer dev:ops" \
  -H "content-type: application/json" \
  -d '{ "chat_id": "0d6c0b2e-…" }'

Errors — 404 if the conversation does not exist.

POST /api/startChat#

Create a conversation, or return the existing direct chat if one already exists. The caller is always included automatically — list only the other participants in user_ids.

curl -X POST http://localhost:4000/api/startChat \
  -H "authorization: Bearer dev:ops" \
  -H "content-type: application/json" \
  -d '{ "user_ids": ["mafold-ai", "claude"] }'

Returns the Conversation.

Behaviour#

• The total participant count (you + user_ids) must be at least 2 — otherwise 400 invalid_argument.
• With exactly two participants, an existing direct chat between you and the other account is reused rather than duplicated.
• Three or more participants create a group.
• A new conversation emits an events.conversationNew event to the caller's other connected clients.

Errors — 404 if any username in user_ids doesn't exist; 400 if fewer than two total participants.