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

# Data Model

> Core resources and data structures in the HopX API. Understand sandbox objects, template structures, execution results, file metadata, and other data models used throughout the HopX API. Essential for working with API responses and building integrations. Includes data model reference and field descriptions.

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:

```json theme={null}
{
  "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

```bash theme={null}
# 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"}'
```

## Related

* **[API Introduction](/api/introduction)** - Learn about the HopX API
* **[Creating Sandboxes](/core-concepts/sandboxes/creating)** - Learn about sandbox creation
* **[Managing Sandbox State](/core-concepts/sandboxes/managing-state)** - Control sandbox lifecycle
* **[Control Plane API Overview](/api/control-plane/overview)** - Manage sandboxes via API
* **[VM Agent API Overview](/api/vm-agent/overview)** - Execute code via API
* [CLI Reference](/cli/introduction) - Command-line interface

## Next Steps

* **[Errors](/api/concepts/errors)** - Error handling and codes
* **[Rate Limits](/api/concepts/rate-limits)** - Request rate limits
* **[Pagination](/api/concepts/pagination)** - Paginating list results