{ "openapi": "3.0.3", "info": { "title": "sandbox-agent", "description": "", "contact": { "name": "Sandbox Agent Contributors" }, "license": { "name": "Apache-2.0" }, "version": "0.1.0" }, "servers": [ { "url": "http://localhost:2468" } ], "paths": { "/v1/agents": { "get": { "tags": [ "agents" ], "operationId": "list_agents", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentListResponse" } } } } } } }, "/v1/agents/{agent}/install": { "post": { "tags": [ "agents" ], "operationId": "install_agent", "parameters": [ { "name": "agent", "in": "path", "description": "Agent id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentInstallRequest" } } }, "required": true }, "responses": { "204": { "description": "Agent installed" }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/agents/{agent}/modes": { "get": { "tags": [ "agents" ], "operationId": "get_agent_modes", "parameters": [ { "name": "agent", "in": "path", "description": "Agent id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentModesResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/health": { "get": { "tags": [ "meta" ], "operationId": "get_health", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/v1/sessions": { "get": { "tags": [ "sessions" ], "operationId": "list_sessions", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionListResponse" } } } } } } }, "/v1/sessions/{session_id}": { "post": { "tags": [ "sessions" ], "operationId": "create_session", "parameters": [ { "name": "session_id", "in": "path", "description": "Client session id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/sessions/{session_id}/events": { "get": { "tags": [ "sessions" ], "operationId": "get_events", "parameters": [ { "name": "session_id", "in": "path", "description": "Session id", "required": true, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "Last seen event sequence (exclusive)", "required": false, "schema": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Max events to return", "required": false, "schema": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 } }, { "name": "include_raw", "in": "query", "description": "Include raw provider payloads", "required": false, "schema": { "type": "boolean", "nullable": true } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsResponse" } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/sessions/{session_id}/events/sse": { "get": { "tags": [ "sessions" ], "operationId": "get_events_sse", "parameters": [ { "name": "session_id", "in": "path", "description": "Session id", "required": true, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "Last seen event sequence (exclusive)", "required": false, "schema": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 } }, { "name": "include_raw", "in": "query", "description": "Include raw provider payloads", "required": false, "schema": { "type": "boolean", "nullable": true } } ], "responses": { "200": { "description": "SSE event stream" } } } }, "/v1/sessions/{session_id}/messages": { "post": { "tags": [ "sessions" ], "operationId": "post_message", "parameters": [ { "name": "session_id", "in": "path", "description": "Session id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageRequest" } } }, "required": true }, "responses": { "204": { "description": "Message accepted" }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/sessions/{session_id}/messages/stream": { "post": { "tags": [ "sessions" ], "operationId": "post_message_stream", "parameters": [ { "name": "session_id", "in": "path", "description": "Session id", "required": true, "schema": { "type": "string" } }, { "name": "include_raw", "in": "query", "description": "Include raw provider payloads", "required": false, "schema": { "type": "boolean", "nullable": true } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageRequest" } } }, "required": true }, "responses": { "200": { "description": "SSE event stream" }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/sessions/{session_id}/permissions/{permission_id}/reply": { "post": { "tags": [ "sessions" ], "operationId": "reply_permission", "parameters": [ { "name": "session_id", "in": "path", "description": "Session id", "required": true, "schema": { "type": "string" } }, { "name": "permission_id", "in": "path", "description": "Permission id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionReplyRequest" } } }, "required": true }, "responses": { "204": { "description": "Permission reply accepted" }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/sessions/{session_id}/questions/{question_id}/reject": { "post": { "tags": [ "sessions" ], "operationId": "reject_question", "parameters": [ { "name": "session_id", "in": "path", "description": "Session id", "required": true, "schema": { "type": "string" } }, { "name": "question_id", "in": "path", "description": "Question id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Question rejected" }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/sessions/{session_id}/questions/{question_id}/reply": { "post": { "tags": [ "sessions" ], "operationId": "reply_question", "parameters": [ { "name": "session_id", "in": "path", "description": "Session id", "required": true, "schema": { "type": "string" } }, { "name": "question_id", "in": "path", "description": "Question id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionReplyRequest" } } }, "required": true }, "responses": { "204": { "description": "Question answered" }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v1/sessions/{session_id}/terminate": { "post": { "tags": [ "sessions" ], "operationId": "terminate_session", "parameters": [ { "name": "session_id", "in": "path", "description": "Session id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Session terminated" }, "404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } } }, "components": { "schemas": { "AgentCapabilities": { "type": "object", "required": [ "planMode", "permissions", "questions", "toolCalls", "toolResults", "textMessages", "images", "fileAttachments", "sessionLifecycle", "errorEvents", "reasoning", "commandExecution", "fileChanges", "mcpTools", "streamingDeltas", "sharedProcess" ], "properties": { "commandExecution": { "type": "boolean" }, "errorEvents": { "type": "boolean" }, "fileAttachments": { "type": "boolean" }, "fileChanges": { "type": "boolean" }, "images": { "type": "boolean" }, "mcpTools": { "type": "boolean" }, "permissions": { "type": "boolean" }, "planMode": { "type": "boolean" }, "questions": { "type": "boolean" }, "reasoning": { "type": "boolean" }, "sessionLifecycle": { "type": "boolean" }, "sharedProcess": { "type": "boolean", "description": "Whether this agent uses a shared long-running server process (vs per-turn subprocess)" }, "streamingDeltas": { "type": "boolean" }, "textMessages": { "type": "boolean" }, "toolCalls": { "type": "boolean" }, "toolResults": { "type": "boolean" } } }, "AgentError": { "type": "object", "required": [ "type", "message" ], "properties": { "agent": { "type": "string", "nullable": true }, "details": { "nullable": true }, "message": { "type": "string" }, "session_id": { "type": "string", "nullable": true }, "type": { "$ref": "#/components/schemas/ErrorType" } } }, "AgentInfo": { "type": "object", "required": [ "id", "installed", "capabilities" ], "properties": { "capabilities": { "$ref": "#/components/schemas/AgentCapabilities" }, "id": { "type": "string" }, "installed": { "type": "boolean" }, "path": { "type": "string", "nullable": true }, "serverStatus": { "allOf": [ { "$ref": "#/components/schemas/ServerStatusInfo" } ], "nullable": true }, "version": { "type": "string", "nullable": true } } }, "AgentInstallRequest": { "type": "object", "properties": { "reinstall": { "type": "boolean", "nullable": true } } }, "AgentListResponse": { "type": "object", "required": [ "agents" ], "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentInfo" } } } }, "AgentModeInfo": { "type": "object", "required": [ "id", "name", "description" ], "properties": { "description": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } } }, "AgentModesResponse": { "type": "object", "required": [ "modes" ], "properties": { "modes": { "type": "array", "items": { "$ref": "#/components/schemas/AgentModeInfo" } } } }, "AgentUnparsedData": { "type": "object", "required": [ "error", "location" ], "properties": { "error": { "type": "string" }, "location": { "type": "string" }, "raw_hash": { "type": "string", "nullable": true } } }, "ContentPart": { "oneOf": [ { "type": "object", "required": [ "text", "type" ], "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] } } }, { "type": "object", "required": [ "json", "type" ], "properties": { "json": {}, "type": { "type": "string", "enum": [ "json" ] } } }, { "type": "object", "required": [ "name", "arguments", "call_id", "type" ], "properties": { "arguments": { "type": "string" }, "call_id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_call" ] } } }, { "type": "object", "required": [ "call_id", "output", "type" ], "properties": { "call_id": { "type": "string" }, "output": { "type": "string" }, "type": { "type": "string", "enum": [ "tool_result" ] } } }, { "type": "object", "required": [ "path", "action", "type" ], "properties": { "action": { "$ref": "#/components/schemas/FileAction" }, "diff": { "type": "string", "nullable": true }, "path": { "type": "string" }, "type": { "type": "string", "enum": [ "file_ref" ] } } }, { "type": "object", "required": [ "text", "visibility", "type" ], "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "reasoning" ] }, "visibility": { "$ref": "#/components/schemas/ReasoningVisibility" } } }, { "type": "object", "required": [ "path", "type" ], "properties": { "mime": { "type": "string", "nullable": true }, "path": { "type": "string" }, "type": { "type": "string", "enum": [ "image" ] } } }, { "type": "object", "required": [ "label", "type" ], "properties": { "detail": { "type": "string", "nullable": true }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "status" ] } } } ], "discriminator": { "propertyName": "type" } }, "CreateSessionRequest": { "type": "object", "required": [ "agent" ], "properties": { "agent": { "type": "string" }, "agentMode": { "type": "string", "nullable": true }, "agentVersion": { "type": "string", "nullable": true }, "model": { "type": "string", "nullable": true }, "permissionMode": { "type": "string", "nullable": true }, "variant": { "type": "string", "nullable": true } } }, "CreateSessionResponse": { "type": "object", "required": [ "healthy" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/AgentError" } ], "nullable": true }, "healthy": { "type": "boolean" }, "nativeSessionId": { "type": "string", "nullable": true } } }, "ErrorData": { "type": "object", "required": [ "message" ], "properties": { "code": { "type": "string", "nullable": true }, "details": { "nullable": true }, "message": { "type": "string" } } }, "ErrorType": { "type": "string", "enum": [ "invalid_request", "unsupported_agent", "agent_not_installed", "install_failed", "agent_process_exited", "token_invalid", "permission_denied", "session_not_found", "session_already_exists", "mode_not_supported", "stream_error", "timeout" ] }, "EventSource": { "type": "string", "enum": [ "agent", "daemon" ] }, "EventsQuery": { "type": "object", "properties": { "includeRaw": { "type": "boolean", "nullable": true }, "limit": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 }, "offset": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 } } }, "EventsResponse": { "type": "object", "required": [ "events", "hasMore" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/UniversalEvent" } }, "hasMore": { "type": "boolean" } } }, "FileAction": { "type": "string", "enum": [ "read", "write", "patch" ] }, "HealthResponse": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } } }, "ItemDeltaData": { "type": "object", "required": [ "item_id", "delta" ], "properties": { "delta": { "type": "string" }, "item_id": { "type": "string" }, "native_item_id": { "type": "string", "nullable": true } } }, "ItemEventData": { "type": "object", "required": [ "item" ], "properties": { "item": { "$ref": "#/components/schemas/UniversalItem" } } }, "ItemKind": { "type": "string", "enum": [ "message", "tool_call", "tool_result", "system", "status", "unknown" ] }, "ItemRole": { "type": "string", "enum": [ "user", "assistant", "system", "tool" ] }, "ItemStatus": { "type": "string", "enum": [ "in_progress", "completed", "failed" ] }, "MessageRequest": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "PermissionEventData": { "type": "object", "required": [ "permission_id", "action", "status" ], "properties": { "action": { "type": "string" }, "metadata": { "nullable": true }, "permission_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/PermissionStatus" } } }, "PermissionReply": { "type": "string", "enum": [ "once", "always", "reject" ] }, "PermissionReplyRequest": { "type": "object", "required": [ "reply" ], "properties": { "reply": { "$ref": "#/components/schemas/PermissionReply" } } }, "PermissionStatus": { "type": "string", "enum": [ "requested", "approved", "denied" ] }, "ProblemDetails": { "type": "object", "required": [ "type", "title", "status" ], "properties": { "detail": { "type": "string", "nullable": true }, "instance": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32", "minimum": 0 }, "title": { "type": "string" }, "type": { "type": "string" } }, "additionalProperties": {} }, "QuestionEventData": { "type": "object", "required": [ "question_id", "prompt", "options", "status" ], "properties": { "options": { "type": "array", "items": { "type": "string" } }, "prompt": { "type": "string" }, "question_id": { "type": "string" }, "response": { "type": "string", "nullable": true }, "status": { "$ref": "#/components/schemas/QuestionStatus" } } }, "QuestionReplyRequest": { "type": "object", "required": [ "answers" ], "properties": { "answers": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } } } }, "QuestionStatus": { "type": "string", "enum": [ "requested", "answered", "rejected" ] }, "ReasoningVisibility": { "type": "string", "enum": [ "public", "private" ] }, "ServerStatus": { "type": "string", "description": "Status of a shared server process for an agent", "enum": [ "running", "stopped", "error" ] }, "ServerStatusInfo": { "type": "object", "required": [ "status", "restartCount" ], "properties": { "baseUrl": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "restartCount": { "type": "integer", "format": "int64", "minimum": 0 }, "status": { "$ref": "#/components/schemas/ServerStatus" }, "uptimeMs": { "type": "integer", "format": "int64", "nullable": true, "minimum": 0 } } }, "SessionEndReason": { "type": "string", "enum": [ "completed", "error", "terminated" ] }, "SessionEndedData": { "type": "object", "required": [ "reason", "terminated_by" ], "properties": { "reason": { "$ref": "#/components/schemas/SessionEndReason" }, "terminated_by": { "$ref": "#/components/schemas/TerminatedBy" } } }, "SessionInfo": { "type": "object", "required": [ "sessionId", "agent", "agentMode", "permissionMode", "ended", "eventCount" ], "properties": { "agent": { "type": "string" }, "agentMode": { "type": "string" }, "ended": { "type": "boolean" }, "eventCount": { "type": "integer", "format": "int64", "minimum": 0 }, "model": { "type": "string", "nullable": true }, "nativeSessionId": { "type": "string", "nullable": true }, "permissionMode": { "type": "string" }, "sessionId": { "type": "string" }, "variant": { "type": "string", "nullable": true } } }, "SessionListResponse": { "type": "object", "required": [ "sessions" ], "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/SessionInfo" } } } }, "SessionStartedData": { "type": "object", "properties": { "metadata": { "nullable": true } } }, "TerminatedBy": { "type": "string", "enum": [ "agent", "daemon" ] }, "TurnStreamQuery": { "type": "object", "properties": { "includeRaw": { "type": "boolean", "nullable": true } } }, "UniversalEvent": { "type": "object", "required": [ "event_id", "sequence", "time", "session_id", "synthetic", "source", "type", "data" ], "properties": { "data": { "$ref": "#/components/schemas/UniversalEventData" }, "event_id": { "type": "string" }, "native_session_id": { "type": "string", "nullable": true }, "raw": { "nullable": true }, "sequence": { "type": "integer", "format": "int64", "minimum": 0 }, "session_id": { "type": "string" }, "source": { "$ref": "#/components/schemas/EventSource" }, "synthetic": { "type": "boolean" }, "time": { "type": "string" }, "type": { "$ref": "#/components/schemas/UniversalEventType" } } }, "UniversalEventData": { "oneOf": [ { "$ref": "#/components/schemas/SessionStartedData" }, { "$ref": "#/components/schemas/SessionEndedData" }, { "$ref": "#/components/schemas/ItemEventData" }, { "$ref": "#/components/schemas/ItemDeltaData" }, { "$ref": "#/components/schemas/ErrorData" }, { "$ref": "#/components/schemas/PermissionEventData" }, { "$ref": "#/components/schemas/QuestionEventData" }, { "$ref": "#/components/schemas/AgentUnparsedData" } ] }, "UniversalEventType": { "type": "string", "enum": [ "session.started", "session.ended", "item.started", "item.delta", "item.completed", "error", "permission.requested", "permission.resolved", "question.requested", "question.resolved", "agent.unparsed" ] }, "UniversalItem": { "type": "object", "required": [ "item_id", "kind", "content", "status" ], "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/ContentPart" } }, "item_id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/ItemKind" }, "native_item_id": { "type": "string", "nullable": true }, "parent_id": { "type": "string", "nullable": true }, "role": { "allOf": [ { "$ref": "#/components/schemas/ItemRole" } ], "nullable": true }, "status": { "$ref": "#/components/schemas/ItemStatus" } } } } }, "tags": [ { "name": "meta", "description": "Service metadata" }, { "name": "agents", "description": "Agent management" }, { "name": "sessions", "description": "Session management" } ] }