10 — AI Studio
The /api/ai chat surface: sessions, streaming responses, and conversation history.
User session required (requireUserSession) — API keys are refused
by design; the AI plane runs on the human's configured LLM keys.
Routes
| Method | Path | Notes |
|---|---|---|
POST | /api/ai/sessions | Open a session |
POST | /api/ai/chat | Send a turn — SSE stream of tokens/tool events |
GET | /api/ai/conversations | List past conversations |
POST | /api/ai/conversations | Create one |
GET | /api/ai/conversations/:id | Fetch |
DELETE | /api/ai/conversations/:id | Delete |
GET | /api/ai/conversations/:id/messages | Message history |
Behaviour worth knowing
- The agent's write tools (
wiki.*,atlas.upsert, …) do not mutate — they create proposals for the owner/GM review queue (07 — Proposals). - Tool calls run through the same authorization as the REST routes; chat tool results render as "waiting for review" cards.
- LLM provider keys come from
/api/settings/llm-key(user-scoped, SSRF-guardedbase_urlwith DNS-rebinding pinning). - System prompt:
studio/agent@v2(apps/api/src/agent/system-prompt.ts).
For programmatic agents, prefer the MCP endpoint
(11 — MCP) — it works with an API key, unlike /api/ai.