> ## Documentation Index
> Fetch the complete documentation index at: https://hyperspeed.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**

<ParamField path="orgId" type="string" required>Organization UUID.</ParamField>
<ParamField path="spaceId" type="string" required>Space UUID.</ParamField>

**Example**

```bash theme={null}
curl https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/chat-rooms \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response** `200 OK`

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

<ResponseField name="chat_rooms[].id" type="string">Chat room UUID.</ResponseField>
<ResponseField name="chat_rooms[].space_id" type="string">Parent space UUID.</ResponseField>
<ResponseField name="chat_rooms[].name" type="string">Room name.</ResponseField>
<ResponseField name="chat_rooms[].created_at" type="string">ISO 8601 creation timestamp.</ResponseField>

***

### Create a chat room

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

Requires the `chat.write` permission.

**Path parameters**

<ParamField path="orgId" type="string" required>Organization UUID.</ParamField>
<ParamField path="spaceId" type="string" required>Space UUID.</ParamField>

**Request body**

<ParamField body="name" type="string" required>
  Display name for the chat room. Leading/trailing whitespace is stripped.
</ParamField>

**Example**

```bash theme={null}
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`

```json theme={null}
{
  "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**

<ParamField path="orgId" type="string" required>Organization UUID.</ParamField>
<ParamField path="spaceId" type="string" required>Space UUID.</ParamField>
<ParamField path="roomId" type="string" required>Chat room UUID.</ParamField>

**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**

<ParamField path="orgId" type="string" required>Organization UUID.</ParamField>
<ParamField path="spaceId" type="string" required>Space UUID.</ParamField>
<ParamField path="roomId" type="string" required>Chat room UUID.</ParamField>

**Query parameters**

<ParamField query="limit" type="integer">
  Maximum messages to return. Defaults to 50, maximum 200.
</ParamField>

<ParamField query="before" type="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.
</ParamField>

**Example**

```bash theme={null}
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`

```json theme={null}
{
  "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": []
}
```

<ResponseField name="messages[].id" type="string">Message UUID.</ResponseField>
<ResponseField name="messages[].chat_room_id" type="string">Chat room UUID.</ResponseField>
<ResponseField name="messages[].space_id" type="string">Space UUID.</ResponseField>
<ResponseField name="messages[].author_user_id" type="string">UUID of the user who posted the message. May be `null` for system messages.</ResponseField>
<ResponseField name="messages[].content" type="string">Message text. Empty string for deleted messages.</ResponseField>
<ResponseField name="messages[].edited_at" type="string">Timestamp of last edit, or `null`.</ResponseField>
<ResponseField name="messages[].deleted_at" type="string">Set when the message has been soft-deleted, otherwise `null`.</ResponseField>
<ResponseField name="reactions" type="array">Emoji reactions across all messages in this batch.</ResponseField>
<ResponseField name="attachments" type="array">File attachments across all messages in this batch.</ResponseField>

***

### 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**

<ParamField path="orgId" type="string" required>Organization UUID.</ParamField>
<ParamField path="spaceId" type="string" required>Space UUID.</ParamField>
<ParamField path="roomId" type="string" required>Chat room UUID.</ParamField>

**Request body**

<ParamField body="content" type="string" required>
  Message text. Required unless `attachments` is non-empty.
</ParamField>

<ParamField body="attachments" type="array">
  Optional list of file attachment metadata objects. Each attachment must have a `url`.
</ParamField>

<ParamField body="attachments[].name" type="string">
  File name for display.
</ParamField>

<ParamField body="attachments[].mime" type="string">
  MIME type, e.g. `"image/png"`.
</ParamField>

<ParamField body="attachments[].size_bytes" type="integer">
  File size in bytes.
</ParamField>

<ParamField body="attachments[].url" type="string">
  Publicly accessible URL of the file. Required per attachment.
</ParamField>

**Example** — simple text message

```bash theme={null}
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`

```json theme={null}
{
  "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.

<ParamField body="content" type="string" required>
  New message text.
</ParamField>

**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
```

<ParamField body="emoji" type="string" required>
  A single emoji character, e.g. `"👍"`.
</ParamField>

**Response** `201 Created`

```json theme={null}
{
  "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**

<ParamField query="emoji" type="string" required>
  The emoji to remove.
</ParamField>

**Response** `204 No Content`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.