Sandbox API Overview

SeaCloud Sandbox exposes an isolated Linux runtime for agents, code execution, file operations, template-based environments, public previews, and usage analytics.

Base URL

https://sandbox-service.real-cloud.seaart.ai/api/v1/sandbox

For Console traffic through the SeaCloud web app, the public path is:

https://cloud.seaart.ai/api/sandbox/v1

Use the Sandbox API base URL directly from backend services and SDKs. Do not expose API keys or envdAccessToken values in browser code.

Authentication

Sandbox API requests use a SeaCloud API key:

X-API-Key: <SEACLOUD_API_KEY>

Runtime requests to a sandbox envdUrl use the token returned by create, detail, or connect:

X-Access-Token: <envdAccessToken>

Health endpoints such as GET {envdUrl}/health do not require the runtime token.

API Groups

Group	Routes	Purpose
Sandboxes	/sandboxes	Create, list, inspect, connect, pause, refresh, timeout, delete.
Runtime	{envdUrl}	Run commands, read/write files, stream logs, inspect runtime metrics.
Templates	/templates	List official templates and resolve template references.
Usage	/sandboxes/usage/*	Query usage summary, runtime trends, storage, and cost data.
Observability	/observability/summary, /usage/limits	Dashboard support and quota diagnostics.

Response Conventions

Sandbox responses use camelCase lifecycle fields:

{
  "sandboxID": "sandbox_...",
  "templateID": "base",
  "status": "running",
  "state": "running",
  "startedAt": "2026-06-10T08:55:50Z",
  "activatedAt": "2026-06-10T08:55:50Z",
  "endAt": "2026-06-10T09:55:50Z",
  "envdUrl": "https://sandbox-router.example/9000-sandbox_...",
  "envdAccessToken": "<opaque-token>"
}

Usage APIs use snake_case fields and points arrays:

{
  "cycle_type": "minute",
  "current_value": 1.2619,
  "current_unit": "hours",
  "points": [
    { "timestamp": 1781081760000, "value": "0.0333" }
  ]
}

timeline appears on sandbox lifecycle/detail responses. Usage trend APIs do not return timeline; chart data is returned in points. Usage request and response timestamps are Unix milliseconds; Unix seconds are accepted on request for compatibility.

Errors

{
  "code": 400,
  "message": "timeoutMs is no longer supported in sandbox create requests; use timeout seconds",
  "requestID": "req_..."
}

For quota errors, inspect details.usageEndpoint and display the returned scope, resource, metric, used, limit, and remaining fields when present.