> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Manage sandboxes, templates, and monitor resources with the HopX Control Plane API. Create and manage sandbox lifecycle, list and build templates, monitor resources, and stream real-time events. Complete reference for all Control Plane API endpoints with authentication, request formats, and response handling.

The Control Plane API (`https://api.hopx.dev`) manages the lifecycle of sandboxes and templates. Use it to create, list, manage, and monitor your cloud sandboxes.

## Base URL

```
https://api.hopx.dev
```

All endpoints are prefixed with `/v1/`:

```
https://api.hopx.dev/v1/sandboxes
https://api.hopx.dev/v1/templates
```

## Authentication

All Control Plane API requests require an API key. Include it in the `Authorization` header:

```bash theme={null}
curl -H "Authorization: Bearer $HOPX_API_KEY" \
  https://api.hopx.dev/v1/sandboxes
```

See the [Authentication guide](/api/authentication) for details.

## What You Can Do

### Sandbox Lifecycle

* **Create sandboxes** - Spin up isolated environments from templates
* **List and filter** - Query sandboxes by status, region, or other criteria
* **Manage state** - Start, stop, pause, resume, and delete sandboxes
* **Set timeouts** - Configure auto-shutdown timers
* **Refresh tokens** - Renew JWT tokens for VM Agent API access

### Template Management

* **List templates** - Browse available pre-built and custom templates
* **Get template details** - View template configuration and resources
* **Build templates** - Create custom templates from Docker images
* **Delete templates** - Remove custom templates (when not in use)

### Real-Time Monitoring

* **Stream sandbox events** - Server-Sent Events (SSE) for sandbox lifecycle changes
* **Stream metrics** - Real-time VM metrics for running sandboxes
* **Stream template updates** - Real-time template list changes

## API Endpoints

### Sandbox Lifecycle

| Endpoint                          | Method | Description                   |
| --------------------------------- | ------ | ----------------------------- |
| `/v1/sandboxes`                   | POST   | Create a new sandbox          |
| `/v1/sandboxes`                   | GET    | List all sandboxes            |
| `/v1/sandboxes/:id`               | GET    | Get sandbox details           |
| `/v1/sandboxes/:id`               | DELETE | Delete a sandbox              |
| `/v1/sandboxes/:id/start`         | POST   | Start a stopped sandbox       |
| `/v1/sandboxes/:id/stop`          | POST   | Stop a running sandbox        |
| `/v1/sandboxes/:id/pause`         | POST   | Pause a running sandbox       |
| `/v1/sandboxes/:id/resume`        | POST   | Resume a paused sandbox       |
| `/v1/sandboxes/:id/timeout`       | PUT    | Set or extend sandbox timeout |
| `/v1/sandboxes/:id/token/refresh` | POST   | Refresh JWT token             |

### Templates

| Endpoint                    | Method | Description              |
| --------------------------- | ------ | ------------------------ |
| `/v1/templates`             | GET    | List available templates |
| `/v1/templates/:name`       | GET    | Get template details     |
| `/v1/templates/:templateID` | DELETE | Delete a custom template |

### Template Building

| Endpoint                              | Method | Description                        |
| ------------------------------------- | ------ | ---------------------------------- |
| `/v1/templates/files/upload-link`     | POST   | Get presigned URL for file uploads |
| `/v1/templates/build`                 | POST   | Trigger template build             |
| `/v1/templates/build/:buildID/status` | GET    | Get build status                   |
| `/v1/templates/build/:buildID/logs`   | GET    | Stream build logs                  |

### Streaming

| Endpoint                           | Method | Description                  |
| ---------------------------------- | ------ | ---------------------------- |
| `/v1/sandboxes/stream`             | GET    | Stream sandbox events (SSE)  |
| `/v1/sandboxes/:id/metrics/stream` | GET    | Stream sandbox metrics (SSE) |
| `/v1/templates/stream`             | GET    | Stream template events (SSE) |

## Response Format

All responses use JSON with a consistent structure:

### Success Response

```json theme={null}
{
  "id": "sandbox_abc123",
  "object": "sandbox",
  "status": "running",
  ...
}
```

### List Response

```json theme={null}
{
  "object": "list",
  "data": [...],
  "has_more": false,
  "next_cursor": null,
  "request_id": "req_abc123"
}
```

### Error Response

```json theme={null}
{
  "error": "Error message",
  "code": "ERROR_CODE",
  "request_id": "req_abc123"
}
```

## Status Codes

| Code | Description                 |
| ---- | --------------------------- |
| 200  | Success                     |
| 201  | Created                     |
| 202  | Accepted (async operations) |
| 400  | Bad Request                 |
| 401  | Unauthorized                |
| 403  | Forbidden                   |
| 404  | Not Found                   |
| 409  | Conflict                    |
| 402  | Payment Required            |
| 503  | Service Unavailable         |

## Rate Limits

The Control Plane API has rate limits to ensure fair usage. Rate limit headers are included in responses:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
```

If you exceed the rate limit, you'll receive a `429 Too Many Requests` response.

## Related

* **[VM Agent API Overview](/api/vm-agent/overview)** - Execute code and manage sandbox resources
* **[Python SDK Quickstart](/sdk/python/quickstart)** - Use the Python SDK instead
* **[JavaScript SDK Quickstart](/sdk/javascript/quickstart)** - Use the JavaScript SDK instead
* **[Creating Sandboxes](/core-concepts/sandboxes/creating)** - Learn about sandbox creation
* **[Managing Sandbox State](/core-concepts/sandboxes/managing-state)** - Control sandbox lifecycle
* [CLI Reference](/cli/introduction) - Command-line interface

## Next Steps

* **[Create Sandbox](/api/control-plane/create-sandbox)** - Create your first sandbox
* **[List Sandboxes](/api/control-plane/list-sandboxes)** - Query and filter sandboxes
* **[Manage Sandboxes](/api/control-plane/get-sandbox)** - Get, update, and delete sandboxes
* **[Templates](/api/control-plane/list-templates)** - Work with templates