---
audience: developer
summary: Engagement, response mode, system prompts, plugins, sampling, search, memory,
  ScaiLink consent, agents, approvals.
title: AI API
path: reference/api/ai
status: published
---

# AI API

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

## Models and commands

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/ai/models` | Tenant's enabled models. |
| `GET` | `/v1/commands` | Slash-command catalog (machine-readable). |

## Engagement (per room)

| Method | Path | Purpose |
|---|---|---|
| `POST` | `/v1/rooms/{room_id}/ai/engage` | Engage an AI for this room (one turn or persistent based on mode). |
| `PUT` | `/v1/rooms/{room_id}/ai/engagement` | Set engagement mode (`mention` / `default` / `engage`). |
| `POST` | `/v1/rooms/{room_id}/ai/stop` | Cancel an in-flight generation. |
| `POST` | `/v1/rooms/{room_id}/ai/compact` | Summarise + start fresh (frees context budget). |
| `PUT` | `/v1/rooms/{room_id}/ai/response-mode` | Streaming / conversational, per-AI or room-wide. |
| `GET` | `/v1/rooms/{room_id}/ai/system-prompt` | Read room-level system prompt override. |
| `PUT` | `/v1/rooms/{room_id}/ai/system-prompt` | Set / clear override. |
| `GET` | `/v1/rooms/{room_id}/ai/temperature` | Read temperature. |
| `PUT` | `/v1/rooms/{room_id}/ai/temperature` | Set temperature. |

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

```json
{ "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

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

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

## Plugins (per-room toggle)

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/plugins` | List plugins available + their per-tenant state. |
| `POST` | `/v1/plugins/{plugin_id}/toggle` | Enable / disable for the tenant (admin). |
| `POST` | `/v1/rooms/{room_id}/plugins/{plugin_id}/toggle` | Per-room override. |

## Memory

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/memories` | List your long-term memories. |
| `POST` | `/v1/memories` | Add one manually (most are AI-created). |
| `POST` | `/v1/memories/forget` | Delete one or many (by id list or filter). |

## ScaiLink (specialist external tools)

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/modules/scailink/capabilities` | What tools are available via ScaiLink. |
| `GET` | `/v1/modules/scailink/status` | Connection status. |
| `GET` | `/v1/modules/scailink/sessions` | Active ScaiLink sessions. |
| `GET` | `/v1/modules/scailink/users/{user_id}/capabilities` | Per-user capability listing. |
| `GET` | `/v1/modules/scailink/users/{user_id}/sessions` | Per-user sessions. |
| `GET` | `/v1/modules/scailink/consent` | Pending consent requests. |
| `POST` | `/v1/modules/scailink/consent/{consent_id}/resolve` | Approve / reject a request. |
| `DELETE` | `/v1/modules/scailink/consent/{tool_name}` | Revoke ongoing consent for a tool. |

## Agents (sidekick-style)

| Method | Path | Purpose |
|---|---|---|
| `POST` | `/v1/rooms/{room_id}/ai/agent/spawn` | Spawn an agent task (low-level; prefer `/v1/rooms/.../sidekicks`). |
| `GET` | `/v1/rooms/{room_id}/ai/agent/tasks` | List agent tasks in this room. |
| `GET` | `/v1/rooms/{room_id}/ai/agent/tasks/{task_id}` | Detail. |
| `POST` | `/v1/rooms/{room_id}/ai/agent/tasks/{task_id}/suspend` | Pause. |
| `POST` | `/v1/rooms/{room_id}/ai/agent/tasks/{task_id}/terminate` | Stop. |

For the higher-level sidekick + planner surface, see
[Sidekicks and plans](/docs/scaiwave/reference/api/sidekicks-and-plans).

## Approvals

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/rooms/{room_id}/ai/approval` | List pending approval requests in this room. |
| `POST` | `/v1/rooms/{room_id}/ai/approval/{req_id}` | Approve or reject. |

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

```json
{ "decision": "approve" }
```

or

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

## Search

| Method | Path | Purpose |
|---|---|---|
| `POST` | `/v1/search` | Hybrid (BM25 + vector) over messages and notes. |

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

Returns:

```json
{
  "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](/docs/scaiwave/reference/api/sidekicks-and-plans).