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.
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
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
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) |
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
429 Too Many Requests response.
Next Steps
