Sessions and Rooms Reference

All session and room endpoints. For usage patterns, see Sessions and Rooms.

Sessions#

POST /v1/sessions#

Create a session.

1
2
3
4
5
6

{
  "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.

1
2
3
4
5
6

{
  "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.

1
2
3
4
5

{
  "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.

1
2
3
4
5
6
7
8

{
  "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.

1

{"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.

1
2
3
4
5

{
  "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.

1

{"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#

Related#

• Sessions and Rooms (guide)
• Chat Completions
• ScaiBot — chatbot built on sessions