Skip to main content

​
API Guide

REST endpoints for creating sessions, starting runs, and checking their status. All endpoints return JSON. Replace {threadId} and {runId} with values from previous calls.

​
Authentication & Headers

  • Every request must include Authorization: Bearer <API_KEY>; keys are provisioned per workspace and can be rotated without downtime.
  • Use X-Client-Id (optional) if you need multi-tenant attribution in logs.
  • Requests without valid credentials return 401.

​
Standard Error Format

All non-2xx responses follow the same envelope: 
{
  "error": {
    "code": "RESOURCE_NOT_FOUND|INVALID_REQUEST|UNAUTHORIZED|RATE_LIMITED|INTERNAL_ERROR",
    "message": "human readable summary",
    "hint": "optional remediation guidance",
    "requestId": "uuid for support"
  }
}

​
Rate Limits & Timeouts

  • Default limit is 60 requests/min per API key. Responses include X-RateLimit-Remaining and Retry-After when throttled (HTTP 429).
  • Long running run-creation calls keep the HTTP connection open for up to 15s; sandbox work continues asynchronously.
  • Web clients should back off exponentially on 429/5xx responses.

​
Sandbox Lifecycle

  • Runs surface current sandbox info in metadata and thread metadata so that external clients can reattach to desktops.
  • sandboxStatus transitions:
    • initializing → provisioning requested
    • ready → desktop reachable; sandboxId & vncUrl valid
    • restored → existing sandbox reused
    • failed → provisioning failed; no desktop available
  • Extend lifetime using /api/sandbox/extend; repeated calls before expiry stack 15-minute increments.

​
Endpoints

​
Create a session

POST /api/sessions Body 
{ "prompt": "your first message" }
Response (201) 
{
  "threadId": "uuid",
  "messageId": "uuid"
}

​
Get a session

GET /api/sessions/{threadId} Response (200) 
{ "thread": { ...serializedThread } }

​
Start a run in a session

POST /api/sessions/{threadId}/runs Body 
{ "message": "your follow-up message" }
Response (201) 
{
  "threadId": "uuid",
  "runId": "run_xxx",
  "publicAccessToken": "token",
  "messageId": "uuid"
}

​
Get a run

GET /api/sessions/{threadId}/runs/{runId} Response (200) 
{
  "id": "run_xxx",
  "status": "QUEUED|RUNNING|COMPLETED|FAILED|...",
  "isCompleted": false,
  "isErrored": false,
  "metadata": {
    "sandboxId": "optional",
    "vncUrl": "optional",
    "sandboxStatus": "initializing|ready|failed|restored"
  }
}

​
Extend sandbox lifetime

POST /api/sandbox/extend Body 
{ "sandboxId": "sandbox_xxx" }
Response (200) 
{
  "success": true,
  "message": "Sandbox lifecycle extended by 15 minutes",
  "sandboxId": "sandbox_xxx"
}