Data Model

The HopX API uses a consistent data model across all endpoints. Understanding these core resources and their relationships is essential for effective API usage.

Core Resources

Sandbox

A sandbox is an isolated virtual machine environment for code execution. Each sandbox has:

Field	Type	Description
`id`	string	Unique sandbox identifier
`status`	string	Current status (see statuses below)
`template_id`	string	Template ID used to create sandbox
`template_name`	string	Template name
`region`	string	Deployment region
`resources`	object	Allocated vCPU, memory, disk
`auth_token`	string	JWT token for VM Agent API access
`token_expires_at`	string	JWT token expiration (ISO 8601)
`public_host`	string	VM Agent API base URL
`timeout_seconds`	integer	Auto-shutdown timeout
`created_at`	string	Creation timestamp (ISO 8601)
`updated_at`	string	Last update timestamp (ISO 8601)

Sandbox Statuses

Status	Description
`creating`	Sandbox is being created
`running`	Sandbox is active and ready
`stopped`	Sandbox is stopped (can be restarted)
`paused`	Sandbox is paused (RAM preserved)
`error`	Sandbox creation or operation failed
`deleted`	Sandbox has been deleted

Sandbox Lifecycle

creating → running ⟷ stopped
              ↓
           paused → running
              ↓
          deleted

Template

A template defines the base image and resources for creating sandboxes:

Field	Type	Description
`id`	string	Unique template identifier
`name`	string	Template name (unique, used as identifier)
`display_name`	string	Human-readable name
`description`	string	Template description
`category`	string	Template category (python, nodejs, ubuntu, etc.)
`language`	string	Primary programming language
`default_resources`	object	Default vCPU, memory, disk allocation
`features`	array	Supported features
`is_public`	boolean	Whether template is publicly available
`is_active`	boolean	Whether template is ready for use
`status`	string	Template status (active, building, failed)

Template Categories

python - Python environments (various versions)
nodejs - Node.js environments
ubuntu - Ubuntu base images
code-interpreter - Multi-language execution environments
custom - Custom organization templates

Execution Result

Result from code execution or command:

Field	Type	Description
`success`	boolean	Whether execution succeeded
`stdout`	string	Standard output
`stderr`	string	Standard error
`exit_code`	integer	Exit code (0 = success)
`execution_time`	number	Execution time in seconds

For rich output capture, additional fields:

Field	Type	Description
`rich_outputs`	array	Array of rich output objects

Each rich output object:

Field	Type	Description
`type`	string	MIME type (image/png, text/html, etc.)
`format`	string	Data format (base64, text)
`data`	string	Output data
`metadata`	object	Additional metadata

Process

Background execution process:

Field	Type	Description
`process_id`	string	Unique process identifier
`execution_id`	string	Execution ID
`name`	string	Process name (optional)
`status`	string	Process status (queued, running, completed, failed)
`language`	string	Programming language
`started_at`	string	Start timestamp (ISO 8601)
`completed_at`	string	Completion timestamp (ISO 8601, if complete)
`stdout`	string	Standard output
`stderr`	string	Standard error
`exit_code`	integer	Exit code (null if still running)

Object Types

All API responses include an object field identifying the resource type:

Object Type	Description
`sandbox`	Sandbox resource
`template`	Template resource
`list`	List of resources with pagination
`error`	Error response

List Objects

List endpoints return a consistent structure:

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

Field	Type	Description
`object`	string	Always “list”
`data`	array	Array of resource objects
`has_more`	boolean	Whether more results exist
`next_cursor`	string	Cursor for next page (if has_more)
`url`	string	Endpoint URL
`request_id`	string	Request ID for debugging

Timestamps

All timestamps use ISO 8601 format with UTC timezone:

2025-01-28T00:00:00Z

Example timestamps:

created_at - Resource creation time
updated_at - Last modification time
completed_at - Task completion time
expires_at - Expiration time
token_expires_at - JWT token expiration

Identifiers

Format

Identifiers follow consistent patterns:

Prefix	Resource Type	Example
`sandbox_`	Sandbox	`sandbox_abc123xyz`
`template_`	Template	`template_xyz789`
`proc_`	Process	`proc_abc123`
`exec_`	Execution	`exec_xyz789`
`req_`	Request	`req_abc123`
`build_`	Template Build	`build_abc123`

Usage

Identifiers are case-sensitive
Store identifiers as returned by the API
Use template name or id when creating sandboxes

Resource Relationships

Template (1) ──creates──> (N) Sandbox
                            │
                            ├──has──> (1) JWT Token
                            │
                            └──runs──> (N) Process/Execution

One template can create multiple sandboxes
Each sandbox has one JWT token (refreshable)
Each sandbox can have multiple concurrent processes/executions

Common Patterns

Create → Poll → Use

# 1. Create resource
RESPONSE=$(curl -X POST https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer $HOPX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id": "code-interpreter"}')

SANDBOX_ID=$(echo "$RESPONSE" | jq -r '.id')

# 2. Poll until ready (status: running)
while true; do
  STATUS=$(curl -s "https://api.hopx.dev/v1/sandboxes/$SANDBOX_ID" \
    -H "Authorization: Bearer $HOPX_API_KEY" | jq -r '.status')
  
  [ "$STATUS" == "running" ] && break
  sleep 2
done

# 3. Use resource
JWT_TOKEN=$(curl -s "https://api.hopx.dev/v1/sandboxes/$SANDBOX_ID" \
  -H "Authorization: Bearer $HOPX_API_KEY" | jq -r '.auth_token')

curl -X POST "https://$SANDBOX_ID.hopx.dev/execute" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "print(\"Hello World\")", "language": "python"}'

API Introduction - Learn about the HopX API
Creating Sandboxes - Learn about sandbox creation
Managing Sandbox State - Control sandbox lifecycle
Control Plane API Overview - Manage sandboxes via API
VM Agent API Overview - Execute code via API
CLI Reference - Command-line interface

Next Steps

Errors - Error handling and codes
Rate Limits - Request rate limits
Pagination - Paginating list results

Getting Started

Concepts

Control Plane API

VM Agent API

Core Resources

Sandbox

Sandbox Statuses

Sandbox Lifecycle

Template

Template Categories

Execution Result

Process

Object Types

List Objects

Timestamps

Identifiers

Format

Usage

Resource Relationships

Common Patterns

Create → Poll → Use

Next Steps

​Core Resources

​Sandbox

​Sandbox Statuses

​Sandbox Lifecycle

​Template

​Template Categories

​Execution Result

​Process

​Object Types

​List Objects

​Timestamps

​Identifiers

​Format

​Usage

​Resource Relationships

​Common Patterns

​Create → Poll → Use

​Related

​Next Steps

Core Resources

Sandbox

Sandbox Statuses

Sandbox Lifecycle

Template

Template Categories

Execution Result

Process

Object Types

List Objects

Timestamps

Identifiers

Format

Usage

Resource Relationships

Common Patterns

Create → Poll → Use

Related

Next Steps