# Script Templates

**Page:** api/exec/templates

[Download Raw Markdown](./api/exec/templates.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## Script Templates

Use these endpoints to list built-in and custom script templates, preview a template with variable substitution, generate code from a template, and create, update, or delete custom templates stored under `_hoody/templates/`.

## List Templates

`GET /api/v1/exec/templates/list`

Returns the set of available script templates. By default, both built-in and user-supplied templates are included. Results can be filtered by metadata category.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `category` | query | string | No | Filter templates to a single metadata category (e.g. `api`, `utility`). Omit to list all categories. |
| `includeBuiltin` | query | boolean | No | Include built-in templates in the result set. Default `true`. Accepts `true`/`false`/`1`/`0`. |
| `includeCustom` | query | boolean | No | Include user-supplied templates (from `_hoody/templates/`) in the result set. Default `true`. |

### Response



```json
{
  "count": 2,
  "templates": [
    {
      "name": "fetch-json",
      "metadata": {
        "category": "api",
        "tags": ["http", "fetch"],
        "description": "Fetch a JSON resource and print the body.",
        "params": ["url"],
        "version": "1.0.0",
        "author": "hoody"
      }
    },
    {
      "name": "log-timestamp",
      "metadata": {
        "category": "utility",
        "tags": ["log"],
        "description": "Print a timestamped log line.",
        "params": ["message"],
        "version": "1.0.0",
        "author": "hoody"
      }
    }
  ]
}
```


```json
{
  "error": "Invalid parameter format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T12:34:56.789Z"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input | Request parameters failed validation | Check parameter format and requirements |


```json
{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T12:34:56.789Z"
}
```



### SDK Usage

```ts
const result = await client.exec.templates.list({
  category: "api",
  includeBuiltin: true,
  includeCustom: true,
});
```

## Preview Template

`GET /api/v1/exec/templates/preview`

Renders a template by name, returning both the original source and the code with the supplied variables substituted. Useful for inspecting what a generation call will produce before writing it to disk.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `name` | query | string | Yes | Name query parameter |
| `variables` | query | string | No | Variables query parameter |

### Response



```json
{
  "template": {
    "name": "fetch-json",
    "metadata": {
      "category": "api",
      "tags": ["http", "fetch"],
      "description": "Fetch a JSON resource and print the body.",
      "params": ["url"],
      "version": "1.0.0",
      "author": "hoody"
    },
    "code": "const res = await fetch('https://api.example.com/items');\nconsole.log(await res.json());",
    "originalCode": "const res = await fetch('{{url}}');\nconsole.log(await res.json());",
    "substituted": true
  }
}
```


```json
{
  "error": "Invalid parameter format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T12:34:56.789Z"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input | Request parameters failed validation | Check parameter format and requirements |


```json
{
  "error": "Resource not found",
  "code": "NOT_FOUND",
  "timestamp": "2025-01-15T12:34:56.789Z"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `NOT_FOUND` | Resource not found | The requested resource does not exist | Verify the resource identifier |


```json
{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T12:34:56.789Z"
}
```



### SDK Usage

```ts
const result = await client.exec.templates.preview({
  name: "fetch-json",
  variables: "{\"url\":\"https://api.example.com/items\"}",
});
```

## Create Custom Template

`POST /api/v1/exec/templates/create-custom`

Persists a new custom template under `_hoody/templates/`. The request body is required but its schema is intentionally open-ended; the server validates the structural fields internally.

### Request Body

This endpoint accepts a JSON payload. No specific fields are documented in the spec.

### Response



```json
{
  "created": true,
  "name": "fetch-json",
  "path": "/workspace/_hoody/templates/fetch-json.js",
  "metadata": {
    "name": "fetch-json",
    "category": "api",
    "tags": ["http", "fetch"],
    "description": "Fetch a JSON resource and print the body.",
    "params": ["url"],
    "version": "1.0.0",
    "author": "hoody"
  }
}
```


```json
{
  "error": "Invalid parameter format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T12:34:56.789Z"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input | Request parameters failed validation | Check parameter format and requirements |


```json
{
  "error": "Access denied",
  "code": "FORBIDDEN",
  "timestamp": "2025-01-15T12:34:56.789Z"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `FORBIDDEN` | Access denied | Insufficient permissions for this operation | Contact administrator for access |


```json
{
  "error": "Resource already exists",
  "code": "CONFLICT",
  "timestamp": "2025-01-15T12:34:56.789Z"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `CONFLICT` | Resource conflict | Operation conflicts with existing resource state | Check resource state and retry |


```json
{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T12:34:56.789Z"
}
```



### SDK Usage

```ts
const result = await client.exec.templates.createCustom({
  data: {
    /* template payload */
  },
});
```

## Generate From Template

`POST /api/v1/exec/templates/generate`

Generates code from a named template, substituting the provided variables. Optionally writes the generated file to `outputPath` when `saveFile` is `true`.

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | Yes | Name |
| `variables` | object | No | Variables |
| `outputPath` | string | No | Output Path |
| `saveFile` | boolean | No | Save File. Default `false` |

### Response



```json
{
  "generated": true,
  "template": "fetch-json",
  "code": "const res = await fetch('https://api.example.com/items');\nconsole.log(await res.json());",
  "saved": false,
  "path": null,
  "variables": {
    "url": "https://api.example.com/items"
  }
}
```


```json
{
  "error": "Invalid parameter format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T12:34:56.789Z"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input | Request parameters failed validation | Check parameter format and requirements |


```json
{
  "error": "Access denied",
  "code": "FORBIDDEN",
  "timestamp": "2025-01-15T12:34:56.789Z"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `FORBIDDEN` | Access denied | Insufficient permissions for this operation | Contact administrator for access |


```json
{
  "error": "Resource not found",
  "code": "NOT_FOUND",
  "timestamp": "2025-01-15T12:34:56.789Z"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `NOT_FOUND` | Resource not found | The requested resource does not exist | Verify the resource identifier |


```json
{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T12:34:56.789Z"
}
```



### SDK Usage

```ts
const result = await client.exec.templates.generate({
  data: {
    name: "fetch-json",
    variables: { url: "https://api.example.com/items" },
    outputPath: "scripts/fetch.js",
    saveFile: false,
  },
});
```

## Update Custom Template

`PUT /api/v1/exec/templates/update-custom/:name`

Patches an existing custom template. The `:name` path segment identifies the template. The request body can supply new code and/or a metadata patch that is merged with the existing metadata.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `name` | path | string | Yes | Name parameter |

### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `code` | string | No | Code |
| `metadata` | object | No | Metadata |

### Response



```json
{
  "updated": true,
  "name": "fetch-json",
  "metadata": {
    "category": "api",
    "tags": ["http", "fetch", "retry"],
    "description": "Fetch a JSON resource and print the body.",
    "params": ["url", "retries"],
    "version": "1.1.0",
    "author": "hoody"
  }
}
```


```json
{
  "error": "Invalid parameter format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T12:34:56.789Z"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input | Request parameters failed validation | Check parameter format and requirements |


```json
{
  "error": "Resource not found",
  "code": "NOT_FOUND",
  "timestamp": "2025-01-15T12:34:56.789Z"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `NOT_FOUND` | Resource not found | The requested resource does not exist | Verify the resource identifier |


```json
{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T12:34:56.789Z"
}
```



### SDK Usage

```ts
const result = await client.exec.templates.updateCustom({
  name: "fetch-json",
  data: {
    code: "const res = await fetch('{{url}}');\nconsole.log(await res.json());",
    metadata: { version: "1.1.0", tags: ["http", "fetch", "retry"] },
  },
});
```

## Delete Custom Template

`DELETE /api/v1/exec/templates/delete-custom/:name`

Removes a custom template from `_hoody/templates/`. Built-in templates cannot be deleted through this endpoint.

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `name` | path | string | Yes | Name parameter |

### Response



```json
{
  "deleted": true,
  "name": "fetch-json"
}
```


```json
{
  "error": "Invalid parameter format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T12:34:56.789Z"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `VALIDATION_ERROR` | Invalid input | Request parameters failed validation | Check parameter format and requirements |


```json
{
  "error": "Resource not found",
  "code": "NOT_FOUND",
  "timestamp": "2025-01-15T12:34:56.789Z"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `NOT_FOUND` | Resource not found | The requested resource does not exist | Verify the resource identifier |


```json
{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T12:34:56.789Z"
}
```



### SDK Usage

```ts
const result = await client.exec.templates.deleteCustom({
  name: "fetch-json",
});
```