Skip to main content
The Hopx API provides a RESTful interface for managing sandboxes (VMs), executing code, and performing file operations. All endpoints use standard HTTP methods and return JSON responses.

​
Base URL

Production: https://api.hopx.dev

​
Authentication

All API requests require authentication via API key. Include your API key in the request headers: Header Options:
  • X-API-Key: your_api_key_here (Recommended)
  • Authorization: Bearer your_api_key_here (Alternative)

​
API Structure

The API is organized into two main sections:

​
1. Lifecycle API

Control plane operations for managing sandboxes and templates:
  • Sandbox Management: Create, list, get, delete, start, stop, pause, resume sandboxes
  • Template Management: List and get template information
Base Path: /v1/sandboxes, /v1/templates

​
2. VM Agent API

Data plane operations for interacting with running sandboxes:
  • Code Execution: Execute code in multiple languages
  • File Operations: Read, write, upload, download files
  • Commands: Run shell commands
  • Process Management: List and manage background processes
  • Environment Variables: Manage runtime environment variables
  • Metrics: Get sandbox metrics and health status
  • Cache: Manage cache operations
  • Desktop: Desktop automation (if available)
  • WebSocket: Real-time streaming operations
Base Path: https://{sandbox_id}.hopx.dev (direct to VM agent)

​
Request Format

​
Headers

All requests should include: 
Content-Type: application/json
X-API-Key: your_api_key_here

​
Request Body

POST and PUT requests should include a JSON body: 
{
  "key": "value"
}

​
Response Format

​
Success Response

{
  "id": "sandbox-id",
  "status": "running",
  ...
}

​
Error Response

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "request_id": "req-123"
}

​
HTTP Status Codes

CodeMeaning
200Success
201Created
400Bad Request
401Unauthorized
403Forbidden
404Not Found
429Rate Limit Exceeded
500Server Error

​
Rate Limits

API requests are rate-limited per organization. Rate limit information is included in response headers:
  • X-RateLimit-Limit: Maximum requests per window
  • X-RateLimit-Remaining: Remaining requests in current window
  • X-RateLimit-Reset: Time when the rate limit resets

​
Getting Started

  1. Get an API Key: Create an API key in the dashboard
  2. Make Your First Request: See Authentication for details
  3. Create a Sandbox: See Create Sandbox

​
Code Examples

All API reference pages include examples in:
  • Python - Using requests library
  • JavaScript - Using fetch API
  • cURL - Command-line examples

​
Next Steps

Authentication

Learn how to authenticate API requests

Create Sandbox

Create your first sandbox

Code Execution

Execute code in sandboxes

File Operations

Work with files