AI API

33 endpoints — the largest router. Grouped here by concern.

Models and commands#

Engagement (per room)#

POST /v1/rooms/{room_id}/ai/engage#

1

{ "participant_id": "ai-claude-…" }

The AI joins the room (if not already a member) and is invited to reply to the most recent message.

PUT /v1/rooms/{room_id}/ai/response-mode#

1

{ "mode": "conversational", "participant_id": null }

participant_id selects which AI in a multi-AI room; null applies to every AI.

Plugins (per-room toggle)#

Memory#

ScaiLink (specialist external tools)#

Agents (sidekick-style)#

For the higher-level sidekick + planner surface, see Sidekicks and plans.

Approvals#

Approval requests come from AI tool calls flagged side_effects=True in multi-user rooms.

1

{ "decision": "approve" }

or

1

{ "decision": "reject", "reason": "Wrong scope" }

Search#

1
2
3
4
5
6

{
  "query": "agentic planner",
  "room_id": "<optional>",
  "workspace_ids": ["<optional>"],
  "limit": 10
}

Returns:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "data": {
    "messages": [
      {
        "event_id": "evt-…",
        "room_id": "room-…",
        "sender_id": "5e4d…",
        "body": "...matching snippet...",
        "score": 0.87
      }
    ],
    "notes": [...]
  }
}

Errors#

• SW_AI_NO_TOKEN — caller has no ScaiGrid token and the tenant has no static fallback.
• SW_AI_MODEL_NOT_FOUND — selected model isn't registered with this tenant.
• SW_AI_BUSY — there's already a generation in flight (use /stop first or wait).
• SW_AI_BUDGET_EXCEEDED — tenant or per-user monthly token budget hit.
• SW_PLUGIN_FORBIDDEN — plugin disabled for tenant/room.
• SW_PLUGIN_NOT_FOUND — plugin id unknown.
• SW_PLAN_* — see Sidekicks and plans.