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 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 |
| Field | Type | Description |
|---|
rich_outputs | array | Array of rich output objects |
| 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:
Example timestamps:
created_at - Resource creation timeupdated_at - Last modification timecompleted_at - Task completion timeexpires_at - Expiration timetoken_expires_at - JWT token expiration
Identifiers
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"}'
Next Steps
