---
title: Sessions and Rooms Reference
path: reference/sessions-and-rooms
status: published
---

# Sessions and Rooms Reference

All session and room endpoints. For usage patterns, see [Sessions and Rooms](../04-api-guides/05-sessions-and-rooms.md).

## Sessions

### POST /v1/sessions

Create a session.

```json
{
  "model": "scailabs/poolnoodle-omni",
  "title": "Product planning",
  "system_prompt": "You are a product strategist.",
  "metadata": {"project_id": "..."}
}
```

### GET /v1/sessions

List sessions owned by the caller. Tenant admins with `accounting:view_tenant` can query `?scope=tenant`.

### GET /v1/sessions/{session_id}

Get session details including all messages.

### PATCH /v1/sessions/{session_id}

Update session metadata.

```json
{
  "title": "...",
  "system_prompt": "...",
  "metadata": {...},
  "status": "active" | "closed"
}
```

### DELETE /v1/sessions/{session_id}

Soft-delete the session. Audit trail preserved.

### POST /v1/sessions/{session_id}/messages

Send a message.

```json
{
  "content": "What should we do about the onboarding flow?",
  "stream": false,
  "max_tokens": 1000
}
```

Returns the assistant reply. With `"stream": true`, returns an SSE stream of chunks.

## Rooms

### POST /v1/rooms

Create a room.

```json
{
  "name": "Design Review",
  "description": "Weekly review channel",
  "initial_members": [
    {"type": "user", "id": "user_alice"},
    {"type": "bot", "id": "bot_reviewer"}
  ]
}
```

### GET /v1/rooms

List rooms the caller is a member of.

### GET /v1/rooms/{room_id}

Get room details, members, recent messages.

### PATCH /v1/rooms/{room_id}

Update room metadata.

### DELETE /v1/rooms/{room_id}

Archive the room. Members lose access; history preserved for audit.

### POST /v1/rooms/{room_id}/members

Add a member.

```json
{"type": "user", "id": "user_bob", "role": "member"}
```

Member types: `user`, `bot`, `agent`, `persona`. Roles: `owner`, `member`, `viewer`.

### DELETE /v1/rooms/{room_id}/members/{member_id}

Remove a member.

### POST /v1/rooms/{room_id}/messages

Post a message.

```json
{
  "content": "Hey everyone — what do you think of the latest design?",
  "mention": [{"type": "bot", "id": "bot_reviewer"}],
  "attachments": []
}
```

If `mention` includes an AI participant, ScaiGrid triggers them to respond automatically.

### POST /v1/rooms/{room_id}/messages/{msg_id}/reply

Reply threaded to a message.

```json
{"content": "Good point. Also consider..."}
```

## Permissions

- `models:use` — required to create sessions or send messages.
- Sessions are owned by their creator; only the owner or a tenant admin can read/edit/delete.
- Rooms use member roles for access: `owner` full control, `member` can post, `viewer` read-only.

## Error codes

| Code | Meaning |
|------|---------|
| `SESSION_NOT_FOUND` | No session with that ID, or not owned by caller |
| `ROOM_NOT_FOUND` | No room with that ID, or caller not a member |
| `ROOM_MEMBER_NOT_FOUND` | Target member doesn't exist in room |
| `ROOM_ACCESS_DENIED` | Caller's role doesn't allow the action |

## Related

- [Sessions and Rooms (guide)](../04-api-guides/05-sessions-and-rooms.md)
- [Chat Completions](../04-api-guides/01-chat-completions.md)
- [ScaiBot](/docs/scaigrid/scaibot) — chatbot built on sessions