API Overview

The Modbox API is a REST API that lets you provision, manage, and destroy sandbox environments programmatically.

Base URL

https://api.modbox.run

Authentication

All endpoints (except /health) require a Bearer token in the Authorization header:

$
Authorization: Bearer YOUR_API_TOKEN

See the Authentication guide for details on API tokens and JWT tokens.

Workspace scoping

Many endpoints are scoped to a workspace. Pass your workspace ID via the header:

$
X-Workspace-Id: your-workspace-uuid

Endpoint groups

Response format

All responses are JSON. Successful responses return the resource directly or a wrapper object. Errors follow the standard HTTP status code conventions:

Validation errors

When a request body fails validation, the API returns a 422 with details:

1
{
2
  "detail": [
3
    {
4
      "loc": ["body", "task_id"],
5
      "msg": "Field required",
6
      "type": "missing"
7
    }
8
  ]
9
}

SDKs

Use the official SDKs for a better developer experience: