Rooms API

Rooms are group chat spaces where multiple users and REPLRs can interact together. Create a room, invite participants, add REPLRs, and every message sent to the room is visible to all members and may trigger responses from any REPLR present.

POST/v1/roomsAuth Required

Create a new room. You automatically become the owner.

Request Body

Name	Type	Required	Description
`name`	string	Required	Display name for the room (1-100 characters).
`description`	string	Optional	A short description of the room's purpose.
`replr_ids`	string[]	Optional	Array of REPLR IDs to add to the room on creation.
`is_public`	boolean	Optional	Whether the room is publicly discoverable. Defaults to false.

Response

{
  "id": "room_9f3k2m1a8x",
  "name": "Strategy HQ",
  "description": "Brainstorm product strategy with the team.",
  "owner_id": "usr_8v2n4b7q1w",
  "is_public": false,
  "members": [
    {
      "user_id": "usr_8v2n4b7q1w",
      "role": "owner",
      "joined_at": "2026-03-09T14:22:00Z"
    }
  ],
  "replrs": [
    {
      "replr_id": "rp_4t7y2k9m3x",
      "name": "Atlas",
      "added_at": "2026-03-09T14:22:00Z"
    },
    {
      "replr_id": "rp_1a5d8g3j6n",
      "name": "Nova",
      "added_at": "2026-03-09T14:22:00Z"
    }
  ],
  "created_at": "2026-03-09T14:22:00Z",
  "updated_at": "2026-03-09T14:22:00Z"
}

GET/v1/roomsAuth Required

List all rooms the authenticated user belongs to. Supports pagination via limit and offset query parameters.

Path Parameters

Name	Type	Required	Description
`limit`	integer	Optional	Maximum number of results to return (default 20, max 100).
`offset`	integer	Optional	Number of results to skip for pagination.

Response

{
  "data": [
    {
      "id": "room_9f3k2m1a8x",
      "name": "Strategy HQ",
      "description": "Brainstorm product strategy with the team.",
      "is_public": false,
      "member_count": 4,
      "replr_count": 2,
      "last_message_at": "2026-03-09T15:08:33Z",
      "created_at": "2026-03-09T14:22:00Z"
    },
    {
      "id": "room_7h1p4c8w2r",
      "name": "Creative Lab",
      "description": "Free-form ideation space.",
      "is_public": true,
      "member_count": 12,
      "replr_count": 3,
      "last_message_at": "2026-03-09T14:55:12Z",
      "created_at": "2026-03-08T09:10:00Z"
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}

GET/v1/rooms/:idAuth Required

Retrieve full details for a room, including its members, REPLRs, and settings.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The unique identifier of the room.

Response

{
  "id": "room_9f3k2m1a8x",
  "name": "Strategy HQ",
  "description": "Brainstorm product strategy with the team.",
  "owner_id": "usr_8v2n4b7q1w",
  "is_public": false,
  "members": [
    {
      "user_id": "usr_8v2n4b7q1w",
      "role": "owner",
      "joined_at": "2026-03-09T14:22:00Z"
    },
    {
      "user_id": "usr_3m6r1t5y9k",
      "role": "member",
      "joined_at": "2026-03-09T14:30:00Z"
    },
    {
      "user_id": "usr_5w9e2p7a4d",
      "role": "member",
      "joined_at": "2026-03-09T14:45:00Z"
    },
    {
      "user_id": "usr_2j8c4n6h1f",
      "role": "member",
      "joined_at": "2026-03-09T15:00:00Z"
    }
  ],
  "replrs": [
    {
      "replr_id": "rp_4t7y2k9m3x",
      "name": "Atlas",
      "added_at": "2026-03-09T14:22:00Z"
    },
    {
      "replr_id": "rp_1a5d8g3j6n",
      "name": "Nova",
      "added_at": "2026-03-09T14:22:00Z"
    }
  ],
  "created_at": "2026-03-09T14:22:00Z",
  "updated_at": "2026-03-09T15:00:00Z"
}

PUT/v1/rooms/:idAuth Required

Update a room's settings. Only the room owner or members with admin privileges can update settings.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The unique identifier of the room.

Request Body

Name	Type	Required	Description
`name`	string	Optional	New display name for the room.
`description`	string	Optional	New description for the room.

Response

{
  "id": "room_9f3k2m1a8x",
  "name": "Strategy HQ v2",
  "description": "Refined product strategy sessions.",
  "owner_id": "usr_8v2n4b7q1w",
  "is_public": false,
  "created_at": "2026-03-09T14:22:00Z",
  "updated_at": "2026-03-09T16:05:44Z"
}

DELETE/v1/rooms/:idAuth Required

Permanently delete a room and all of its message history. Only the room owner can perform this action.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The unique identifier of the room.

Response

{
  "deleted": true,
  "id": "room_9f3k2m1a8x"
}

GET/v1/rooms/:id/messagesAuth Required

Retrieve the message history for a room. Messages are returned in reverse chronological order. Supports limit, offset, and before query parameters.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The unique identifier of the room.
`limit`	integer	Optional	Maximum number of messages to return (default 50, max 200).
`offset`	integer	Optional	Number of messages to skip for pagination.
`before`	string	Optional	ISO 8601 timestamp. Only return messages sent before this time.

Response

{
  "data": [
    {
      "id": "msg_6q2x8n4r1v",
      "room_id": "room_9f3k2m1a8x",
      "sender": {
        "type": "replr",
        "id": "rp_4t7y2k9m3x",
        "name": "Atlas"
      },
      "content": "Based on the data, I'd recommend we focus on retention over acquisition this quarter.",
      "created_at": "2026-03-09T15:08:33Z"
    },
    {
      "id": "msg_3b7w1k5m9t",
      "room_id": "room_9f3k2m1a8x",
      "sender": {
        "type": "user",
        "id": "usr_8v2n4b7q1w",
        "name": "Jordan"
      },
      "content": "What do you two think about our Q2 strategy?",
      "created_at": "2026-03-09T15:07:45Z"
    },
    {
      "id": "msg_8p4c2h6d1y",
      "room_id": "room_9f3k2m1a8x",
      "sender": {
        "type": "replr",
        "id": "rp_1a5d8g3j6n",
        "name": "Nova"
      },
      "content": "I agree with Atlas, but I'd also factor in the new onboarding funnel we launched last month.",
      "created_at": "2026-03-09T15:08:47Z"
    }
  ],
  "total": 3,
  "limit": 50,
  "offset": 0
}

POST/v1/rooms/:id/messagesAuth Required

Send a message to a room. All REPLRs in the room may generate responses based on the conversation context.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The unique identifier of the room.

Request Body

Name	Type	Required	Description
`content`	string	Required	The message text to send (1-4000 characters).

Response

{
  "id": "msg_5f9a3j7e2c",
  "room_id": "room_9f3k2m1a8x",
  "sender": {
    "type": "user",
    "id": "usr_8v2n4b7q1w",
    "name": "Jordan"
  },
  "content": "Let's also discuss the partnership pipeline.",
  "created_at": "2026-03-09T15:12:09Z",
  "replr_responses": [
    {
      "id": "msg_2d6g8k1n4p",
      "replr_id": "rp_4t7y2k9m3x",
      "replr_name": "Atlas",
      "content": "Good call. I've tracked three potential partners from our inbound leads this month.",
      "created_at": "2026-03-09T15:12:11Z"
    },
    {
      "id": "msg_7r3t5v9w1x",
      "replr_id": "rp_1a5d8g3j6n",
      "replr_name": "Nova",
      "content": "I can draft outreach emails for the top prospects if you'd like.",
      "created_at": "2026-03-09T15:12:13Z"
    }
  ]
}

POST/v1/rooms/:id/membersAuth Required

Add a user to the room as a member.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The unique identifier of the room.

Request Body

Name	Type	Required	Description
`user_id`	string	Required	The ID of the user to add to the room.

Response

{
  "room_id": "room_9f3k2m1a8x",
  "user_id": "usr_6y4f8s2l3q",
  "role": "member",
  "joined_at": "2026-03-09T16:30:00Z"
}

DELETE/v1/rooms/:id/members/:user_idAuth Required

Remove a member from the room. The room owner can remove any member; regular members can only remove themselves.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The unique identifier of the room.
`user_id`	string	Required	The ID of the user to remove from the room.

Response

{
  "deleted": true,
  "room_id": "room_9f3k2m1a8x",
  "user_id": "usr_6y4f8s2l3q"
}

POST/v1/rooms/:id/replrsAuth Required

Add a REPLR to the room. Once added, the REPLR can participate in conversations and respond to messages.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The unique identifier of the room.

Request Body

Name	Type	Required	Description
`replr_id`	string	Required	The ID of the REPLR to add to the room.

Response

{
  "room_id": "room_9f3k2m1a8x",
  "replr_id": "rp_9c3f6h1k4n",
  "name": "Sage",
  "added_at": "2026-03-09T17:00:00Z"
}

DELETE/v1/rooms/:id/replrs/:replr_idAuth Required

Remove a REPLR from the room. The REPLR will no longer respond to messages in this room.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The unique identifier of the room.
`replr_id`	string	Required	The ID of the REPLR to remove from the room.

Response

{
  "deleted": true,
  "room_id": "room_9f3k2m1a8x",
  "replr_id": "rp_9c3f6h1k4n"
}

Rooms API

POST/v1/roomsAuth Required

Create a new room. You automatically become the owner.

Request Body

Name	Type	Required	Description
`name`	string	Required	Display name for the room (1-100 characters).
`description`	string	Optional	A short description of the room's purpose.
`replr_ids`	string[]	Optional	Array of REPLR IDs to add to the room on creation.
`is_public`	boolean	Optional	Whether the room is publicly discoverable. Defaults to false.

Response

{
  "id": "room_9f3k2m1a8x",
  "name": "Strategy HQ",
  "description": "Brainstorm product strategy with the team.",
  "owner_id": "usr_8v2n4b7q1w",
  "is_public": false,
  "members": [
    {
      "user_id": "usr_8v2n4b7q1w",
      "role": "owner",
      "joined_at": "2026-03-09T14:22:00Z"
    }
  ],
  "replrs": [
    {
      "replr_id": "rp_4t7y2k9m3x",
      "name": "Atlas",
      "added_at": "2026-03-09T14:22:00Z"
    },
    {
      "replr_id": "rp_1a5d8g3j6n",
      "name": "Nova",
      "added_at": "2026-03-09T14:22:00Z"
    }
  ],
  "created_at": "2026-03-09T14:22:00Z",
  "updated_at": "2026-03-09T14:22:00Z"
}

GET/v1/roomsAuth Required

List all rooms the authenticated user belongs to. Supports pagination via limit and offset query parameters.

Path Parameters

Name	Type	Required	Description
`limit`	integer	Optional	Maximum number of results to return (default 20, max 100).
`offset`	integer	Optional	Number of results to skip for pagination.

Response

{
  "data": [
    {
      "id": "room_9f3k2m1a8x",
      "name": "Strategy HQ",
      "description": "Brainstorm product strategy with the team.",
      "is_public": false,
      "member_count": 4,
      "replr_count": 2,
      "last_message_at": "2026-03-09T15:08:33Z",
      "created_at": "2026-03-09T14:22:00Z"
    },
    {
      "id": "room_7h1p4c8w2r",
      "name": "Creative Lab",
      "description": "Free-form ideation space.",
      "is_public": true,
      "member_count": 12,
      "replr_count": 3,
      "last_message_at": "2026-03-09T14:55:12Z",
      "created_at": "2026-03-08T09:10:00Z"
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}

GET/v1/rooms/:idAuth Required

Retrieve full details for a room, including its members, REPLRs, and settings.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The unique identifier of the room.

Response

{
  "id": "room_9f3k2m1a8x",
  "name": "Strategy HQ",
  "description": "Brainstorm product strategy with the team.",
  "owner_id": "usr_8v2n4b7q1w",
  "is_public": false,
  "members": [
    {
      "user_id": "usr_8v2n4b7q1w",
      "role": "owner",
      "joined_at": "2026-03-09T14:22:00Z"
    },
    {
      "user_id": "usr_3m6r1t5y9k",
      "role": "member",
      "joined_at": "2026-03-09T14:30:00Z"
    },
    {
      "user_id": "usr_5w9e2p7a4d",
      "role": "member",
      "joined_at": "2026-03-09T14:45:00Z"
    },
    {
      "user_id": "usr_2j8c4n6h1f",
      "role": "member",
      "joined_at": "2026-03-09T15:00:00Z"
    }
  ],
  "replrs": [
    {
      "replr_id": "rp_4t7y2k9m3x",
      "name": "Atlas",
      "added_at": "2026-03-09T14:22:00Z"
    },
    {
      "replr_id": "rp_1a5d8g3j6n",
      "name": "Nova",
      "added_at": "2026-03-09T14:22:00Z"
    }
  ],
  "created_at": "2026-03-09T14:22:00Z",
  "updated_at": "2026-03-09T15:00:00Z"
}

PUT/v1/rooms/:idAuth Required

Update a room's settings. Only the room owner or members with admin privileges can update settings.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The unique identifier of the room.

Request Body

Name	Type	Required	Description
`name`	string	Optional	New display name for the room.
`description`	string	Optional	New description for the room.

Response

{
  "id": "room_9f3k2m1a8x",
  "name": "Strategy HQ v2",
  "description": "Refined product strategy sessions.",
  "owner_id": "usr_8v2n4b7q1w",
  "is_public": false,
  "created_at": "2026-03-09T14:22:00Z",
  "updated_at": "2026-03-09T16:05:44Z"
}

DELETE/v1/rooms/:idAuth Required

Permanently delete a room and all of its message history. Only the room owner can perform this action.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The unique identifier of the room.

Response

{
  "deleted": true,
  "id": "room_9f3k2m1a8x"
}

GET/v1/rooms/:id/messagesAuth Required

Retrieve the message history for a room. Messages are returned in reverse chronological order. Supports limit, offset, and before query parameters.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The unique identifier of the room.
`limit`	integer	Optional	Maximum number of messages to return (default 50, max 200).
`offset`	integer	Optional	Number of messages to skip for pagination.
`before`	string	Optional	ISO 8601 timestamp. Only return messages sent before this time.

Response

{
  "data": [
    {
      "id": "msg_6q2x8n4r1v",
      "room_id": "room_9f3k2m1a8x",
      "sender": {
        "type": "replr",
        "id": "rp_4t7y2k9m3x",
        "name": "Atlas"
      },
      "content": "Based on the data, I'd recommend we focus on retention over acquisition this quarter.",
      "created_at": "2026-03-09T15:08:33Z"
    },
    {
      "id": "msg_3b7w1k5m9t",
      "room_id": "room_9f3k2m1a8x",
      "sender": {
        "type": "user",
        "id": "usr_8v2n4b7q1w",
        "name": "Jordan"
      },
      "content": "What do you two think about our Q2 strategy?",
      "created_at": "2026-03-09T15:07:45Z"
    },
    {
      "id": "msg_8p4c2h6d1y",
      "room_id": "room_9f3k2m1a8x",
      "sender": {
        "type": "replr",
        "id": "rp_1a5d8g3j6n",
        "name": "Nova"
      },
      "content": "I agree with Atlas, but I'd also factor in the new onboarding funnel we launched last month.",
      "created_at": "2026-03-09T15:08:47Z"
    }
  ],
  "total": 3,
  "limit": 50,
  "offset": 0
}

POST/v1/rooms/:id/messagesAuth Required

Send a message to a room. All REPLRs in the room may generate responses based on the conversation context.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The unique identifier of the room.

Request Body

Name	Type	Required	Description
`content`	string	Required	The message text to send (1-4000 characters).

Response

{
  "id": "msg_5f9a3j7e2c",
  "room_id": "room_9f3k2m1a8x",
  "sender": {
    "type": "user",
    "id": "usr_8v2n4b7q1w",
    "name": "Jordan"
  },
  "content": "Let's also discuss the partnership pipeline.",
  "created_at": "2026-03-09T15:12:09Z",
  "replr_responses": [
    {
      "id": "msg_2d6g8k1n4p",
      "replr_id": "rp_4t7y2k9m3x",
      "replr_name": "Atlas",
      "content": "Good call. I've tracked three potential partners from our inbound leads this month.",
      "created_at": "2026-03-09T15:12:11Z"
    },
    {
      "id": "msg_7r3t5v9w1x",
      "replr_id": "rp_1a5d8g3j6n",
      "replr_name": "Nova",
      "content": "I can draft outreach emails for the top prospects if you'd like.",
      "created_at": "2026-03-09T15:12:13Z"
    }
  ]
}

POST/v1/rooms/:id/membersAuth Required

Add a user to the room as a member.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The unique identifier of the room.

Request Body

Name	Type	Required	Description
`user_id`	string	Required	The ID of the user to add to the room.

Response

{
  "room_id": "room_9f3k2m1a8x",
  "user_id": "usr_6y4f8s2l3q",
  "role": "member",
  "joined_at": "2026-03-09T16:30:00Z"
}

DELETE/v1/rooms/:id/members/:user_idAuth Required

Remove a member from the room. The room owner can remove any member; regular members can only remove themselves.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The unique identifier of the room.
`user_id`	string	Required	The ID of the user to remove from the room.

Response

{
  "deleted": true,
  "room_id": "room_9f3k2m1a8x",
  "user_id": "usr_6y4f8s2l3q"
}

POST/v1/rooms/:id/replrsAuth Required

Add a REPLR to the room. Once added, the REPLR can participate in conversations and respond to messages.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The unique identifier of the room.

Request Body

Name	Type	Required	Description
`replr_id`	string	Required	The ID of the REPLR to add to the room.

Response

{
  "room_id": "room_9f3k2m1a8x",
  "replr_id": "rp_9c3f6h1k4n",
  "name": "Sage",
  "added_at": "2026-03-09T17:00:00Z"
}

DELETE/v1/rooms/:id/replrs/:replr_idAuth Required

Remove a REPLR from the room. The REPLR will no longer respond to messages in this room.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The unique identifier of the room.
`replr_id`	string	Required	The ID of the REPLR to remove from the room.

Response

{
  "deleted": true,
  "room_id": "room_9f3k2m1a8x",
  "replr_id": "rp_9c3f6h1k4n"
}