sandbox-agent/docs/openapi.json
2026-02-11 14:47:41 +00:00

1089 lines
No EOL
25 KiB
JSON

{
"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"
}
]
}