List Templates

List all available templates that can be used to create sandboxes. This includes both public pre-built templates and your organization’s custom templates.

Endpoint

GET /v1/templates

Request

Headers

Authorization: Bearer $HOPX_API_KEY

Query Parameters

Parameter	Type	Required	Description
`category`	string	No	Filter by category (e.g., `python`, `nodejs`, `ubuntu`)
`language`	string	No	Filter by language (e.g., `python`, `javascript`)

Example Request

List all templates:

curl https://api.hopx.dev/v1/templates \
  -H "Authorization: Bearer $HOPX_API_KEY"

Filter by category:

curl "https://api.hopx.dev/v1/templates?category=python" \
  -H "Authorization: Bearer $HOPX_API_KEY"

Filter by language:

curl "https://api.hopx.dev/v1/templates?language=javascript" \
  -H "Authorization: Bearer $HOPX_API_KEY"

Response

Success (200 OK)

{
  "object": "list",
  "data": [
    {
      "id": "73",
      "name": "code-interpreter",
      "display_name": "Code Interpreter",
      "description": "Pre-built environment for Python, JavaScript, and Bash execution",
      "category": "python",
      "language": "python",
      "is_public": true,
      "is_active": true,
      "default_resources": {
        "vcpu": 2,
        "memory_mb": 4096,
        "disk_gb": 10
      }
    },
    {
      "id": "74",
      "name": "python-3.11",
      "display_name": "Python 3.11",
      "description": "Python 3.11 environment with pip and common packages",
      "category": "python",
      "language": "python",
      "is_public": true,
      "is_active": true,
      "default_resources": {
        "vcpu": 1,
        "memory_mb": 2048,
        "disk_gb": 5
      }
    }
  ],
  "has_more": false,
  "url": "/v1/templates",
  "request_id": "req_abc123"
}

Response Fields

Field	Type	Description
`object`	string	Always `"list"`
`data`	array	Array of template objects
`has_more`	boolean	Whether more results are available
`url`	string	Endpoint URL
`request_id`	string	Request ID for debugging

Each template object includes:

id - Template ID (use for creating sandboxes)
name - Template name (alternative identifier)
display_name - Human-readable name
description - Template description
category - Template category
language - Primary language (if applicable)
is_public - Whether template is publicly available
is_active - Whether template is active and ready for use
default_resources - Default vCPU, memory, and disk allocation

Status Codes

Code	Description
`200`	Success
`401`	Authentication required

Template Categories

Common template categories:

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

Use Cases

Find Python Templates

curl "https://api.hopx.dev/v1/templates?category=python" \
  -H "Authorization: Bearer $HOPX_API_KEY" | jq '.data[]'

List Only Custom Templates

curl https://api.hopx.dev/v1/templates \
  -H "Authorization: Bearer $HOPX_API_KEY" | \
  jq '.data[] | select(.is_public == false)'

Find Template ID by Name

curl https://api.hopx.dev/v1/templates \
  -H "Authorization: Bearer $HOPX_API_KEY" | \
  jq '.data[] | select(.name == "code-interpreter") | .id'

Check Template Resources

curl https://api.hopx.dev/v1/templates \
  -H "Authorization: Bearer $HOPX_API_KEY" | \
  jq '.data[] | {name: .name, resources: .default_resources}'

SDK: Sandbox.list_templates() - Python SDK method
CLI Template Commands - Template management from CLI

Next Steps

Get Template - Get detailed template information
Build Template - Create a custom template
Create Sandbox - Create a sandbox from a template

Getting Started

Concepts

Control Plane API

VM Agent API

Endpoint

Request

Headers

Query Parameters

Example Request

Response

Success (200 OK)

Response Fields

Status Codes

Template Categories

Use Cases

Find Python Templates

List Only Custom Templates

Find Template ID by Name

Check Template Resources

Next Steps

​Endpoint

​Request

​Headers

​Query Parameters

​Example Request

​Response

​Success (200 OK)

​Response Fields

​Status Codes

​Template Categories

​Use Cases

​Find Python Templates

​List Only Custom Templates

​Find Template ID by Name

​Check Template Resources

​Related

​Next Steps

Endpoint

Request

Headers

Query Parameters

Example Request

Response

Success (200 OK)

Response Fields

Status Codes

Template Categories

Use Cases

Find Python Templates

List Only Custom Templates

Find Template ID by Name

Check Template Resources

Related

Next Steps