{ "openapi": "3.1.0", "info": { "title": "Sparkles Sandbox API", "version": "1.0.0", "description": "Create coding sandboxes, stream their work, and control their lifecycle." }, "servers": [ { "url": "https://sparkles.dev" } ], "paths": { "/api/public/v1/sandboxes": { "get": { "operationId": "listSandboxes", "tags": [ "sandboxes" ], "summary": "List sandboxes created by this API access grant", "security": [ { "apiKey": [] } ], "parameters": [ { "in": "query", "name": "after", "schema": { "type": "string", "minLength": 1, "maxLength": 1000 } }, { "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "queued", "creating", "running", "succeeded", "failed", "terminating", "terminated" ] } }, { "in": "query", "name": "repo", "schema": { "type": "string", "maxLength": 201, "pattern": "^[A-Za-z0-9._-]+\\/[A-Za-z0-9._-]+$" } } ], "responses": { "200": { "description": "Grant-scoped sandboxes in newest-first order", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^c_[a-z2-9]{12}$" }, "worktreeId": { "readOnly": true, "type": "string", "minLength": 1 }, "object": { "type": "string", "const": "sandbox" }, "status": { "type": "string", "enum": [ "queued", "creating", "running", "succeeded", "failed", "terminating", "terminated" ] }, "title": { "type": "string" }, "repos": { "type": "array", "items": { "type": "object", "properties": { "fullName": { "type": "string", "maxLength": 201, "pattern": "^[A-Za-z0-9._-]+\\/[A-Za-z0-9._-]+$" }, "ref": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "fullName" ], "additionalProperties": false } }, "model": { "type": [ "string", "null" ] }, "agentRuntime": { "type": "string", "enum": [ "opencode", "codex", "claude", "grok" ] }, "turn": { "type": "object", "properties": { "active": { "type": "boolean" } }, "required": [ "active" ], "additionalProperties": false }, "usage": { "type": "object", "properties": { "llmRequestCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "costMicroUsd": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "creditsChargedMicros": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "llmRequestCount", "costMicroUsd", "creditsChargedMicros" ], "additionalProperties": false }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "startedAt": { "type": [ "string", "null" ] }, "completedAt": { "type": [ "string", "null" ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "format": "uri" }, "events": { "type": "string", "format": "uri" }, "messages": { "type": "string", "format": "uri" } }, "required": [ "self", "events", "messages" ], "additionalProperties": false } }, "required": [ "id", "worktreeId", "object", "status", "title", "repos", "model", "agentRuntime", "turn", "usage", "metadata", "error", "createdAt", "startedAt", "completedAt", "links" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "List filters or cursor failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing, malformed, revoked, or otherwise invalid API key", "headers": { "WWW-Authenticate": { "required": true, "description": "Bearer authentication challenge for the Sparkles Sandbox API", "schema": { "type": "string", "description": "Bearer authentication challenge for the Sparkles Sandbox API" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "The API key lacks the sandboxes scope or its user is no longer an active organization member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "The API key exceeded its distributed per-minute request limit", "headers": { "Retry-After": { "required": true, "description": "Seconds until another request may be made", "schema": { "type": "string", "pattern": "^\\d+$", "description": "Seconds until another request may be made" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "The request could not be completed because of an internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "post": { "operationId": "createSandbox", "tags": [ "sandboxes" ], "summary": "Create a sandbox", "description": "Creates an asynchronously booting sandbox. An identical Idempotency-Key retry returns the same sandbox; changed request fields return 409.", "security": [ { "apiKey": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "repos": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "fullName": { "type": "string", "maxLength": 201, "pattern": "^[A-Za-z0-9._-]+\\/[A-Za-z0-9._-]+$" }, "ref": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "fullName" ], "additionalProperties": false } }, "prompt": { "type": "string", "minLength": 1, "maxLength": 60000 }, "model": { "type": "string", "minLength": 1, "maxLength": 200 }, "reasoningEffort": { "type": "string", "enum": [ "none", "low", "medium", "high", "xhigh", "max", "ultra", "ultracode" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "toolApprovalMode": { "default": "auto", "type": "string", "enum": [ "auto", "prompt" ] }, "metadata": { "default": {}, "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 64 }, "additionalProperties": { "type": "string", "maxLength": 1000 } } }, "required": [ "repos", "prompt" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "An identical sandbox creation was already accepted", "headers": { "Location": { "required": true, "schema": { "type": "string", "format": "uri" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^c_[a-z2-9]{12}$" }, "worktreeId": { "readOnly": true, "type": "string", "minLength": 1 }, "object": { "type": "string", "const": "sandbox" }, "status": { "type": "string", "enum": [ "queued", "creating", "running", "succeeded", "failed", "terminating", "terminated" ] }, "title": { "type": "string" }, "repos": { "type": "array", "items": { "type": "object", "properties": { "fullName": { "type": "string", "maxLength": 201, "pattern": "^[A-Za-z0-9._-]+\\/[A-Za-z0-9._-]+$" }, "ref": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "fullName" ], "additionalProperties": false } }, "model": { "type": [ "string", "null" ] }, "agentRuntime": { "type": "string", "enum": [ "opencode", "codex", "claude", "grok" ] }, "turn": { "type": "object", "properties": { "active": { "type": "boolean" } }, "required": [ "active" ], "additionalProperties": false }, "usage": { "type": "object", "properties": { "llmRequestCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "costMicroUsd": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "creditsChargedMicros": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "llmRequestCount", "costMicroUsd", "creditsChargedMicros" ], "additionalProperties": false }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "startedAt": { "type": [ "string", "null" ] }, "completedAt": { "type": [ "string", "null" ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "format": "uri" }, "events": { "type": "string", "format": "uri" }, "messages": { "type": "string", "format": "uri" } }, "required": [ "self", "events", "messages" ], "additionalProperties": false } }, "required": [ "id", "worktreeId", "object", "status", "title", "repos", "model", "agentRuntime", "turn", "usage", "metadata", "error", "createdAt", "startedAt", "completedAt", "links" ], "additionalProperties": false } } } }, "201": { "description": "Sandbox creation accepted", "headers": { "Location": { "required": true, "schema": { "type": "string", "format": "uri" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^c_[a-z2-9]{12}$" }, "worktreeId": { "readOnly": true, "type": "string", "minLength": 1 }, "object": { "type": "string", "const": "sandbox" }, "status": { "type": "string", "enum": [ "queued", "creating", "running", "succeeded", "failed", "terminating", "terminated" ] }, "title": { "type": "string" }, "repos": { "type": "array", "items": { "type": "object", "properties": { "fullName": { "type": "string", "maxLength": 201, "pattern": "^[A-Za-z0-9._-]+\\/[A-Za-z0-9._-]+$" }, "ref": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "fullName" ], "additionalProperties": false } }, "model": { "type": [ "string", "null" ] }, "agentRuntime": { "type": "string", "enum": [ "opencode", "codex", "claude", "grok" ] }, "turn": { "type": "object", "properties": { "active": { "type": "boolean" } }, "required": [ "active" ], "additionalProperties": false }, "usage": { "type": "object", "properties": { "llmRequestCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "costMicroUsd": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "creditsChargedMicros": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "llmRequestCount", "costMicroUsd", "creditsChargedMicros" ], "additionalProperties": false }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "startedAt": { "type": [ "string", "null" ] }, "completedAt": { "type": [ "string", "null" ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "format": "uri" }, "events": { "type": "string", "format": "uri" }, "messages": { "type": "string", "format": "uri" } }, "required": [ "self", "events", "messages" ], "additionalProperties": false } }, "required": [ "id", "worktreeId", "object", "status", "title", "repos", "model", "agentRuntime", "turn", "usage", "metadata", "error", "createdAt", "startedAt", "completedAt", "links" ], "additionalProperties": false } } } }, "400": { "description": "The request body or Idempotency-Key failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing, malformed, revoked, or otherwise invalid API key", "headers": { "WWW-Authenticate": { "required": true, "description": "Bearer authentication challenge for the Sparkles Sandbox API", "schema": { "type": "string", "description": "Bearer authentication challenge for the Sparkles Sandbox API" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "The organization has no credits remaining", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "The API key lacks the sandboxes scope or its user is no longer an active organization member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Idempotency or sandbox concurrency conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeded 64 KiB", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "415": { "description": "Content-Type was not application/json", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "The API key exceeded its distributed per-minute request limit", "headers": { "Retry-After": { "required": true, "description": "Seconds until another request may be made", "schema": { "type": "string", "pattern": "^\\d+$", "description": "Seconds until another request may be made" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "The request could not be completed because of an internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "502": { "description": "The sandbox command runtime is unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/public/v1/sandboxes/{sandboxId}": { "get": { "operationId": "getSandbox", "tags": [ "sandboxes" ], "summary": "Get the current sandbox state", "security": [ { "apiKey": [] } ], "parameters": [ { "in": "path", "name": "sandboxId", "schema": { "type": "string", "pattern": "^c_[a-z2-9]{12}$" }, "required": true } ], "responses": { "200": { "description": "Current sandbox state and eventually consistent usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^c_[a-z2-9]{12}$" }, "worktreeId": { "readOnly": true, "type": "string", "minLength": 1 }, "object": { "type": "string", "const": "sandbox" }, "status": { "type": "string", "enum": [ "queued", "creating", "running", "succeeded", "failed", "terminating", "terminated" ] }, "title": { "type": "string" }, "repos": { "type": "array", "items": { "type": "object", "properties": { "fullName": { "type": "string", "maxLength": 201, "pattern": "^[A-Za-z0-9._-]+\\/[A-Za-z0-9._-]+$" }, "ref": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "fullName" ], "additionalProperties": false } }, "model": { "type": [ "string", "null" ] }, "agentRuntime": { "type": "string", "enum": [ "opencode", "codex", "claude", "grok" ] }, "turn": { "type": "object", "properties": { "active": { "type": "boolean" } }, "required": [ "active" ], "additionalProperties": false }, "usage": { "type": "object", "properties": { "llmRequestCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "costMicroUsd": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "creditsChargedMicros": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "llmRequestCount", "costMicroUsd", "creditsChargedMicros" ], "additionalProperties": false }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "startedAt": { "type": [ "string", "null" ] }, "completedAt": { "type": [ "string", "null" ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "format": "uri" }, "events": { "type": "string", "format": "uri" }, "messages": { "type": "string", "format": "uri" } }, "required": [ "self", "events", "messages" ], "additionalProperties": false } }, "required": [ "id", "worktreeId", "object", "status", "title", "repos", "model", "agentRuntime", "turn", "usage", "metadata", "error", "createdAt", "startedAt", "completedAt", "links" ], "additionalProperties": false } } } }, "401": { "description": "Missing, malformed, revoked, or otherwise invalid API key", "headers": { "WWW-Authenticate": { "required": true, "description": "Bearer authentication challenge for the Sparkles Sandbox API", "schema": { "type": "string", "description": "Bearer authentication challenge for the Sparkles Sandbox API" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "The API key lacks the sandboxes scope or its user is no longer an active organization member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Sandbox not found for this API access grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "The API key exceeded its distributed per-minute request limit", "headers": { "Retry-After": { "required": true, "description": "Seconds until another request may be made", "schema": { "type": "string", "pattern": "^\\d+$", "description": "Seconds until another request may be made" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "The request could not be completed because of an internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/public/v1/sandboxes/{sandboxId}/messages": { "post": { "operationId": "sendSandboxMessage", "tags": [ "sandboxes" ], "summary": "Send a follow-up message", "description": "A terminal cloud sandbox automatically restarts when its concurrency slot is available.", "security": [ { "apiKey": [] } ], "parameters": [ { "in": "path", "name": "sandboxId", "schema": { "type": "string", "pattern": "^c_[a-z2-9]{12}$" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 1, "maxLength": 60000 }, "promptId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "prompt" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The durable command was accepted or deduplicated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunCommandReceipt" } } } }, "400": { "description": "The command payload failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing, malformed, revoked, or otherwise invalid API key", "headers": { "WWW-Authenticate": { "required": true, "description": "Bearer authentication challenge for the Sparkles Sandbox API", "schema": { "type": "string", "description": "Bearer authentication challenge for the Sparkles Sandbox API" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "The organization has no credits remaining for an automatic restart", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "The API key lacks the sandboxes scope or its user is no longer an active organization member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Sandbox not found for this API access grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "The command conflicts with the current sandbox state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeded 64 KiB", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "415": { "description": "Content-Type was not application/json", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "The API key exceeded its distributed per-minute request limit", "headers": { "Retry-After": { "required": true, "description": "Seconds until another request may be made", "schema": { "type": "string", "pattern": "^\\d+$", "description": "Seconds until another request may be made" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "The request could not be completed because of an internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "502": { "description": "The sandbox command runtime is unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/public/v1/sandboxes/{sandboxId}/interrupt": { "post": { "operationId": "interruptSandbox", "tags": [ "sandboxes" ], "summary": "Interrupt the active sandbox turn", "security": [ { "apiKey": [] } ], "parameters": [ { "in": "path", "name": "sandboxId", "schema": { "type": "string", "pattern": "^c_[a-z2-9]{12}$" }, "required": true } ], "responses": { "200": { "description": "The durable command was accepted or deduplicated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunCommandReceipt" } } } }, "400": { "description": "The command payload failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing, malformed, revoked, or otherwise invalid API key", "headers": { "WWW-Authenticate": { "required": true, "description": "Bearer authentication challenge for the Sparkles Sandbox API", "schema": { "type": "string", "description": "Bearer authentication challenge for the Sparkles Sandbox API" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "The API key lacks the sandboxes scope or its user is no longer an active organization member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Sandbox not found for this API access grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "The command conflicts with the current sandbox state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeded 64 KiB", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "415": { "description": "Content-Type was not application/json", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "The API key exceeded its distributed per-minute request limit", "headers": { "Retry-After": { "required": true, "description": "Seconds until another request may be made", "schema": { "type": "string", "pattern": "^\\d+$", "description": "Seconds until another request may be made" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "The request could not be completed because of an internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "502": { "description": "The sandbox command runtime is unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/public/v1/sandboxes/{sandboxId}/approvals/{approvalId}": { "post": { "operationId": "resolveSandboxApproval", "tags": [ "sandboxes" ], "summary": "Approve or deny a pending tool call", "security": [ { "apiKey": [] } ], "parameters": [ { "in": "path", "name": "sandboxId", "schema": { "type": "string", "pattern": "^c_[a-z2-9]{12}$" }, "required": true }, { "in": "path", "name": "approvalId", "schema": { "type": "string", "minLength": 1, "maxLength": 300 }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approve", "deny" ] } }, "required": [ "decision" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The durable command was accepted or deduplicated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunCommandReceipt" } } } }, "400": { "description": "The command payload failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing, malformed, revoked, or otherwise invalid API key", "headers": { "WWW-Authenticate": { "required": true, "description": "Bearer authentication challenge for the Sparkles Sandbox API", "schema": { "type": "string", "description": "Bearer authentication challenge for the Sparkles Sandbox API" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "The API key lacks the sandboxes scope or its user is no longer an active organization member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Sandbox not found for this API access grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "The command conflicts with the current sandbox state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeded 64 KiB", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "415": { "description": "Content-Type was not application/json", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "The API key exceeded its distributed per-minute request limit", "headers": { "Retry-After": { "required": true, "description": "Seconds until another request may be made", "schema": { "type": "string", "pattern": "^\\d+$", "description": "Seconds until another request may be made" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "The request could not be completed because of an internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "502": { "description": "The sandbox command runtime is unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/public/v1/sandboxes/{sandboxId}/terminate": { "post": { "operationId": "terminateSandbox", "tags": [ "sandboxes" ], "summary": "Terminate a sandbox", "description": "Termination is idempotent. Destructive purge controls are not exposed.", "security": [ { "apiKey": [] } ], "parameters": [ { "in": "path", "name": "sandboxId", "schema": { "type": "string", "pattern": "^c_[a-z2-9]{12}$" }, "required": true } ], "responses": { "200": { "description": "The durable command was accepted or deduplicated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunCommandReceipt" } } } }, "400": { "description": "The command payload failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing, malformed, revoked, or otherwise invalid API key", "headers": { "WWW-Authenticate": { "required": true, "description": "Bearer authentication challenge for the Sparkles Sandbox API", "schema": { "type": "string", "description": "Bearer authentication challenge for the Sparkles Sandbox API" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "The API key lacks the sandboxes scope or its user is no longer an active organization member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Sandbox not found for this API access grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "The command conflicts with the current sandbox state", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeded 64 KiB", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "415": { "description": "Content-Type was not application/json", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "The API key exceeded its distributed per-minute request limit", "headers": { "Retry-After": { "required": true, "description": "Seconds until another request may be made", "schema": { "type": "string", "pattern": "^\\d+$", "description": "Seconds until another request may be made" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "The request could not be completed because of an internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "502": { "description": "The sandbox command runtime is unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/public/v1/sandboxes/{sandboxId}/events": { "get": { "operationId": "listSandboxEvents", "tags": [ "sandbox events" ], "summary": "List replayable sandbox events", "description": "Returns curated durable conversation events after the supplied sequence cursor. Use this endpoint to recover gaps before resuming the live stream.", "security": [ { "apiKey": [] } ], "parameters": [ { "in": "path", "name": "sandboxId", "schema": { "type": "string", "pattern": "^c_[a-z2-9]{12}$" }, "required": true }, { "in": "query", "name": "after", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "in": "query", "name": "limit", "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Sandbox events after the supplied cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "object": { "type": "string", "const": "sandbox.event" }, "version": { "type": "string", "const": "v1" }, "ts": { "type": "string" }, "sandbox_id": { "type": "string" }, "turn_id": { "type": "string" }, "type": { "type": "string", "const": "snapshot" }, "data": { "type": "object", "properties": { "sandbox": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^c_[a-z2-9]{12}$" }, "worktreeId": { "readOnly": true, "type": "string", "minLength": 1 }, "object": { "type": "string", "const": "sandbox" }, "status": { "type": "string", "enum": [ "queued", "creating", "running", "succeeded", "failed", "terminating", "terminated" ] }, "title": { "type": "string" }, "repos": { "type": "array", "items": { "type": "object", "properties": { "fullName": { "type": "string", "maxLength": 201, "pattern": "^[A-Za-z0-9._-]+\\/[A-Za-z0-9._-]+$" }, "ref": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "fullName" ], "additionalProperties": false } }, "model": { "type": [ "string", "null" ] }, "agentRuntime": { "type": "string", "enum": [ "opencode", "codex", "claude", "grok" ] }, "turn": { "type": "object", "properties": { "active": { "type": "boolean" } }, "required": [ "active" ], "additionalProperties": false }, "usage": { "type": "object", "properties": { "llmRequestCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "costMicroUsd": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "creditsChargedMicros": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "llmRequestCount", "costMicroUsd", "creditsChargedMicros" ], "additionalProperties": false }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "startedAt": { "type": [ "string", "null" ] }, "completedAt": { "type": [ "string", "null" ] }, "links": { "type": "object", "properties": { "self": { "type": "string", "format": "uri" }, "events": { "type": "string", "format": "uri" }, "messages": { "type": "string", "format": "uri" } }, "required": [ "self", "events", "messages" ], "additionalProperties": false } }, "required": [ "id", "worktreeId", "object", "status", "title", "repos", "model", "agentRuntime", "turn", "usage", "metadata", "error", "createdAt", "startedAt", "completedAt", "links" ], "additionalProperties": false }, "turn": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "running", "succeeded", "failed", "canceled" ] } }, "required": [ "id", "state" ], "additionalProperties": false }, { "type": "null" } ] }, "resume_cursor": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "sandbox", "turn", "resume_cursor" ], "additionalProperties": false } }, "required": [ "object", "version", "ts", "sandbox_id", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "object": { "type": "string", "const": "sandbox.event" }, "version": { "type": "string", "const": "v1" }, "ts": { "type": "string" }, "sandbox_id": { "type": "string" }, "turn_id": { "type": "string" }, "type": { "type": "string", "const": "sandbox.status" }, "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "queued", "creating", "running", "succeeded", "failed", "terminating", "terminated" ] } }, "required": [ "status" ], "additionalProperties": false } }, "required": [ "object", "version", "ts", "sandbox_id", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^\\d+$" }, "object": { "type": "string", "const": "sandbox.event" }, "version": { "type": "string", "const": "v1" }, "ts": { "type": "string" }, "sandbox_id": { "type": "string" }, "turn_id": { "type": "string" }, "type": { "type": "string", "const": "turn.started" }, "data": { "type": "object", "properties": { "prompt_id": { "type": "string" }, "text": { "type": "string" }, "files": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string" }, "mime": { "type": "string" } }, "additionalProperties": false } }, "author": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false } }, "required": [ "prompt_id", "text", "files" ], "additionalProperties": false } }, "required": [ "id", "object", "version", "ts", "sandbox_id", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^\\d+$" }, "object": { "type": "string", "const": "sandbox.event" }, "version": { "type": "string", "const": "v1" }, "ts": { "type": "string" }, "sandbox_id": { "type": "string" }, "turn_id": { "type": "string" }, "type": { "type": "string", "const": "turn.completed" }, "data": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "succeeded", "failed", "canceled" ] }, "error": { "type": "string" } }, "required": [ "state" ], "additionalProperties": false } }, "required": [ "id", "object", "version", "ts", "sandbox_id", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^\\d+$" }, "object": { "type": "string", "const": "sandbox.event" }, "version": { "type": "string", "const": "v1" }, "ts": { "type": "string" }, "sandbox_id": { "type": "string" }, "turn_id": { "type": "string" }, "type": { "type": "string", "const": "message.updated" }, "data": { "type": "object", "properties": { "part_id": { "type": "string" }, "message_id": { "type": "string" }, "kind": { "type": "string", "enum": [ "text", "reasoning" ] }, "text": { "type": "string" } }, "required": [ "part_id", "message_id", "kind", "text" ], "additionalProperties": false } }, "required": [ "id", "object", "version", "ts", "sandbox_id", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^\\d+$" }, "object": { "type": "string", "const": "sandbox.event" }, "version": { "type": "string", "const": "v1" }, "ts": { "type": "string" }, "sandbox_id": { "type": "string" }, "turn_id": { "type": "string" }, "type": { "type": "string", "const": "message.completed" }, "data": { "type": "object", "properties": { "message_id": { "type": "string" }, "finish": { "type": "string" }, "error": { "type": "string" } }, "required": [ "message_id" ], "additionalProperties": false } }, "required": [ "id", "object", "version", "ts", "sandbox_id", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^\\d+$" }, "object": { "type": "string", "const": "sandbox.event" }, "version": { "type": "string", "const": "v1" }, "ts": { "type": "string" }, "sandbox_id": { "type": "string" }, "turn_id": { "type": "string" }, "type": { "type": "string", "const": "tool.updated" }, "data": { "type": "object", "properties": { "part_id": { "type": "string" }, "message_id": { "type": "string" }, "call_id": { "type": "string" }, "tool": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "error", "stopped" ] }, "error": { "type": "string" } }, "required": [ "part_id", "message_id", "call_id", "tool", "status" ], "additionalProperties": false } }, "required": [ "id", "object", "version", "ts", "sandbox_id", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^\\d+$" }, "object": { "type": "string", "const": "sandbox.event" }, "version": { "type": "string", "const": "v1" }, "ts": { "type": "string" }, "sandbox_id": { "type": "string" }, "turn_id": { "type": "string" }, "type": { "type": "string", "const": "approval.requested" }, "data": { "type": "object", "properties": { "approval_id": { "type": "string" }, "tool": { "type": "string" } }, "required": [ "approval_id", "tool" ], "additionalProperties": false } }, "required": [ "id", "object", "version", "ts", "sandbox_id", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^\\d+$" }, "object": { "type": "string", "const": "sandbox.event" }, "version": { "type": "string", "const": "v1" }, "ts": { "type": "string" }, "sandbox_id": { "type": "string" }, "turn_id": { "type": "string" }, "type": { "type": "string", "const": "approval.resolved" }, "data": { "type": "object", "properties": { "approval_id": { "type": "string" }, "outcome": { "type": "string", "enum": [ "approved", "denied", "canceled", "failed" ] } }, "required": [ "approval_id", "outcome" ], "additionalProperties": false } }, "required": [ "id", "object", "version", "ts", "sandbox_id", "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^\\d+$" }, "object": { "type": "string", "const": "sandbox.event" }, "version": { "type": "string", "const": "v1" }, "ts": { "type": "string" }, "sandbox_id": { "type": "string" }, "turn_id": { "type": "string" }, "type": { "type": "string", "const": "sandbox.error" }, "data": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false } }, "required": [ "id", "object", "version", "ts", "sandbox_id", "type", "data" ], "additionalProperties": false } ], "type": "object" } }, "nextCursor": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "The event cursor or limit failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing, malformed, revoked, or otherwise invalid API key", "headers": { "WWW-Authenticate": { "required": true, "description": "Bearer authentication challenge for the Sparkles Sandbox API", "schema": { "type": "string", "description": "Bearer authentication challenge for the Sparkles Sandbox API" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "The API key lacks the sandboxes scope or its user is no longer an active organization member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Sandbox not found for this API access grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "The API key exceeded its distributed per-minute request limit", "headers": { "Retry-After": { "required": true, "description": "Seconds until another request may be made", "schema": { "type": "string", "pattern": "^\\d+$", "description": "Seconds until another request may be made" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "The request could not be completed because of an internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/public/v1/sandboxes/{sandboxId}/events/stream": { "get": { "operationId": "streamSandboxEvents", "tags": [ "sandbox events" ], "summary": "Stream sandbox events", "description": "Opens a fetch-based Server-Sent Events stream across sandbox boot, turns, and completion. Durable frames carry an event id; reconnect with Last-Event-ID or since. Fresh connections receive a transient snapshot before the live tail.", "security": [ { "apiKey": [] } ], "parameters": [ { "in": "path", "name": "sandboxId", "schema": { "type": "string", "pattern": "^c_[a-z2-9]{12}$" }, "required": true }, { "in": "query", "name": "since", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "in": "header", "name": "Last-Event-ID", "schema": { "type": "string", "pattern": "^\\d+$" } } ], "responses": { "200": { "description": "A Server-Sent Events stream of curated sandbox event envelopes", "content": { "text/event-stream": { "schema": { "type": "string", "description": "SSE frames whose data field is a JSON sandbox.event envelope" } } } }, "400": { "description": "The Last-Event-ID or since cursor failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing, malformed, revoked, or otherwise invalid API key", "headers": { "WWW-Authenticate": { "required": true, "description": "Bearer authentication challenge for the Sparkles Sandbox API", "schema": { "type": "string", "description": "Bearer authentication challenge for the Sparkles Sandbox API" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "The API key lacks the sandboxes scope or its user is no longer an active organization member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Sandbox not found for this API access grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "The API key exceeded its distributed per-minute request limit", "headers": { "Retry-After": { "required": true, "description": "Seconds until another request may be made", "schema": { "type": "string", "pattern": "^\\d+$", "description": "Seconds until another request may be made" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "The request could not be completed because of an internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/public/v1/sandboxes/{sandboxId}/files/tree": { "get": { "operationId": "listSandboxFiles", "tags": [ "sandbox files" ], "summary": "List files in a sandbox repository", "description": "Returns the immediate read-only repository tree. Select repo when the sandbox contains more than one repository.", "security": [ { "apiKey": [] } ], "parameters": [ { "in": "path", "name": "sandboxId", "schema": { "type": "string", "pattern": "^c_[a-z2-9]{12}$" }, "required": true }, { "in": "query", "name": "directory", "schema": { "default": "", "type": "string", "maxLength": 1000 } }, { "in": "query", "name": "repo", "schema": { "type": "string", "maxLength": 201, "pattern": "^[A-Za-z0-9._-]+\\/[A-Za-z0-9._-]+$" } } ], "responses": { "200": { "description": "The requested repository directory", "content": { "application/json": { "schema": { "type": "object", "properties": { "directory": { "type": "string" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "additions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "deletions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "depth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "kind": { "type": "string", "enum": [ "directory", "file" ] }, "mtimeMs": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "name": { "type": "string" }, "path": { "type": "string" }, "previousPath": { "type": [ "string", "null" ] }, "size": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "added", "deleted", "modified", "renamed", "untracked" ] }, { "type": "null" } ] } }, "required": [ "additions", "deletions", "kind", "name", "path", "previousPath", "status" ], "additionalProperties": false } }, "partialWarnings": { "type": "array", "items": { "type": "string" } }, "scope": { "type": "string", "const": "all" } }, "required": [ "directory", "entries", "partialWarnings", "scope" ], "additionalProperties": false } } } }, "400": { "description": "The directory or repository selector failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing, malformed, revoked, or otherwise invalid API key", "headers": { "WWW-Authenticate": { "required": true, "description": "Bearer authentication challenge for the Sparkles Sandbox API", "schema": { "type": "string", "description": "Bearer authentication challenge for the Sparkles Sandbox API" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "The API key lacks the sandboxes scope or its user is no longer an active organization member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Sandbox, repository, file, or directory not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Sandbox files are not available yet", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "The requested file operation exceeded its size limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "The repository helper rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "The API key exceeded its distributed per-minute request limit", "headers": { "Retry-After": { "required": true, "description": "Seconds until another request may be made", "schema": { "type": "string", "pattern": "^\\d+$", "description": "Seconds until another request may be made" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "The request could not be completed because of an internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/public/v1/sandboxes/{sandboxId}/files/content": { "get": { "operationId": "getSandboxFile", "tags": [ "sandbox files" ], "summary": "Read a sandbox file", "description": "Returns read-only working-tree and comparison versions. Protected files such as .env and opencode.json are never accessible.", "security": [ { "apiKey": [] } ], "parameters": [ { "in": "path", "name": "sandboxId", "schema": { "type": "string", "pattern": "^c_[a-z2-9]{12}$" }, "required": true }, { "in": "query", "name": "path", "schema": { "type": "string", "minLength": 1, "maxLength": 1000 }, "required": true }, { "in": "query", "name": "repo", "schema": { "type": "string", "maxLength": 201, "pattern": "^[A-Za-z0-9._-]+\\/[A-Za-z0-9._-]+$" } } ], "responses": { "200": { "description": "The requested read-only file document", "content": { "application/json": { "schema": { "type": "object", "properties": { "base": { "anyOf": [ { "type": "object", "properties": { "content": { "type": [ "string", "null" ] }, "hash": { "type": [ "string", "null" ] }, "ref": { "type": [ "string", "null" ] } }, "required": [ "content", "hash", "ref" ], "additionalProperties": false }, { "type": "null" } ] }, "binary": { "type": "boolean" }, "editable": { "type": "boolean", "const": false }, "editReason": { "type": [ "string", "null" ] }, "head": { "anyOf": [ { "type": "object", "properties": { "content": { "type": [ "string", "null" ] }, "hash": { "type": [ "string", "null" ] }, "ref": { "type": [ "string", "null" ] } }, "required": [ "content", "hash", "ref" ], "additionalProperties": false }, { "type": "null" } ] }, "path": { "type": "string" }, "previousPath": { "type": [ "string", "null" ] }, "reviewHead": { "anyOf": [ { "type": "object", "properties": { "content": { "type": [ "string", "null" ] }, "hash": { "type": [ "string", "null" ] }, "ref": { "type": [ "string", "null" ] } }, "required": [ "content", "hash", "ref" ], "additionalProperties": false }, { "type": "null" } ] }, "size": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "added", "deleted", "modified", "renamed", "untracked" ] }, { "type": "null" } ] }, "working": { "anyOf": [ { "type": "object", "properties": { "content": { "type": [ "string", "null" ] }, "hash": { "type": [ "string", "null" ] }, "ref": { "type": [ "string", "null" ] } }, "required": [ "content", "hash", "ref" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "base", "binary", "editable", "editReason", "head", "path", "previousPath", "reviewHead", "size", "status", "working" ], "additionalProperties": false } } } }, "400": { "description": "The file path or repository selector failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing, malformed, revoked, or otherwise invalid API key", "headers": { "WWW-Authenticate": { "required": true, "description": "Bearer authentication challenge for the Sparkles Sandbox API", "schema": { "type": "string", "description": "Bearer authentication challenge for the Sparkles Sandbox API" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "The API key lacks the sandboxes scope or its user is no longer an active organization member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Sandbox, repository, or file not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Sandbox files are not available yet", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "The requested file operation exceeded its size limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "422": { "description": "The repository helper rejected the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "The API key exceeded its distributed per-minute request limit", "headers": { "Retry-After": { "required": true, "description": "Seconds until another request may be made", "schema": { "type": "string", "pattern": "^\\d+$", "description": "Seconds until another request may be made" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "The request could not be completed because of an internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/public/v1/sandboxes/{sandboxId}/files/download": { "get": { "operationId": "downloadSandboxFile", "tags": [ "sandbox files" ], "summary": "Download a sandbox file", "description": "Streams the raw bytes of one working-tree file from a running sandbox as an attachment. The bytes are read over the sandbox ACP connection, so the sandbox must be running with a live agent connection. Files above 100 MiB, protected files such as .env and opencode.json, and .git contents are refused.", "security": [ { "apiKey": [] } ], "parameters": [ { "in": "path", "name": "sandboxId", "schema": { "type": "string", "pattern": "^c_[a-z2-9]{12}$" }, "required": true }, { "in": "query", "name": "path", "schema": { "type": "string", "minLength": 1, "maxLength": 1000 }, "required": true }, { "in": "query", "name": "repo", "schema": { "type": "string", "maxLength": 201, "pattern": "^[A-Za-z0-9._-]+\\/[A-Za-z0-9._-]+$" } } ], "responses": { "200": { "description": "The file bytes, delivered as an attachment", "headers": { "Content-Disposition": { "required": true, "description": "attachment with the file basename, RFC 5987 encoded when needed", "schema": { "type": "string", "description": "attachment with the file basename, RFC 5987 encoded when needed" } }, "Content-Length": { "required": true, "description": "File size in bytes", "schema": { "type": "string", "description": "File size in bytes" } }, "Content-Type": { "required": true, "description": "Media type reported by the sandbox, else application/octet-stream", "schema": { "type": "string", "description": "Media type reported by the sandbox, else application/octet-stream" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "The file path or repository selector failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing, malformed, revoked, or otherwise invalid API key", "headers": { "WWW-Authenticate": { "required": true, "description": "Bearer authentication challenge for the Sparkles Sandbox API", "schema": { "type": "string", "description": "Bearer authentication challenge for the Sparkles Sandbox API" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "The API key lacks the sandboxes scope or its user is no longer an active organization member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Sandbox, repository, or file not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Sandbox files or the agent connection are not available yet", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "The file exceeds the 100 MiB download limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "The API key exceeded its distributed per-minute request limit", "headers": { "Retry-After": { "required": true, "description": "Seconds until another request may be made", "schema": { "type": "string", "pattern": "^\\d+$", "description": "Seconds until another request may be made" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "The request could not be completed because of an internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "501": { "description": "The sandbox daemon does not support file downloads", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "502": { "description": "The sandbox command runtime is unavailable", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/public/v1/sandboxes/{sandboxId}/pull-request": { "get": { "operationId": "getSandboxPullRequest", "tags": [ "sandbox pull requests" ], "summary": "Get draft pull request status", "security": [ { "apiKey": [] } ], "parameters": [ { "in": "path", "name": "sandboxId", "schema": { "type": "string", "pattern": "^c_[a-z2-9]{12}$" }, "required": true }, { "in": "query", "name": "repo", "schema": { "type": "string", "maxLength": 201, "pattern": "^[A-Za-z0-9._-]+\\/[A-Za-z0-9._-]+$" } } ], "responses": { "200": { "description": "Current draft pull request and check status", "content": { "application/json": { "schema": { "type": "object", "properties": { "actionState": { "type": "string", "enum": [ "idle", "draft", "ready", "merged", "closed" ] }, "checks": { "type": "object", "properties": { "error": { "type": "string" }, "label": { "type": "string" }, "runs": { "type": "array", "items": { "type": "object", "properties": { "conclusion": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "event": { "type": [ "string", "null" ] }, "headBranch": { "type": [ "string", "null" ] }, "headSha": { "type": [ "string", "null" ] }, "id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string" }, "runNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "id", "name" ], "additionalProperties": false } }, "checkRuns": { "type": "array", "items": { "type": "object", "properties": { "completedAt": { "type": [ "string", "null" ] }, "conclusion": { "type": [ "string", "null" ] }, "id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string" }, "startedAt": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "id", "name" ], "additionalProperties": false } }, "state": { "type": "string", "enum": [ "idle", "pending", "active", "success", "failure", "error" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "label", "runs", "checkRuns", "state" ], "additionalProperties": false }, "comments": { "type": "array", "items": { "type": "object", "properties": { "author": { "type": [ "string", "null" ] }, "authorAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "createdAt": { "type": [ "string", "null" ] }, "id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "title": { "type": "string" }, "updatedAt": { "type": [ "string", "null" ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "id", "title" ], "additionalProperties": false } }, "detailsPending": { "type": "boolean" }, "pullRequest": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "nodeId": { "type": "string" }, "number": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "state": { "type": "string", "enum": [ "open", "closed" ] }, "draft": { "type": "boolean" }, "merged": { "type": "boolean" }, "baseRef": { "type": "string" }, "headRef": { "type": "string" }, "headSha": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "additions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "deletions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "changedFiles": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "nodeId", "number", "url", "title", "state", "draft", "merged", "baseRef", "headRef", "headSha", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "repository": { "type": "string" } }, "required": [ "actionState", "checks", "comments", "pullRequest", "repository" ], "additionalProperties": false } } } }, "400": { "description": "The repository selector or request body failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing, malformed, revoked, or otherwise invalid API key", "headers": { "WWW-Authenticate": { "required": true, "description": "Bearer authentication challenge for the Sparkles Sandbox API", "schema": { "type": "string", "description": "Bearer authentication challenge for the Sparkles Sandbox API" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "The API key lacks the sandboxes scope or its user is no longer an active organization member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Sandbox, repository, or pull request not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "The sandbox is not ready or has no changes to publish", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeded 16 KiB", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "415": { "description": "Content-Type was not application/json", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "The API key exceeded its distributed per-minute request limit", "headers": { "Retry-After": { "required": true, "description": "Seconds until another request may be made", "schema": { "type": "string", "pattern": "^\\d+$", "description": "Seconds until another request may be made" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "The request could not be completed because of an internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "post": { "operationId": "createSandboxPullRequest", "tags": [ "sandbox pull requests" ], "summary": "Create or update a draft pull request", "description": "Publishes sandbox changes through the sanctioned short-lived GitHub App token pipeline and returns the resulting draft pull request status.", "security": [ { "apiKey": [] } ], "parameters": [ { "in": "path", "name": "sandboxId", "schema": { "type": "string", "pattern": "^c_[a-z2-9]{12}$" }, "required": true } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "repo": { "type": "string", "maxLength": 201, "pattern": "^[A-Za-z0-9._-]+\\/[A-Za-z0-9._-]+$" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Current draft pull request and check status", "content": { "application/json": { "schema": { "type": "object", "properties": { "actionState": { "type": "string", "enum": [ "idle", "draft", "ready", "merged", "closed" ] }, "checks": { "type": "object", "properties": { "error": { "type": "string" }, "label": { "type": "string" }, "runs": { "type": "array", "items": { "type": "object", "properties": { "conclusion": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "event": { "type": [ "string", "null" ] }, "headBranch": { "type": [ "string", "null" ] }, "headSha": { "type": [ "string", "null" ] }, "id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string" }, "runNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "id", "name" ], "additionalProperties": false } }, "checkRuns": { "type": "array", "items": { "type": "object", "properties": { "completedAt": { "type": [ "string", "null" ] }, "conclusion": { "type": [ "string", "null" ] }, "id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string" }, "startedAt": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "id", "name" ], "additionalProperties": false } }, "state": { "type": "string", "enum": [ "idle", "pending", "active", "success", "failure", "error" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "label", "runs", "checkRuns", "state" ], "additionalProperties": false }, "comments": { "type": "array", "items": { "type": "object", "properties": { "author": { "type": [ "string", "null" ] }, "authorAvatarUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "createdAt": { "type": [ "string", "null" ] }, "id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "title": { "type": "string" }, "updatedAt": { "type": [ "string", "null" ] }, "url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "id", "title" ], "additionalProperties": false } }, "detailsPending": { "type": "boolean" }, "pullRequest": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "nodeId": { "type": "string" }, "number": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "state": { "type": "string", "enum": [ "open", "closed" ] }, "draft": { "type": "boolean" }, "merged": { "type": "boolean" }, "baseRef": { "type": "string" }, "headRef": { "type": "string" }, "headSha": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "additions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "deletions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "changedFiles": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "nodeId", "number", "url", "title", "state", "draft", "merged", "baseRef", "headRef", "headSha", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "repository": { "type": "string" } }, "required": [ "actionState", "checks", "comments", "pullRequest", "repository" ], "additionalProperties": false } } } }, "400": { "description": "The repository selector or request body failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing, malformed, revoked, or otherwise invalid API key", "headers": { "WWW-Authenticate": { "required": true, "description": "Bearer authentication challenge for the Sparkles Sandbox API", "schema": { "type": "string", "description": "Bearer authentication challenge for the Sparkles Sandbox API" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "The API key lacks the sandboxes scope or its user is no longer an active organization member", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Sandbox, repository, or pull request not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "The sandbox is not ready or has no changes to publish", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeded 16 KiB", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "415": { "description": "Content-Type was not application/json", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "The API key exceeded its distributed per-minute request limit", "headers": { "Retry-After": { "required": true, "description": "Seconds until another request may be made", "schema": { "type": "string", "pattern": "^\\d+$", "description": "Seconds until another request may be made" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "The request could not be completed because of an internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } } }, "components": { "schemas": { "RunCommandReceipt": { "type": "object", "properties": { "commandId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "revision": { "$ref": "#/components/schemas/RunRevision" }, "outcome": { "type": "string", "enum": [ "applied", "duplicate", "rejected" ] }, "rejection": { "type": "string", "minLength": 1 } }, "required": [ "commandId", "revision", "outcome" ], "additionalProperties": false }, "RunRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "spk_live_…", "description": "Long-lived opaque API key minted by an approved user at /api. The secret is shown once, stored only as a SHA-256 digest, and disabled immediately when either the key or its API access grant is revoked." } } } }