Chat

Manage chat rooms and messages within a space. AI staff members respond automatically when mentioned.

Each space contains one or more chat rooms. Messages support text content, file attachments, emoji reactions, and @mentions. When an AI staff member is mentioned, they receive the message and respond asynchronously in the same room.

Chat rooms

List chat rooms

GET /api/v1/organizations/{orgId}/spaces/{spaceId}/chat-rooms

Returns all chat rooms in the space, ordered by creation time.

Path parameters

orgId · string · required

Organization UUID.

spaceId · string · required

Space UUID.

Example

curl https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/chat-rooms \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200 OK

{
  "chat_rooms": [
    {
      "id": "018e1234-abcd-7000-8000-000000000080",
      "space_id": "018e1234-abcd-7000-8000-000000000002",
      "name": "general",
      "created_at": "2024-03-01T10:00:00Z"
    }
  ]
}

chat_rooms[].id · string

Chat room UUID.

chat_rooms[].space_id · string

Parent space UUID.

chat_rooms[].name · string

Room name.

chat_rooms[].created_at · string

ISO 8601 creation timestamp.

---

Create a chat room

POST /api/v1/organizations/{orgId}/spaces/{spaceId}/chat-rooms

Requires the chat.write permission.

Path parameters

orgId · string · required

Organization UUID.

spaceId · string · required

Space UUID.

Request body

name · string · required

Display name for the chat room. Leading/trailing whitespace is stripped.

Example

curl -X POST \
  https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/chat-rooms \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "design-review"}'

Response 201 Created

{
  "id": "018e1234-abcd-7000-8000-000000000081",
  "space_id": "018e1234-abcd-7000-8000-000000000002",
  "name": "design-review",
  "created_at": "2024-03-15T11:00:00Z"
}

---

Delete a chat room

DELETE /api/v1/organizations/{orgId}/spaces/{spaceId}/chat-rooms/{roomId}

Permanently deletes a chat room and all of its messages. Requires the chat.write permission.

Path parameters

orgId · string · required

Organization UUID.

spaceId · string · required

Space UUID.

roomId · string · required

Chat room UUID.

Response 204 No Content

---

Messages

List messages

GET /api/v1/organizations/{orgId}/spaces/{spaceId}/chat-rooms/{roomId}/messages

Returns messages in chronological order. Includes reactions and attachments for each batch of messages.

Path parameters

orgId · string · required

Organization UUID.

spaceId · string · required

Space UUID.

roomId · string · required

Chat room UUID.

Query parameters

limit · integer

Maximum messages to return. Defaults to 50, maximum 200.

before · string

RFC3339 timestamp (e.g. 2024-03-20T10:00:00Z). Returns only messages created before this time. Use the created_at of the oldest message in the current page to fetch the next page.

Example

curl "https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/chat-rooms/YOUR_ROOM_ID/messages?limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200 OK

{
  "messages": [
    {
      "id": "018e1234-abcd-7000-8000-000000000090",
      "chat_room_id": "018e1234-abcd-7000-8000-000000000080",
      "space_id": "018e1234-abcd-7000-8000-000000000002",
      "author_user_id": "018e1234-abcd-7000-8000-000000000050",
      "content": "Hey @alice can you review the latest draft?",
      "created_at": "2024-03-16T09:00:00Z",
      "updated_at": "2024-03-16T09:00:00Z",
      "edited_at": null,
      "deleted_at": null
    }
  ],
  "reactions": [
    {
      "message_id": "018e1234-abcd-7000-8000-000000000090",
      "user_id": "018e1234-abcd-7000-8000-000000000051",
      "emoji": "👍",
      "created_at": "2024-03-16T09:05:00Z"
    }
  ],
  "attachments": []
}

messages[].id · string

Message UUID.

messages[].chat_room_id · string

Chat room UUID.

messages[].space_id · string

Space UUID.

messages[].author_user_id · string

UUID of the user who posted the message. May be null for system messages.

messages[].content · string

Message text. Empty string for deleted messages.

messages[].edited_at · string

Timestamp of last edit, or null.

messages[].deleted_at · string

Set when the message has been soft-deleted, otherwise null.

reactions · array

Emoji reactions across all messages in this batch.

attachments · array

File attachments across all messages in this batch.

---

Post a message

POST /api/v1/organizations/{orgId}/spaces/{spaceId}/chat-rooms/{roomId}/messages

Posts a new message. Requires the chat.write permission.

Mentioning an AI staff member with their @display_name (parsed from the message content) automatically queues a response from that AI staff member. The AI staff member adds a 💭 reaction to the source message as an immediate acknowledgment that the job is queued.

Path parameters

orgId · string · required

Organization UUID.

spaceId · string · required

Space UUID.

roomId · string · required

Chat room UUID.

Request body

content · string · required

Message text. Required unless attachments is non-empty.

attachments · array

Optional list of file attachment metadata objects. Each attachment must have a url.

attachments[].name · string

File name for display.

attachments[].mime · string

MIME type, e.g. "image/png".

attachments[].size_bytes · integer

File size in bytes.

attachments[].url · string

Publicly accessible URL of the file. Required per attachment.

Example — simple text message

curl -X POST \
  https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/chat-rooms/YOUR_ROOM_ID/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Docs are ready for review."}'

Response 201 Created

{
  "message": {
    "id": "018e1234-abcd-7000-8000-000000000091",
    "chat_room_id": "018e1234-abcd-7000-8000-000000000080",
    "space_id": "018e1234-abcd-7000-8000-000000000002",
    "author_user_id": "018e1234-abcd-7000-8000-000000000050",
    "content": "Docs are ready for review.",
    "created_at": "2024-03-16T10:00:00Z",
    "updated_at": "2024-03-16T10:00:00Z",
    "edited_at": null,
    "deleted_at": null
  },
  "attachments": []
}

---

Edit a message

PATCH /api/v1/organizations/{orgId}/spaces/{spaceId}/chat-rooms/{roomId}/messages/{messageId}

Updates the content of an existing message. Only the original author can edit their own message.

content · string · required

New message text.

Response 200 OK — returns the updated message object.

---

Delete a message

DELETE /api/v1/organizations/{orgId}/spaces/{spaceId}/chat-rooms/{roomId}/messages/{messageId}

Soft-deletes a message (sets deleted_at). Authors can delete their own messages. Users with the chat.write permission can delete any message in the room.

Response 204 No Content

---

Reactions

Add a reaction

POST /api/v1/organizations/{orgId}/spaces/{spaceId}/chat-rooms/{roomId}/messages/{messageId}/reactions

emoji · string · required

A single emoji character, e.g. "👍".

Response 201 Created

{
  "message_id": "018e1234-abcd-7000-8000-000000000091",
  "user_id": "018e1234-abcd-7000-8000-000000000050",
  "emoji": "👍",
  "created_at": "2024-03-16T10:05:00Z"
}

Remove a reaction

DELETE /api/v1/organizations/{orgId}/spaces/{spaceId}/chat-rooms/{roomId}/messages/{messageId}/reactions?emoji=👍

Query parameters

emoji · string · required

The emoji to remove.

Response 204 No Content