Skip to main content
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

EndpointMethodDescription
/v1/sandboxesPOSTCreate a new sandbox
/v1/sandboxesGETList all sandboxes
/v1/sandboxes/:idGETGet sandbox details
/v1/sandboxes/:idDELETEDelete a sandbox
/v1/sandboxes/:id/startPOSTStart a stopped sandbox
/v1/sandboxes/:id/stopPOSTStop a running sandbox
/v1/sandboxes/:id/pausePOSTPause a running sandbox
/v1/sandboxes/:id/resumePOSTResume a paused sandbox
/v1/sandboxes/:id/timeoutPUTSet or extend sandbox timeout
/v1/sandboxes/:id/token/refreshPOSTRefresh JWT token

​
Templates

EndpointMethodDescription
/v1/templatesGETList available templates
/v1/templates/:nameGETGet template details
/v1/templates/:templateIDDELETEDelete a custom template

​
Template Building

EndpointMethodDescription
/v1/templates/files/upload-linkPOSTGet presigned URL for file uploads
/v1/templates/buildPOSTTrigger template build
/v1/templates/build/:buildID/statusGETGet build status
/v1/templates/build/:buildID/logsGETStream build logs

​
Streaming

EndpointMethodDescription
/v1/sandboxes/streamGETStream sandbox events (SSE)
/v1/sandboxes/:id/metrics/streamGETStream sandbox metrics (SSE)
/v1/templates/streamGETStream 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

CodeDescription
200Success
201Created
202Accepted (async operations)
400Bad Request
401Unauthorized
403Forbidden
404Not Found
409Conflict
402Payment Required
503Service 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.

​
Next Steps