API overview
Sandbox Platform HTTP API — gateway intents, auth, and available surfaces.
The Sandbox API is a REST API at the gateway — one hostname per environment (http://localhost:8780 locally, https://sandbox.turing.com in production). L4 products call that host and pick routes by intent (Harbor benchmark, code execution, agent runtime, browser, CI).
New to Sandbox? Start with Get started, then Which API should I call?.
Prerequisites
- A Sandbox API key (
X-Api-Key) or KeyHive team token (Bearer) - For Harbor async jobs: GCS-backed artifacts (local:
make upwith a temp bucket)
Available APIs
| API | Status | Primary routes |
|---|---|---|
| Execution catalog | GA | GET /sandbox/v1/catalog |
| Harbor v2 | GA (recommended) | POST /sandbox/harbor/v2/run/datapoint, job poll + SSE |
| Agent Runtime | GA | POST /sandbox/agent/v1/runs, GET /sandbox/agent/v1/agents |
| CodeEdit | GA | POST /sandbox/codeedit/v1/executions |
| Browser | Beta | POST /sandbox/browser/v1/sessions |
| CI Runner | Beta | POST /sandbox/cirunner/v1/runs |
| Credential plane admin | GA | POST /sandbox/v1/admin/credential-plane/teams |
| harbor_extensions | Beta | Optional on datapoint agents + Agent Runtime bodies |
Harbor v1 and unversioned paths remain for compatibility; prefer v2.
Authentication
All /sandbox/* routes require credentials unless noted.
| Header | Value | Required |
|---|---|---|
X-Api-Key | Service or break-glass API key | One of API key or Bearer |
Authorization | Bearer <keyhive-team-token> | One of API key or Bearer |
Authorization | Bearer <keycloak-jwt> | Service-to-service (optional) |
Content-Type | application/json | For POST bodies |
x-correlation-id | Stable id per eval run (optional) | Gateway honors verbatim; echoed on response; see Observability |
Local default API key: dev-local-key (see make setup).
Client SDK
Use SandboxClient from sandbox_core in Python — do not call harbor-worker URLs directly from L4 products.
from sandbox_core.clients.sandbox_client import SandboxClient
client = SandboxClient.from_env()
items = client.catalog(kind="agent")See Python SandboxClient.
Rate limits
When SANDBOX_L2_SCHEDULER=quota and Redis is configured, concurrent runs are limited per project across gateway replicas. Excess requests may receive 429 with retry guidance.
Downloads
- OpenAPI YAML
- Postman:
docs/postman/sandbox_platform.postman_collection.jsonin the repo
Architecture
See Architecture (integrator view) for gateway routing and job lifecycle. Platform HLD/LLD diagrams are maintained in GitHub.
Next steps
- Get started —
make up+ first curl - Observability — correlation id + Langfuse
- Harbor v2 reference — datapoint + jobs
- Agent Runtime reference
- Authentication