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 directly

What's next#

Chat Completions — the underlying inference call.
ScaiBot — for embeddable customer-facing chatbots (built on sessions).
Sessions and Rooms Reference — full endpoint list.