{ "openapi": "3.0.3", "info": { "title": "Ash API", "description": "REST API for deploying and orchestrating hosted AI agents", "version": "0.1.0" }, "components": { "schemas": { "def-0": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "tenantId": { "type": "string" }, "version": { "type": "integer" }, "path": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "version", "path", "createdAt", "updatedAt" ], "title": "Agent" }, "def-1": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string" }, "agentName": { "type": "string" }, "sandboxId": { "type": "string" }, "status": { "type": "string", "enum": [ "starting", "active", "paused", "stopped", "ended", "error" ] }, "runnerId": { "type": [ "null", "string" ] }, "parentSessionId": { "type": [ "null", "string" ], "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "lastActiveAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "agentName", "sandboxId", "status", "createdAt", "lastActiveAt" ], "title": "Session" }, "def-2": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string", "description": "JSON-encoded message content (SDK passthrough)" }, "sequence": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "sessionId", "role", "content", "sequence", "createdAt" ], "title": "Message" }, "def-3": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sessionId": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "tool_start", "tool_result", "reasoning", "error", "turn_complete", "lifecycle" ] }, "data": { "type": [ "null", "string" ], "description": "JSON-encoded event payload" }, "sequence": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "sessionId", "type", "sequence", "createdAt" ], "title": "SessionEvent" }, "def-4": { "type": "object", "properties": { "error": { "type": "string" }, "statusCode": { "type": "integer" } }, "required": [ "error", "statusCode" ], "title": "ApiError" }, "def-5": { "type": "object", "properties": { "total": { "type": "integer" }, "cold": { "type": "integer" }, "warming": { "type": "integer" }, "warm": { "type": "integer" }, "waiting": { "type": "integer" }, "running": { "type": "integer" }, "maxCapacity": { "type": "integer" }, "resumeWarmHits": { "type": "integer" }, "resumeColdHits": { "type": "integer" }, "preWarmHits": { "type": "integer" } }, "required": [ "total", "cold", "warming", "warm", "waiting", "running", "maxCapacity", "resumeWarmHits", "resumeColdHits", "preWarmHits" ], "title": "PoolStats" }, "def-6": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "version": { "type": "string", "description": "Ash server version" }, "coordinatorId": { "type": "string", "description": "Unique coordinator ID (hostname-PID)" }, "activeSessions": { "type": "integer" }, "activeSandboxes": { "type": "integer" }, "remoteRunners": { "type": "integer", "description": "Number of registered remote runners" }, "uptime": { "type": "integer", "description": "Seconds since process start" }, "pool": { "$ref": "#/components/schemas/def-5" } }, "required": [ "status", "activeSessions", "activeSandboxes", "uptime", "pool" ], "title": "HealthResponse" }, "def-7": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string" }, "sessionId": { "type": [ "null", "string" ] }, "agentName": { "type": "string" }, "prompt": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "cancelled" ] }, "priority": { "type": "integer" }, "retryCount": { "type": "integer" }, "maxRetries": { "type": "integer" }, "error": { "type": [ "null", "string" ] }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": [ "null", "string" ] }, "completedAt": { "type": [ "null", "string" ] } }, "required": [ "id", "agentName", "prompt", "status", "priority", "retryCount", "maxRetries", "createdAt" ], "title": "QueueItem" }, "def-8": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string" }, "messageId": { "type": "string" }, "sessionId": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "mimeType": { "type": "string" }, "size": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "sessionId", "filename", "mimeType", "size", "createdAt" ], "title": "Attachment" }, "def-9": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string" }, "type": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "type", "createdAt" ], "title": "Credential" }, "def-10": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string" }, "sessionId": { "type": "string", "format": "uuid" }, "agentName": { "type": "string" }, "eventType": { "type": "string" }, "value": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "sessionId", "agentName", "eventType", "value", "createdAt" ], "title": "UsageEvent" }, "def-11": { "type": "object", "properties": { "totalInputTokens": { "type": "number" }, "totalOutputTokens": { "type": "number" }, "totalCacheCreationTokens": { "type": "number" }, "totalCacheReadTokens": { "type": "number" }, "totalToolCalls": { "type": "number" }, "totalMessages": { "type": "number" }, "totalComputeSeconds": { "type": "number" } }, "required": [ "totalInputTokens", "totalOutputTokens", "totalCacheCreationTokens", "totalCacheReadTokens", "totalToolCalls", "totalMessages", "totalComputeSeconds" ], "title": "UsageStats" } } }, "paths": { "/api/agents": { "post": { "tags": [ "agents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "path": { "type": "string" }, "systemPrompt": { "type": "string" }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": [ "path", "content" ] } } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "$ref": "#/components/schemas/def-0" } }, "required": [ "agent" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } }, "get": { "tags": [ "agents" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/def-0" } } }, "required": [ "agents" ] } } } } } } }, "/api/agents/{name}": { "get": { "tags": [ "agents" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "name", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "$ref": "#/components/schemas/def-0" } }, "required": [ "agent" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } }, "delete": { "tags": [ "agents" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "name", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } } }, "/api/agents/{name}/files": { "get": { "tags": [ "agents" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "name", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "size": { "type": "integer" }, "modifiedAt": { "type": "string", "format": "date-time" } }, "required": [ "path", "size", "modifiedAt" ] } } }, "required": [ "files" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } } }, "/api/agents/{name}/files/{*}": { "get": { "tags": [ "agents" ], "parameters": [ { "schema": { "type": "string", "enum": [ "json", "raw" ] }, "in": "query", "name": "format", "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "name", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "*", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/sessions": { "post": { "tags": [ "sessions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "type": "string" }, "credentialId": { "type": "string" }, "extraEnv": { "type": "object", "additionalProperties": { "type": "string" } }, "model": { "type": "string", "description": "Model override for this session. Overrides agent .claude/settings.json default." }, "mcpServers": { "type": "object", "description": "Per-session MCP servers. Merged into agent .mcp.json (session overrides agent). Enables sidecar pattern.", "additionalProperties": { "type": "object", "properties": { "url": { "type": "string" }, "command": { "type": "string" }, "args": { "type": "array", "items": { "type": "string" } }, "env": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "systemPrompt": { "type": "string", "description": "System prompt override. Replaces agent CLAUDE.md for this session." }, "permissionMode": { "type": "string", "enum": [ "bypassPermissions", "permissionsByAgent", "default" ], "description": "Permission mode for the SDK inside the sandbox. Defaults to bypassPermissions (sandbox isolation is the security boundary)." }, "allowedTools": { "type": "array", "items": { "type": "string" }, "description": "Whitelist of allowed tool names for this session." }, "disallowedTools": { "type": "array", "items": { "type": "string" }, "description": "Blacklist of disallowed tool names for this session." }, "betas": { "type": "array", "items": { "type": "string" }, "description": "Beta feature flags for this session." }, "subagents": { "type": "object", "additionalProperties": true, "description": "Programmatic subagent definitions. Passed through to the SDK as `agents`." }, "initialAgent": { "type": "string", "description": "Which subagent to use for the main thread. Maps to SDK `agent` option." } }, "required": [ "agent" ] } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/def-1" } }, "required": [ "session" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } }, "get": { "tags": [ "sessions" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "agent", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/def-1" } } }, "required": [ "sessions" ] } } } } } } }, "/api/sessions/{id}": { "get": { "tags": [ "sessions" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/def-1" } }, "required": [ "session" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } }, "delete": { "tags": [ "sessions" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/def-1" } }, "required": [ "session" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } } }, "/api/sessions/{id}/config": { "patch": { "tags": [ "sessions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "model": { "type": "string", "description": "Model override for subsequent queries." }, "allowedTools": { "type": "array", "items": { "type": "string" }, "description": "Whitelist of allowed tool names." }, "disallowedTools": { "type": "array", "items": { "type": "string" }, "description": "Blacklist of disallowed tool names." }, "betas": { "type": "array", "items": { "type": "string" }, "description": "Beta feature flags." }, "subagents": { "type": "object", "additionalProperties": true, "description": "Programmatic subagent definitions." }, "initialAgent": { "type": "string", "description": "Which subagent to use for the main thread." } } } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/def-1" } }, "required": [ "session" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } } }, "/api/sessions/{id}/messages": { "get": { "tags": [ "sessions" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "after", "required": false, "description": "Return messages after this sequence number" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/def-2" } } }, "required": [ "messages" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } }, "post": { "tags": [ "sessions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" }, "includePartialMessages": { "type": "boolean" }, "model": { "type": "string", "description": "Model override for this query. Overrides session and agent defaults." }, "maxTurns": { "type": "integer", "minimum": 1, "description": "Maximum agentic turns for this query." }, "maxBudgetUsd": { "type": "number", "minimum": 0, "description": "Maximum budget in USD for this query." }, "effort": { "type": "string", "enum": [ "low", "medium", "high", "max" ], "description": "Effort level for this query." }, "thinking": { "type": "object", "properties": { "type": { "type": "string" }, "budgetTokens": { "type": "integer" } }, "required": [ "type" ], "description": "Thinking configuration for this query." }, "outputFormat": { "type": "object", "properties": { "type": { "type": "string" }, "schema": { "type": "object", "additionalProperties": true } }, "required": [ "type", "schema" ], "description": "Output format constraint for this query." } }, "required": [ "content" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "SSE stream. Events: `message` (SDK Message JSON), `error` ({error: string}), `done` ({sessionId: string})", "content": { "application/json": { "schema": { "type": "string", "description": "SSE stream. Events: `message` (SDK Message JSON), `error` ({error: string}), `done` ({sessionId: string})" } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } } }, "/api/sessions/{id}/events": { "get": { "tags": [ "sessions" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 200 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "after", "required": false, "description": "Return events after this sequence number" }, { "schema": { "type": "string" }, "in": "query", "name": "type", "required": false, "description": "Filter by event type" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/def-3" } } }, "required": [ "events" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } } }, "/api/sessions/{id}/logs": { "get": { "tags": [ "sessions" ], "parameters": [ { "schema": { "type": "integer", "minimum": -1, "default": -1 }, "in": "query", "name": "after", "required": false, "description": "Return log entries with index > after" }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "logs": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "level": { "type": "string", "enum": [ "stdout", "stderr", "system" ] }, "text": { "type": "string" }, "ts": { "type": "string" } }, "required": [ "index", "level", "text", "ts" ] } }, "source": { "type": "string" } }, "required": [ "logs", "source" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } } }, "/api/sessions/{id}/exec": { "post": { "tags": [ "sessions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "command": { "type": "string" }, "timeout": { "type": "integer", "minimum": 1, "maximum": 300000 } }, "required": [ "command" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "exitCode": { "type": "integer" }, "stdout": { "type": "string" }, "stderr": { "type": "string" } }, "required": [ "exitCode", "stdout", "stderr" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } } }, "/api/sessions/{id}/pause": { "post": { "tags": [ "sessions" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/def-1" } }, "required": [ "session" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } } }, "/api/sessions/{id}/stop": { "post": { "tags": [ "sessions" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/def-1" } }, "required": [ "session" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } } }, "/api/sessions/{id}/fork": { "post": { "tags": [ "sessions" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/def-1" } }, "required": [ "session" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } } }, "/api/sessions/{id}/resume": { "post": { "tags": [ "sessions" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/def-1" } }, "required": [ "session" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "410": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } } }, "/api/sessions/{id}/files": { "get": { "tags": [ "sessions" ], "parameters": [ { "schema": { "type": "string", "enum": [ "true", "false" ] }, "in": "query", "name": "includeHidden", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "size": { "type": "integer" }, "modifiedAt": { "type": "string", "format": "date-time" } }, "required": [ "path", "size", "modifiedAt" ] } }, "source": { "type": "string", "enum": [ "sandbox", "snapshot" ] } }, "required": [ "files", "source" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } }, "post": { "tags": [ "sessions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" }, "mimeType": { "type": "string" } }, "required": [ "path", "content" ] }, "minItems": 1, "maxItems": 500 }, "targetPath": { "type": "string", "default": "." } }, "required": [ "files" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/sessions/{id}/files/{*}": { "get": { "tags": [ "sessions" ], "parameters": [ { "schema": { "type": "string", "enum": [ "json", "raw" ] }, "in": "query", "name": "format", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "*", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "tags": [ "sessions" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "*", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/api/credentials": { "post": { "tags": [ "credentials" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "anthropic", "openai", "custom" ] }, "key": { "type": "string", "minLength": 1 }, "label": { "type": "string" } }, "required": [ "type", "key" ] } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "credential": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" }, "active": { "type": "boolean" }, "createdAt": { "type": "string" } } } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } }, "get": { "tags": [ "credentials" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "credentials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "lastUsedAt": { "type": [ "null", "string" ] } } } } } } } } } } } }, "/api/credentials/{id}": { "delete": { "tags": [ "credentials" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "204": { "description": "Default Response" }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } } }, "/api/queue": { "post": { "tags": [ "queue" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agentName": { "type": "string" }, "prompt": { "type": "string", "minLength": 1 }, "sessionId": { "type": "string", "format": "uuid" }, "priority": { "type": "integer", "minimum": 0, "default": 0 }, "maxRetries": { "type": "integer", "minimum": 0, "default": 3 } }, "required": [ "agentName", "prompt" ] } } } }, "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/def-7" } }, "required": [ "item" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } }, "get": { "tags": [ "queue" ], "parameters": [ { "schema": { "type": "string", "enum": [ "pending", "processing", "completed", "failed", "cancelled" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 }, "in": "query", "name": "limit", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/def-7" } } }, "required": [ "items" ] } } } } } } }, "/api/queue/stats": { "get": { "tags": [ "queue" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "type": "object", "properties": { "pending": { "type": "integer" }, "processing": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" }, "cancelled": { "type": "integer" } }, "required": [ "pending", "processing", "completed", "failed", "cancelled" ] } }, "required": [ "stats" ] } } } } } } }, "/api/queue/{id}": { "get": { "tags": [ "queue" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/def-7" } }, "required": [ "item" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } }, "delete": { "tags": [ "queue" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/def-7" } }, "required": [ "item" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } } }, "/api/sessions/{id}/attachments": { "post": { "tags": [ "sessions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1 }, "mimeType": { "type": "string", "default": "application/octet-stream" }, "content": { "type": "string", "description": "Base64-encoded file content" }, "messageId": { "type": "string", "format": "uuid", "description": "Message to attach to (optional — can be linked later)" } }, "required": [ "filename", "content" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "attachment": { "$ref": "#/components/schemas/def-8" } }, "required": [ "attachment" ] } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "413": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } }, "get": { "tags": [ "sessions" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/def-8" } } }, "required": [ "attachments" ] } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } } }, "/api/attachments/{id}": { "get": { "tags": [ "attachments" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } }, "delete": { "tags": [ "attachments" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "204": { "description": "Default Response" }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } } }, "/api/usage": { "get": { "tags": [ "usage" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "sessionId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "agentName", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "after", "required": false, "description": "Only events after this ISO timestamp" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "before", "required": false, "description": "Only events before this ISO timestamp" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }, "in": "query", "name": "limit", "required": false } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/def-10" } } }, "required": [ "events" ] } } } } } } }, "/api/usage/stats": { "get": { "tags": [ "usage" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "sessionId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "agentName", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "after", "required": false, "description": "Only events after this ISO timestamp" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "before", "required": false, "description": "Only events before this ISO timestamp" } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "stats": { "$ref": "#/components/schemas/def-11" } }, "required": [ "stats" ] } } } } } } }, "/api/sessions/{id}/workspace": { "get": { "tags": [ "sessions" ], "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } }, "post": { "tags": [ "sessions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bundle": { "type": "string", "description": "Base64-encoded tar.gz bundle" } }, "required": [ "bundle" ] } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-4" } } } } } } }, "/health": { "get": { "tags": [ "health" ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/def-6" } } } } } } }, "/api/internal/runners/register": { "post": { "responses": { "200": { "description": "Default Response" } } } }, "/api/internal/runners/heartbeat": { "post": { "responses": { "200": { "description": "Default Response" } } } }, "/api/internal/runners/deregister": { "post": { "responses": { "200": { "description": "Default Response" } } } }, "/api/internal/runners": { "get": { "responses": { "200": { "description": "Default Response" } } } } }, "servers": [ { "url": "http://localhost:4100" } ], "tags": [ { "name": "health", "description": "Server health" }, { "name": "agents", "description": "Agent deployment and management" }, { "name": "sessions", "description": "Session lifecycle and messaging" }, { "name": "files", "description": "Sandbox file access" }, { "name": "credentials", "description": "Credential storage and management" }, { "name": "attachments", "description": "File attachments for sessions" }, { "name": "queue", "description": "Async message queue" }, { "name": "usage", "description": "Usage tracking and analytics" }, { "name": "workspace", "description": "Workspace bundle download/upload" }, { "name": "runners", "description": "Internal runner management" } ] }