Skip to main content
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:
FieldTypeDescription
idstringUnique sandbox identifier
statusstringCurrent status (see statuses below)
template_idstringTemplate ID used to create sandbox
template_namestringTemplate name
regionstringDeployment region
resourcesobjectAllocated vCPU, memory, disk
auth_tokenstringJWT token for VM Agent API access
token_expires_atstringJWT token expiration (ISO 8601)
public_hoststringVM Agent API base URL
timeout_secondsintegerAuto-shutdown timeout
created_atstringCreation timestamp (ISO 8601)
updated_atstringLast update timestamp (ISO 8601)

​
Sandbox Statuses

StatusDescription
creatingSandbox is being created
runningSandbox is active and ready
stoppedSandbox is stopped (can be restarted)
pausedSandbox is paused (RAM preserved)
errorSandbox creation or operation failed
deletedSandbox has been deleted

​
Sandbox Lifecycle

creating → running ⟷ stopped
              ↓
           paused → running
              ↓
          deleted

​
Template

A template defines the base image and resources for creating sandboxes:
FieldTypeDescription
idstringUnique template identifier
namestringTemplate name (unique, used as identifier)
display_namestringHuman-readable name
descriptionstringTemplate description
categorystringTemplate category (python, nodejs, ubuntu, etc.)
languagestringPrimary programming language
default_resourcesobjectDefault vCPU, memory, disk allocation
featuresarraySupported features
is_publicbooleanWhether template is publicly available
is_activebooleanWhether template is ready for use
statusstringTemplate 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:
FieldTypeDescription
successbooleanWhether execution succeeded
stdoutstringStandard output
stderrstringStandard error
exit_codeintegerExit code (0 = success)
execution_timenumberExecution time in seconds
For rich output capture, additional fields:
FieldTypeDescription
rich_outputsarrayArray of rich output objects
Each rich output object:
FieldTypeDescription
typestringMIME type (image/png, text/html, etc.)
formatstringData format (base64, text)
datastringOutput data
metadataobjectAdditional metadata

​
Process

Background execution process:
FieldTypeDescription
process_idstringUnique process identifier
execution_idstringExecution ID
namestringProcess name (optional)
statusstringProcess status (queued, running, completed, failed)
languagestringProgramming language
started_atstringStart timestamp (ISO 8601)
completed_atstringCompletion timestamp (ISO 8601, if complete)
stdoutstringStandard output
stderrstringStandard error
exit_codeintegerExit code (null if still running)

​
Object Types

All API responses include an object field identifying the resource type:
Object TypeDescription
sandboxSandbox resource
templateTemplate resource
listList of resources with pagination
errorError 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"
}
FieldTypeDescription
objectstringAlways “list”
dataarrayArray of resource objects
has_morebooleanWhether more results exist
next_cursorstringCursor for next page (if has_more)
urlstringEndpoint URL
request_idstringRequest 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:
PrefixResource TypeExample
sandbox_Sandboxsandbox_abc123xyz
template_Templatetemplate_xyz789
proc_Processproc_abc123
exec_Executionexec_xyz789
req_Requestreq_abc123
build_Template Buildbuild_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