> ## 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

> Learn what the HopX REST API does, its main resources, and who uses it. The HopX API provides two interfaces: Control Plane API for sandbox lifecycle management and VM Agent API for code execution, file operations, and desktop automation. Get started with authentication, endpoints, and API best practices. For SDK or CLI usage, see the SDK Reference or CLI Reference sections.

The HopX REST API enables you to create, manage, and interact with cloud sandboxes programmatically. Use the API to build automation workflows, integrate sandbox execution into your applications, or create custom tooling on top of HopX.

## What the API Does

The HopX API provides two main interfaces:

### Control Plane API

The **Control Plane API** (`https://api.hopx.dev`) manages sandbox lifecycle and templates:

* **Create and manage sandboxes** - Spin up isolated cloud environments from templates
* **Template management** - List, view, and build custom templates
* **Real-time monitoring** - Stream sandbox events and metrics via Server-Sent Events (SSE)
* **Resource management** - Start, stop, pause, resume, and delete sandboxes

### VM Agent API

The **VM Agent API** (sandbox-specific URLs) executes code and manages sandbox resources:

* **Code execution** - Run Python, JavaScript, Bash, and Go code synchronously or asynchronously
* **File operations** - Read, write, list, upload, and download files
* **Command execution** - Run shell commands in the sandbox environment
* **Desktop automation** - Control VNC, mouse, keyboard, screenshots, and screen recording
* **Observability** - Monitor processes, metrics, cache, and terminal access

## Main Resources

### Sandboxes

Sandboxes are isolated cloud environments created from templates. Each sandbox has:

* **Unique ID** - Identifier for all operations
* **Status** - `running`, `stopped`, `paused`, `creating`
* **Resources** - vCPU, memory, and disk allocated from template
* **Public URL** - Accessible endpoint for VM Agent API
* **JWT Token** - Authentication token for VM Agent API calls

### Templates

Templates define the base environment for sandboxes:

* **Pre-built templates** - Python, Node.js, Ubuntu, and more
* **Custom templates** - Build your own with Docker images and build steps
* **Resource specifications** - vCPU, memory, and disk limits
* **Features** - Desktop support, internet access, pre-installed packages

## When to Use the API vs SDK vs CLI

### Use the REST API when:

* ✅ You're building in a language without an official SDK
* ✅ You need fine-grained control over HTTP requests
* ✅ You're integrating with existing HTTP client libraries
* ✅ You need custom retry logic or connection pooling
* ✅ You're building serverless functions or edge workers

### Use the SDK when:

* ✅ You're building Python or JavaScript/TypeScript applications
* ✅ You want type safety and IDE autocomplete
* ✅ You prefer language-native error handling
* ✅ You want automatic resource management

### Use the CLI when:

* ✅ You prefer command-line workflows
* ✅ You're scripting or automating from shell
* ✅ You want quick one-off operations
* ✅ You're working in CI/CD pipelines

## Typical Consumers

The HopX API is used by:

* **Backend developers** - Integrating sandbox execution into applications
* **DevOps engineers** - Automating infrastructure and testing workflows
* **AI/ML engineers** - Running model training and inference in isolated environments
* **CI/CD pipelines** - Executing tests and builds in clean sandboxes
* **Automation tools** - Building custom tooling and workflows

## Base URLs

### Control Plane API

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

All Control Plane endpoints are prefixed with `/v1/`:

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

### VM Agent API

Each sandbox has its own VM Agent API endpoint:

```
https://{sandbox_id}.hopx.dev
```

Or using the direct URL format:

```
https://{port}-{vmId}.{serverId}.hopx.dev
```

The VM Agent base URL is returned in the `public_host` or `direct_url` field when creating a sandbox.

## API Specification

The HopX API follows RESTful principles:

* **HTTP methods** - GET, POST, PUT, DELETE for resource operations
* **JSON request/response** - All request bodies and responses use JSON
* **Standard status codes** - 200, 201, 400, 401, 404, 503, etc.
* **Error format** - Consistent error response structure with codes and messages

<Info>
  An OpenAPI specification is available for the Control Plane API. The spec is kept in sync with the API implementation and can be used to generate client SDKs or mock servers.
</Info>

## Related

* **[API Quickstart](/api/quickstart)** - Get started with the API
* **[Authentication](/api/authentication)** - Learn about API authentication
* **[Python SDK Quickstart](/sdk/python/quickstart)** - Use the Python SDK instead
* **[JavaScript SDK Quickstart](/sdk/javascript/quickstart)** - Use the JavaScript SDK instead
* **[VM Agent API Overview](/api/vm-agent/overview)** - Learn about the VM Agent API
* [CLI Reference](/cli/introduction) - Command-line interface

## Next Steps

* **[Authentication](/api/authentication)** - Learn how to authenticate API requests
* **[Quickstart](/api/quickstart)** - Get your first sandbox running in minutes
* **[Control Plane API](/api/control-plane/overview)** - Manage sandboxes and templates
* **[VM Agent API](/api/vm-agent/overview)** - Execute code and manage sandbox resources