API Overview

The Runra Sandbox REST API lets you programmatically create, manage, and execute code in secure cloud sandboxes. All API endpoints are served over HTTPS from the base URL.

Base URL

https://api.box.runra.dev

All requests must use HTTPS. Plain HTTP requests will receive a 301 Moved Permanently redirect to the HTTPS endpoint.

API Versioning

The current API version is v1 and is specified as a path prefix:

https://api.box.runra.dev/v1

The version prefix is required on all requests. We follow semantic versioning for the API contract:

• Minor additions (new fields, new endpoints) are backward-compatible and do not require a version bump.
• Breaking changes (field removal, type change, endpoint deprecation) will ship under a new version prefix (/v2).
• Deprecated endpoints receive a Deprecation: true response header and remain available for at least 90 days.

The current API version is also available via a lightweight status endpoint:

curl https://api.box.runra.dev/v1/health

{
  "status": "ok",
  "version": "v1",
  "timestamp": "2026-06-15T10:30:00Z"
}

Authentication

All endpoints require authentication via Bearer token:

curl -H "Authorization: Bearer $RUNRA_API_KEY" \
  https://api.box.runra.dev/v1/sandboxes

See Authentication for details on obtaining and managing API keys.

Content Types

Request Body

All POST and PUT endpoints accept JSON bodies. You must set:

Content-Type: application/json

Response Body

All responses are JSON with:

Content-Type: application/json; charset=utf-8

Successful responses return HTTP 2xx. The response envelope for collection endpoints includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Single-resource endpoints return the resource directly:

{
  "id": "sb_x7k2m9p4q1",
  "state": "running",
  "image": "node:22",
  "createdAt": "2026-06-15T10:30:00Z"
}

Error Format

All error responses use a consistent structure:

{
  "error": {
    "code": "SANDBOX_NOT_FOUND",
    "message": "Sandbox sb_x7k2m9p4q1 not found",
    "details": {
      "sandboxId": "sb_x7k2m9p4q1"
    },
    "requestId": "req_a1b2c3d4"
  }
}

Common Error Codes

HTTP Status	Code	Description
400	INVALID_REQUEST	Malformed request body or query parameters
400	INVALID_CONFIG	Configuration values out of allowed range
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	Valid key but insufficient permissions
404	SANDBOX_NOT_FOUND	Sandbox does not exist or was terminated
409	INVALID_STATE	Operation not valid for current sandbox state
429	RATE_LIMITED	Too many requests; see Retry-After header
500	INTERNAL_ERROR	Unexpected server error
503	RESOURCE_EXHAUSTED	No capacity available; try again later

Rate Limits

Rate limits are applied per API key. The default limits are:

Endpoint Group	Limit	Window
Read endpoints (GET)	300	per minute
Write endpoints (POST, PUT, DELETE)	60	per minute
Sandbox creation (POST /v1/sandboxes)	10	per minute
Code execution (POST /v1/sandboxes/:id/execute)	100	per minute per sandbox

Rate limit headers are included on every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1718445600

When exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating seconds to wait.

If you need higher limits, contact support@runra.dev.

Pagination

Collection endpoints support cursor-based pagination:

Parameter	Type	Default	Description
limit	integer	20	Number of items per page (max 100)
offset	integer	0	Number of items to skip

Idempotency

POST endpoints that create resources support idempotency keys. Pass an Idempotency-Key header to safely retry requests:

curl -X POST https://api.box.runra.dev/v1/sandboxes \
  -H "Authorization: Bearer $RUNRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"image": "node:22"}'

Idempotency keys are valid for 24 hours. Repeated requests with the same key return the original response.

Request IDs

Every response includes an X-Request-Id header with a unique identifier for the request. Include this value when contacting support to help us debug issues.

Timestamps

All timestamps are in ISO 8601 format with UTC timezone:

2026-06-15T10:30:00.123Z

Next Steps

• Authentication — obtain and manage API keys
• Sandboxes API — create and manage sandboxes
• Execution API — run code inside sandboxes