Chat

All chat routes require X-User-Email and the chat permission. The user must be a member of the conversation.

List conversations

GET /api/v1/chat/conversations

Returns data.conversations[] with type, name, participants, last message, unread count, and mute state. Supports limit / offset.

Start a conversation

POST /api/v1/chat/conversations

{ "participantEmail": "teammate@example.com", "message": "Hello" }

participantEmail is required and must be another enabled user in the same tenant. If a direct conversation already exists, the API returns 200 with isNew: false. A new conversation is 201 with isNew: true.

Errors: PARTICIPANT_NOT_FOUND (404), INVALID_PARTICIPANT (400).

List messages

GET /api/v1/chat/messages?conversationId={uuid}

conversationId is required. Optional before (ISO timestamp) pages older messages. Reading a page updates the user's last-read time.

Errors: MISSING_CONVERSATION_ID (400), NOT_A_MEMBER (403).

Send a message

POST /api/v1/chat/messages

{ "conversationId": "11111111-2222-4333-8444-555555555555", "content": "Following up" }

content is 1–5000 characters. Returns 201 with data.message.

curl -sS "https://app.crystalqore.com/api/v1/chat/conversations" \
  -H "X-API-Key: $CRYSTALQORE_API_KEY" \
  -H "X-Tenant-Id: $CRYSTALQORE_TENANT_ID" \
  -H "X-User-Email: $CRYSTALQORE_USER_EMAIL"