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

# List Templates

> List all available sandbox templates using the HopX Control Plane API. Browse pre-built and custom templates, filter by category or language, and view template configurations. Learn how to use GET /v1/templates endpoint with filtering options to discover templates for your sandbox needs. Includes request examples and response formats.

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:

```bash theme={null}
curl https://api.hopx.dev/v1/templates \
  -H "Authorization: Bearer $HOPX_API_KEY"
```

Filter by category:

```bash theme={null}
curl "https://api.hopx.dev/v1/templates?category=python" \
  -H "Authorization: Bearer $HOPX_API_KEY"
```

Filter by language:

```bash theme={null}
curl "https://api.hopx.dev/v1/templates?language=javascript" \
  -H "Authorization: Bearer $HOPX_API_KEY"
```

## Response

### Success (200 OK)

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

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

### List Only Custom Templates

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

### Find Template ID by Name

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

### Check Template Resources

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

## Related

* **SDK**: [Sandbox.list\_templates()](/sdk/python/sandbox#list_templates) - Python SDK method
* [CLI Template Commands](/cli/commands/template) - Template management from CLI

## Next Steps

* **[Get Template](/api/control-plane/get-template)** - Get detailed template information
* **[Build Template](/api/control-plane/build-template)** - Create a custom template
* **[Create Sandbox](/api/control-plane/create-sandbox)** - Create a sandbox from a template