Overview

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:

curl -H "Authorization: Bearer $HOPX_API_KEY" \
  https://api.hopx.dev/v1/sandboxes

See the Authentication guide 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

{
  "id": "sandbox_abc123",
  "object": "sandbox",
  "status": "running",
  ...
}

List Response

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

Error Response

{
  "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.

VM Agent API Overview - Execute code and manage sandbox resources
Python SDK Quickstart - Use the Python SDK instead
JavaScript SDK Quickstart - Use the JavaScript SDK instead
Creating Sandboxes - Learn about sandbox creation
Managing Sandbox State - Control sandbox lifecycle
CLI Reference - Command-line interface

Next Steps

Create Sandbox - Create your first sandbox
List Sandboxes - Query and filter sandboxes
Manage Sandboxes - Get, update, and delete sandboxes
Templates - Work with templates

Getting Started

Concepts

Control Plane API

VM Agent API

Base URL

Authentication

What You Can Do

Sandbox Lifecycle

Template Management

Real-Time Monitoring

API Endpoints

Sandbox Lifecycle

Templates

Template Building

Streaming

Response Format

Success Response

List Response

Error Response

Status Codes

Rate Limits

Next Steps

​Base URL

​Authentication

​What You Can Do

​Sandbox Lifecycle

​Template Management

​Real-Time Monitoring

​API Endpoints

​Sandbox Lifecycle

​Templates

​Template Building

​Streaming

​Response Format

​Success Response

​List Response

​Error Response

​Status Codes

​Rate Limits

​Related

​Next Steps

Base URL

Authentication

What You Can Do

Sandbox Lifecycle

Template Management

Real-Time Monitoring

API Endpoints

Sandbox Lifecycle

Templates

Template Building

Streaming

Response Format

Success Response

List Response

Error Response

Status Codes

Rate Limits

Related

Next Steps