{ "openapi": "3.1.1", "info": { "title": "Cast API", "version": "1.0.0", "description": "Stable local integration API for a Cast daemon. Existing /api/* endpoints power the bundled web UI; use /api/v1/* for integrations." }, "servers": [ { "url": "/", "description": "The running Cast daemon" } ], "security": [ { "loopbackBearer": [] }, { "webSession": [] } ], "paths": { "/api/v1/personas": { "get": { "summary": "List personas", "responses": { "200": { "description": "Personas", "content": { "application/json": { "schema": { "type": "array" } } } } } } }, "/api/v1/git-info": { "get": { "summary": "Inspect a working directory's Git state", "responses": { "200": { "description": "Git state", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/config": { "get": { "summary": "Read the safe client configuration", "responses": { "200": { "description": "Configuration", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/commands": { "get": { "summary": "List slash commands", "responses": { "200": { "description": "Commands", "content": { "application/json": { "schema": { "type": "array" } } } } } } }, "/api/v1/themes": { "get": { "summary": "List themes", "responses": { "200": { "description": "Themes", "content": { "application/json": { "schema": { "type": "array" } } } } } } }, "/api/v1/models": { "get": { "summary": "Discover provider models", "responses": { "200": { "description": "Models", "content": { "application/json": { "schema": { "type": "array" } } } } } } }, "/api/v1/models/cached": { "get": { "summary": "Read cached provider models", "responses": { "200": { "description": "Models", "content": { "application/json": { "schema": { "type": "array" } } } } } } }, "/api/v1/skill-content": { "get": { "summary": "Read a skill's content", "responses": { "200": { "description": "Skill content", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/persona-content": { "get": { "summary": "Read a persona's content", "responses": { "200": { "description": "Persona content", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/suggest": { "get": { "summary": "Get composer suggestions", "responses": { "200": { "description": "Suggestions", "content": { "application/json": { "schema": { "type": "array" } } } } } } }, "/api/v1/settings/appearance": { "get": { "summary": "Read appearance settings", "responses": { "200": { "description": "Appearance", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "summary": "Update appearance settings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "showReasoning" ], "properties": { "showReasoning": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated appearance", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/settings/reasoning-options": { "get": { "summary": "List global reasoning options", "responses": { "200": { "description": "Reasoning options", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/settings/command": { "post": { "summary": "Run a supported global settings command", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandRequest" } } } }, "responses": { "200": { "description": "Command result", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/ssh/key": { "post": { "summary": "Configure an SSH key", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SshKeyRequest" } } } }, "responses": { "200": { "description": "Configured SSH key", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/ssh/add": { "post": { "summary": "Add an SSH host", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SshHostRequest" } } } }, "responses": { "200": { "description": "Added SSH host", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/provider/verify": { "post": { "summary": "Verify provider credentials", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderVerificationRequest" } } } }, "responses": { "200": { "description": "Verification", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/browse": { "get": { "summary": "Browse a permitted directory", "responses": { "200": { "description": "Directory listing", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a selected directory entry", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/browse/mkdir": { "post": { "summary": "Create a directory in the browser root", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/events": { "get": { "summary": "Subscribe to all session updates", "responses": { "200": { "description": "SSE stream", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/WebEvent" } } } } } } }, "/api/v1/sessions/{id}/events/history": { "get": { "summary": "Read execution event audit trail", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "responses": { "200": { "description": "Event history", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/image": { "get": { "summary": "Download a persisted message image", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "responses": { "200": { "description": "Image bytes", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/permanent": { "delete": { "summary": "Permanently delete a session", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/rename": { "post": { "summary": "Rename a session", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string" } } } } } }, "responses": { "200": { "description": "Renamed", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/pin": { "post": { "summary": "Pin or unpin a session", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pinned" ], "properties": { "pinned": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Pinned state", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/share": { "post": { "summary": "Create a share link", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "responses": { "200": { "description": "Share link", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Revoke a share link", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "responses": { "200": { "description": "Revoked, or already not shared", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/diff": { "get": { "summary": "Read the session working tree diff", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "responses": { "200": { "description": "Diff", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/sessions/{id}/reasoning-options": { "get": { "summary": "List session reasoning options", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "responses": { "200": { "description": "Reasoning options", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/sessions/{id}/fs": { "get": { "summary": "List session files", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "responses": { "200": { "description": "File listing", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "delete": { "summary": "Delete a session file", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/fs/search": { "get": { "summary": "Search session files", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/sessions/{id}/fs/download": { "get": { "summary": "Download a session file", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "responses": { "200": { "description": "File bytes", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/api/v1/sessions/{id}/fs/rename": { "post": { "summary": "Rename a session file", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Renamed", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/inputs": { "get": { "summary": "List session attachments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "responses": { "200": { "description": "Attachments", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "delete": { "summary": "Delete a session attachment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/inputs/upload": { "post": { "summary": "Upload a session attachment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "dataUrl" ] } } } }, "responses": { "200": { "description": "Uploaded attachment", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/inputs/download": { "get": { "summary": "Download a session attachment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "responses": { "200": { "description": "Attachment bytes", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/api/v1/openapi.json": { "get": { "summary": "Get this OpenAPI document", "security": [], "responses": { "200": { "description": "OpenAPI document", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/server/status": { "get": { "summary": "Get daemon status", "responses": { "200": { "description": "Daemon status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DaemonStatus" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/server/identity": { "get": { "summary": "Verify daemon process identity", "responses": { "200": { "description": "Daemon identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DaemonIdentity" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions": { "get": { "summary": "List sessions", "description": "Returns a plain array by default. Passing `limit` or `offset` switches the body to a paged object — clients that add paging must handle both shapes.", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Optional text search." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Page size. Presence of this or `offset` changes the response shape (see above)." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Page offset. Presence of this or `limit` changes the response shape (see above)." } ], "responses": { "200": { "description": "Session summaries — an array, or a paged object when limit/offset is given", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SessionSummary" } }, { "type": "object", "required": [ "sessions", "total", "limit", "offset" ], "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/SessionSummary" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } ] } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionRequest" } } } }, "responses": { "201": { "description": "Created session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionResponse" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}": { "get": { "summary": "Get a session and its recent history", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." }, { "name": "turns", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Unload a session from the daemon", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "responses": { "200": { "description": "Session unloaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/fork": { "post": { "summary": "Fork an idle session", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "responses": { "201": { "description": "Forked session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionResponse" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/chat": { "post": { "summary": "Start an agent turn", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatRequest" } } } }, "responses": { "202": { "description": "Turn accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/abort": { "post": { "summary": "Abort the current turn", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "responses": { "200": { "description": "Abort requested", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/steer": { "post": { "summary": "Inject a message into the current turn", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageRequest" } } } }, "responses": { "202": { "description": "Steer accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/followup": { "post": { "summary": "Queue a follow-up turn", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageRequest" } } } }, "responses": { "202": { "description": "Follow-up accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/command": { "post": { "summary": "Run a supported slash command", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandRequest" } } } }, "responses": { "200": { "description": "Command result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandResponse" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/mode": { "post": { "summary": "Set session mode", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "enum": [ "plan", "build" ] } } } } } }, "responses": { "200": { "description": "Mode changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/question": { "post": { "summary": "Answer a pending question", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "values" ], "properties": { "values": { "type": "array", "description": "One entry per question. A multi-select answer is itself an array of the chosen values.", "items": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } } } } }, "responses": { "202": { "description": "Answer accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/bash-confirm": { "post": { "summary": "Answer a pending dangerous-command confirmation", "description": "The daemon runs the agent loop, so its dangerous-command gate asks the connected clients. The turn stays blocked until this is answered or the request times out (denied).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "allow" ], "properties": { "id": { "type": "string", "description": "The id carried by the bash_confirm event." }, "allow": { "type": "boolean", "description": "True runs the command once; false blocks it." } } } } } }, "responses": { "202": { "description": "Answer accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/plan-transition": { "post": { "summary": "Resolve a plan completion transition", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "const": "done" } } } } } }, "responses": { "202": { "description": "Transition accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/clean-context": { "post": { "summary": "Clear a session's in-context working set", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "responses": { "200": { "description": "Context cleared", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/events": { "get": { "summary": "Subscribe to session events", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." } ], "responses": { "200": { "description": "SSE stream of WebEvent JSON payloads", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/WebEvent" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/sessions/{id}/history": { "get": { "summary": "Load older session history", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Cast session identifier." }, { "name": "before", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "turns", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "History page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryPage" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "loopbackBearer": { "type": "http", "scheme": "bearer", "description": "Token from server.json; accepted only from localhost." }, "webSession": { "type": "apiKey", "in": "cookie", "name": "cast_web_session", "description": "Authenticated web session cookie." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "Ok": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "const": true } } }, "DaemonStatus": { "type": "object", "required": [ "running" ], "properties": { "running": { "type": "boolean" }, "pid": { "type": "integer" }, "host": { "type": "string" }, "port": { "type": "integer" }, "startedAt": { "type": "string" }, "foreground": { "type": "boolean" } } }, "DaemonIdentity": { "type": "object", "properties": { "instanceId": { "type": "string" } } }, "SessionSummary": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "cwd": { "type": "string" }, "model": { "type": "string" }, "persona": { "type": "string" }, "status": { "enum": [ "idle", "running", "error" ] }, "updatedAt": { "type": "string" }, "createdAt": { "type": "string" }, "pinned": { "type": "boolean" }, "messageCount": { "type": "integer", "description": "Turns in the session, as the sidebar counts them." }, "isSandbox": { "type": "boolean", "description": "True when the session runs in a throwaway sandbox directory." } } }, "Session": { "type": "object", "required": [ "id", "status", "messages" ], "properties": { "id": { "type": "string" }, "persona": { "type": "string" }, "model": { "type": "string" }, "cwd": { "type": "string" }, "mode": { "enum": [ "plan", "build" ] }, "status": { "enum": [ "idle", "running", "error" ] }, "messages": { "type": "array", "items": { "type": "object" } }, "streaming": { "type": "array", "items": { "type": "object" } }, "hasMoreHistory": { "type": "boolean" }, "oldestSeq": { "type": [ "integer", "null" ] }, "title": { "type": "string" }, "pinned": { "type": "boolean" }, "shareToken": { "type": [ "string", "null" ], "description": "Public share token, when the session is shared." }, "turnStartedAt": { "type": [ "integer", "null" ], "description": "Epoch ms the in-flight turn began." }, "question": { "type": [ "object", "null" ], "description": "Pending question awaiting an answer." }, "planTransition": { "type": [ "object", "null" ] }, "usage": { "type": "object", "description": "Token and cost totals for the session." }, "backgroundTasks": { "type": "array", "description": "Background bash tasks still running for this session.", "items": { "type": "object", "required": [ "id", "command" ], "properties": { "id": { "type": "string" }, "command": { "type": "string" }, "startedAt": { "type": "integer", "description": "Epoch ms." } } } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } } }, "CreateSessionRequest": { "type": "object", "properties": { "persona": { "type": "string" }, "model": { "type": "string" }, "provider": { "type": "string", "description": "Pin the session to a saved provider by name." }, "cwd": { "type": "string", "description": "\"sandbox\" for a throwaway directory, or an absolute path." }, "worktree": { "type": "string", "description": "Mutually exclusive with a sandbox cwd." }, "agentId": { "type": "string", "description": "Spawn from a saved agent; its persona/model/provider override the fields above." } } }, "CreateSessionResponse": { "type": "object", "required": [ "id", "session" ], "properties": { "id": { "type": "string" }, "session": { "type": "object" } } }, "ChatRequest": { "type": "object", "properties": { "text": { "type": "string" }, "images": { "type": "array", "maxItems": 6, "items": { "type": "string", "contentEncoding": "base64" } }, "clientMessageId": { "type": "string", "maxLength": 200 }, "goal": { "description": "Run the turn as a goal: `true` for the default iteration budget, or a number (1-200) to set it.", "oneOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 1, "maximum": 200 } ] } }, "anyOf": [ { "required": [ "text" ] }, { "required": [ "images" ] } ] }, "MessageRequest": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "minLength": 1 } } }, "CommandRequest": { "type": "object", "required": [ "command" ], "properties": { "command": { "type": "string", "minLength": 1 } } }, "CommandResponse": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "const": true }, "result": {} } }, "SshKeyRequest": { "type": "object", "required": [ "name", "key" ], "properties": { "name": { "type": "string", "minLength": 1 }, "key": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "SshHostRequest": { "type": "object", "required": [ "name", "host" ], "properties": { "name": { "type": "string", "minLength": 1 }, "host": { "type": "string", "minLength": 1 }, "username": { "type": "string" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "keyPath": { "type": "string" }, "password": { "type": "string" } }, "additionalProperties": false }, "ProviderVerificationRequest": { "type": "object", "required": [ "url", "apiKey" ], "properties": { "url": { "type": "string", "minLength": 1 }, "apiKey": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "HistoryPage": { "type": "object", "required": [ "messages", "hasMoreHistory" ], "properties": { "messages": { "type": "array", "items": { "type": "object" } }, "oldestSeq": { "type": [ "integer", "null" ] }, "hasMoreHistory": { "type": "boolean" } } }, "WebEvent": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string" } }, "additionalProperties": true } } } }