---
title: Sessions and Rooms
path: api-guides/sessions-and-rooms
status: published
---

# Sessions and Rooms

Two abstractions for conversations, solving different problems.

- **Sessions** — persistent one-on-one conversations between a user and a model. ScaiGrid stores the history; your client doesn't need to pass it every time.
- **Rooms** — multi-party shared spaces. Multiple users, multiple AIs, messages with threading.

Use sessions for chat UIs where each user has their own conversation. Use rooms when several participants (users, bots, agents) coexist and need to see each other's messages.

## Sessions

### Creating a session

```bash
curl -X POST https://scaigrid.scailabs.ai/v1/sessions \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "scailabs/poolnoodle-omni",
    "title": "Product planning",
    "system_prompt": "You are a product strategy consultant.",
    "metadata": {"project_id": "proj_123"}
  }'
```

```python
resp = httpx.post(
    "https://scaigrid.scailabs.ai/v1/sessions",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "scailabs/poolnoodle-omni",
        "title": "Product planning",
        "system_prompt": "You are a product strategy consultant.",
        "metadata": {"project_id": "proj_123"},
    },
)
session = resp.json()["data"]
print(session["id"])  # sess_abc123
```

```typescript
const resp = await fetch("https://scaigrid.scailabs.ai/v1/sessions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "scailabs/poolnoodle-omni",
    title: "Product planning",
    system_prompt: "You are a product strategy consultant.",
    metadata: { project_id: "proj_123" },
  }),
});
const session = (await resp.json()).data;
```

### Sending a message

```bash
curl -X POST https://scaigrid.scailabs.ai/v1/sessions/{session_id}/messages \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "What positioning would work for a B2B dev tool targeting enterprise infra teams?",
    "stream": false
  }'
```

The session already knows the model and system prompt — you just send the new user message. ScaiGrid appends it to the stored history, calls the model, stores the assistant's reply, and returns both.

Response:

```json
{
  "status": "ok",
  "data": {
    "message_id": "msg_xyz",
    "content": "For enterprise infrastructure teams, position as...",
    "finish_reason": "stop",
    "usage": {"prompt_tokens": 142, "completion_tokens": 289}
  }
}
```

### Listing sessions

```bash
curl "https://scaigrid.scailabs.ai/v1/sessions?limit=20" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY"
```

Returns sessions the caller owns. Tenant admins can see all sessions in their tenant via a `?scope=tenant` query param.

### Retrieving full history

```bash
curl https://scaigrid.scailabs.ai/v1/sessions/{session_id} \
  -H "Authorization: Bearer $SCAIGRID_API_KEY"
```

Returns the session plus all its messages in order. Useful for rebuilding a chat UI on page reload.

### Streaming messages

Same as chat completions — set `"stream": true`:

```python
with httpx.stream(
    "POST",
    f"https://scaigrid.scailabs.ai/v1/sessions/{session_id}/messages",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"content": "Summarize our discussion.", "stream": True},
    timeout=600,
) as r:
    for line in r.iter_lines():
        if line.startswith("data: "):
            payload = line[6:]
            if payload == "[DONE]":
                break
            chunk = json.loads(payload)
            print(chunk["choices"][0]["delta"].get("content", ""), end="", flush=True)
```

### Updating session metadata

```bash
curl -X PATCH https://scaigrid.scailabs.ai/v1/sessions/{session_id} \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Product positioning strategy"}'
```

Editable fields: `title`, `system_prompt`, `metadata`, `status` (`active` / `closed`).

### Deleting a session

```bash
curl -X DELETE https://scaigrid.scailabs.ai/v1/sessions/{session_id} \
  -H "Authorization: Bearer $SCAIGRID_API_KEY"
```

Soft-delete — the session is marked deleted but its audit trail persists. Hard-deletion is an admin-only operation.

## Rooms

Rooms host conversations with multiple participants. Think of them as Slack channels where both humans and AI agents post.

### Creating a room

```bash
curl -X POST https://scaigrid.scailabs.ai/v1/rooms \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Design Review",
    "description": "Weekly product design review",
    "initial_members": [
      {"type": "user", "id": "user_alice"},
      {"type": "user", "id": "user_bob"},
      {"type": "bot", "id": "bot_design_reviewer"}
    ]
  }'
```

### Adding members

```bash
curl -X POST https://scaigrid.scailabs.ai/v1/rooms/{room_id}/members \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "user", "id": "user_carol"}'
```

Member types:
- `user` — a ScaiGrid user
- `bot` — a ScaiBot instance
- `agent` — a ScaiCore instance
- `persona` — a ScaiPersona-published model

### Posting a message

```bash
curl -X POST https://scaigrid.scailabs.ai/v1/rooms/{room_id}/messages \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Can someone review the new onboarding flow?",
    "mention": [{"type": "bot", "id": "bot_design_reviewer"}]
  }'
```

If `mention` targets an AI participant, ScaiGrid triggers that participant to respond. Users see both the original message and the AI's reply in real time.

### Threaded replies

```bash
curl -X POST https://scaigrid.scailabs.ai/v1/rooms/{room_id}/messages/{msg_id}/reply \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "I think the CTA should be stronger."}'
```

## When to use which

| Scenario | Use |
|----------|-----|
| Simple chat UI, one user + one model | **Sessions** |
| Customer support bot with human escalation | **Sessions** (human takes over via admin UI) |
| Multi-agent collaboration (several AI agents coordinating) | **Rooms** |
| Team Slack-like workspace with AI participants | **Rooms** |
| Ephemeral one-shot request, no persistence needed | Neither — use [Chat Completions](./01-chat-completions.md) directly |

## What's next

- [Chat Completions](./01-chat-completions.md) — the underlying inference call.
- [ScaiBot](/docs/scaigrid/scaibot) — for embeddable customer-facing chatbots (built on sessions).
- [Sessions and Rooms Reference](../06-reference/06-sessions-and-rooms.md) — full endpoint list.