{ "openapi": "3.0.3", "info": { "title": "sandbox-agent", "description": "Universal API for automatic coding agents in sandboxes. Supports Claude Code, Codex, OpenCode, Cursor, Amp, and Pi.", "contact": { "name": "Rivet Gaming, LLC", "email": "developer@rivet.gg" }, "license": { "name": "Apache-2.0" }, "version": "0.2.0" }, "servers": [ { "url": "http://localhost:2468" } ], "paths": { "/v2/fs/file": { "get": { "tags": [ "v2" ], "operationId": "get_v2_fs_file", "parameters": [ { "name": "path", "in": "query", "description": "File path", "required": true, "schema": { "type": "string" } }, { "name": "session_id", "in": "query", "description": "Session id for relative path base", "required": false, "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "File content" } } }, "put": { "tags": [ "v2" ], "operationId": "put_v2_fs_file", "parameters": [ { "name": "path", "in": "query", "description": "File path", "required": true, "schema": { "type": "string" } }, { "name": "session_id", "in": "query", "description": "Session id for relative path base", "required": false, "schema": { "type": "string", "nullable": true } } ], "requestBody": { "description": "Raw file bytes", "content": { "text/plain": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Write result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FsWriteResponse" } } } } } } }, "/v2/fs/upload-batch": { "post": { "tags": [ "v2" ], "operationId": "post_v2_fs_upload_batch", "parameters": [ { "name": "path", "in": "query", "description": "Destination path", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "session_id", "in": "query", "description": "Session id for relative path base", "required": false, "schema": { "type": "string", "nullable": true } } ], "requestBody": { "description": "tar archive body", "content": { "text/plain": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Upload/extract result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FsUploadBatchResponse" } } } } } } }, "/v2/health": { "get": { "tags": [ "v2" ], "summary": "v2 Health", "description": "Returns server health for the v2 ACP surface.", "operationId": "get_v2_health", "responses": { "200": { "description": "Service health response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/v2/rpc": { "get": { "tags": [ "v2" ], "summary": "ACP SSE", "description": "Streams ACP JSON-RPC envelopes for an ACP client over SSE.", "operationId": "get_v2_acp", "responses": { "200": { "description": "SSE stream of ACP envelopes" }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Unknown ACP client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "406": { "description": "Client does not accept SSE responses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "409": { "description": "ACP client already has an active SSE stream", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "v2" ], "summary": "ACP POST", "description": "Sends ACP JSON-RPC envelopes to an ACP client and returns request responses.", "operationId": "post_v2_acp", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpEnvelope" } } }, "required": true }, "responses": { "200": { "description": "JSON-RPC response envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcpEnvelope" } } } }, "202": { "description": "JSON-RPC notification accepted" }, "400": { "description": "Invalid ACP envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Unknown ACP client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "406": { "description": "Client does not accept JSON responses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "415": { "description": "Unsupported media type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "504": { "description": "ACP agent process response timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": [ "v2" ], "summary": "ACP Close", "description": "Closes an ACP client and releases agent process resources.", "operationId": "delete_v2_acp", "responses": { "204": { "description": "ACP client closed" }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Unknown ACP client", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } } }, "components": { "schemas": { "AcpEnvelope": { "type": "object", "required": [ "jsonrpc" ], "properties": { "error": { "nullable": true }, "id": { "nullable": true }, "jsonrpc": { "type": "string" }, "method": { "type": "string", "nullable": true }, "params": { "nullable": true }, "result": { "nullable": true } } }, "AgentCapabilities": { "type": "object", "required": [ "planMode", "permissions", "questions", "toolCalls", "toolResults", "textMessages", "images", "fileAttachments", "sessionLifecycle", "errorEvents", "reasoning", "status", "commandExecution", "fileChanges", "mcpTools", "streamingDeltas", "itemStarted", "sharedProcess" ], "properties": { "commandExecution": { "type": "boolean" }, "errorEvents": { "type": "boolean" }, "fileAttachments": { "type": "boolean" }, "fileChanges": { "type": "boolean" }, "images": { "type": "boolean" }, "itemStarted": { "type": "boolean" }, "mcpTools": { "type": "boolean" }, "permissions": { "type": "boolean" }, "planMode": { "type": "boolean" }, "questions": { "type": "boolean" }, "reasoning": { "type": "boolean" }, "sessionLifecycle": { "type": "boolean" }, "sharedProcess": { "type": "boolean" }, "status": { "type": "boolean" }, "streamingDeltas": { "type": "boolean" }, "textMessages": { "type": "boolean" }, "toolCalls": { "type": "boolean" }, "toolResults": { "type": "boolean" } } }, "AgentInfo": { "type": "object", "required": [ "id", "installed", "credentialsAvailable", "capabilities" ], "properties": { "capabilities": { "$ref": "#/components/schemas/AgentCapabilities" }, "credentialsAvailable": { "type": "boolean" }, "defaultModel": { "type": "string", "nullable": true }, "id": { "type": "string" }, "installed": { "type": "boolean" }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/AgentModelInfo" }, "nullable": true }, "modes": { "type": "array", "items": { "$ref": "#/components/schemas/AgentModeInfo" }, "nullable": true }, "path": { "type": "string", "nullable": true }, "serverStatus": { "allOf": [ { "$ref": "#/components/schemas/ServerStatusInfo" } ], "nullable": true }, "version": { "type": "string", "nullable": true } } }, "AgentInstallArtifact": { "type": "object", "required": [ "kind", "path", "source" ], "properties": { "kind": { "type": "string" }, "path": { "type": "string" }, "source": { "type": "string" }, "version": { "type": "string", "nullable": true } } }, "AgentInstallRequest": { "type": "object", "properties": { "agentProcessVersion": { "type": "string", "nullable": true }, "agentVersion": { "type": "string", "nullable": true }, "reinstall": { "type": "boolean", "nullable": true } } }, "AgentInstallResponse": { "type": "object", "required": [ "already_installed", "artifacts" ], "properties": { "already_installed": { "type": "boolean" }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/AgentInstallArtifact" } } } }, "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" } } }, "AgentModelInfo": { "type": "object", "required": [ "id" ], "properties": { "defaultVariant": { "type": "string", "nullable": true }, "id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "variants": { "type": "array", "items": { "type": "string" }, "nullable": true } } }, "ErrorType": { "type": "string", "enum": [ "invalid_request", "conflict", "unsupported_agent", "agent_not_installed", "install_failed", "agent_process_exited", "token_invalid", "permission_denied", "not_acceptable", "unsupported_media_type", "session_not_found", "session_already_exists", "mode_not_supported", "stream_error", "timeout" ] }, "FsActionResponse": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" } } }, "FsDeleteQuery": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" }, "recursive": { "type": "boolean", "nullable": true }, "sessionId": { "type": "string", "nullable": true } } }, "FsEntriesQuery": { "type": "object", "properties": { "path": { "type": "string", "nullable": true }, "sessionId": { "type": "string", "nullable": true } } }, "FsEntry": { "type": "object", "required": [ "name", "path", "entryType", "size" ], "properties": { "entryType": { "$ref": "#/components/schemas/FsEntryType" }, "modified": { "type": "string", "nullable": true }, "name": { "type": "string" }, "path": { "type": "string" }, "size": { "type": "integer", "format": "int64", "minimum": 0 } } }, "FsEntryType": { "type": "string", "enum": [ "file", "directory" ] }, "FsMoveRequest": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string" }, "overwrite": { "type": "boolean", "nullable": true }, "to": { "type": "string" } } }, "FsMoveResponse": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string" }, "to": { "type": "string" } } }, "FsPathQuery": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" }, "sessionId": { "type": "string", "nullable": true } } }, "FsSessionQuery": { "type": "object", "properties": { "sessionId": { "type": "string", "nullable": true } } }, "FsStat": { "type": "object", "required": [ "path", "entryType", "size" ], "properties": { "entryType": { "$ref": "#/components/schemas/FsEntryType" }, "modified": { "type": "string", "nullable": true }, "path": { "type": "string" }, "size": { "type": "integer", "format": "int64", "minimum": 0 } } }, "FsUploadBatchQuery": { "type": "object", "properties": { "path": { "type": "string", "nullable": true }, "sessionId": { "type": "string", "nullable": true } } }, "FsUploadBatchResponse": { "type": "object", "required": [ "paths", "truncated" ], "properties": { "paths": { "type": "array", "items": { "type": "string" } }, "truncated": { "type": "boolean" } } }, "FsWriteResponse": { "type": "object", "required": [ "path", "bytesWritten" ], "properties": { "bytesWritten": { "type": "integer", "format": "int64", "minimum": 0 }, "path": { "type": "string" } } }, "HealthResponse": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } } }, "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": {} }, "ServerStatus": { "type": "string", "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 } } }, "SessionInfo": { "type": "object", "required": [ "sessionId", "agent", "agentMode", "permissionMode", "ended", "eventCount", "createdAt", "updatedAt" ], "properties": { "agent": { "type": "string" }, "agentMode": { "type": "string" }, "createdAt": { "type": "integer", "format": "int64" }, "directory": { "type": "string", "nullable": true }, "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" }, "terminationInfo": { "allOf": [ { "$ref": "#/components/schemas/TerminationInfo" } ], "nullable": true }, "title": { "type": "string", "nullable": true }, "updatedAt": { "type": "integer", "format": "int64" } } }, "SessionListResponse": { "type": "object", "required": [ "sessions" ], "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/SessionInfo" } } } }, "StderrOutput": { "type": "object", "required": [ "truncated" ], "properties": { "head": { "type": "string", "nullable": true }, "tail": { "type": "string", "nullable": true }, "totalLines": { "type": "integer", "nullable": true, "minimum": 0 }, "truncated": { "type": "boolean" } } }, "TerminationInfo": { "type": "object", "required": [ "reason", "terminatedBy" ], "properties": { "exitCode": { "type": "integer", "format": "int32", "nullable": true }, "message": { "type": "string", "nullable": true }, "reason": { "type": "string" }, "stderr": { "allOf": [ { "$ref": "#/components/schemas/StderrOutput" } ], "nullable": true }, "terminatedBy": { "type": "string" } } } } }, "tags": [ { "name": "v2", "description": "ACP-native v2 API" } ] }