Script Templates

The Script Templates API exposes the container’s template engine: list available templates (built-in and custom), preview a template with variable substitution, generate executable code from a template, and create, update, or delete custom user-supplied templates stored in _hoody/templates/. Use these endpoints when integrating template-driven automation or building tooling that needs to inspect or extend the available script scaffolds.

Note

All endpoints on this page are container-scoped. Substitute {projectId}, {containerId}, and {server} in the base URL with the values from your environment.

GET /api/v1/exec/templates/list

Returns the set of available templates. Built-in and custom templates are both included by default; pass query parameters to narrow the result set by category or to exclude either source.

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.

cURL

curl -X GET "https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.icu/api/v1/exec/templates/list?includeBuiltin=true&includeCustom=true"

SDK

await client.exec.templates.list({ includeBuiltin: true, includeCustom: true })

200

{
  "count": 2,
  "templates": [
    {
      "name": "api-fetch",
      "metadata": {
        "category": "api",
        "description": "Fetch a JSON resource via curl and jq.",
        "tags": ["http", "curl"],
        "params": ["url", "method"],
        "version": "1.0.0",
        "author": "hoody"
      }
    },
    {
      "name": "db-migrate",
      "metadata": {
        "category": "data",
        "description": "Apply SQL migrations against a Postgres database.",
        "tags": ["postgres", "sql"],
        "params": ["db", "dir"],
        "version": "1.2.0",
        "author": "hoody"
      }
    }
  ]
}

400

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2026-01-15T12:34:56.789Z",
  "details": {
    "parameter": "includeBuiltin"
  }
}

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

500

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

GET /api/v1/exec/templates/preview

Renders a template with optional variable substitution and returns both the substituted and original source. Useful for previewing what a generated script will look like before invoking the generate endpoint.

Parameters

Name	In	Type	Required	Description
name	query	string	Yes	Name of the template to preview.
variables	query	string	No	JSON-encoded object of variables to substitute into the template body.

cURL

curl -X GET "https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.icu/api/v1/exec/templates/preview?name=api-fetch&variables=%7B%22url%22%3A%22https%3A%2F%2Fapi.example.com%22%7D"

SDK

await client.exec.templates.preview({ name: 'api-fetch', variables: '{"url":"https://api.example.com"}' })

200

{
  "template": {
    "name": "api-fetch",
    "metadata": {
      "category": "api",
      "description": "Fetch a JSON resource via curl and jq.",
      "tags": ["http", "curl"],
      "params": ["url", "method"],
      "version": "1.0.0",
      "author": "hoody"
    },
    "code": "curl -sS -X GET https://api.example.com | jq .",
    "originalCode": "curl -sS -X {{method}} {{url}} | jq .",
    "substituted": true
  }
}

400

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2026-01-15T12:34:56.789Z"
}

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

404

{
  "error": "Template not found",
  "code": "NOT_FOUND",
  "timestamp": "2026-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

500

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

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

Creates a new custom template in the container’s _hoody/templates/ directory. The endpoint returns the persisted metadata so the caller can confirm what was written.

Request Body

This endpoint accepts a JSON request payload. The body schema is intentionally open-ended by the server and does not define specific fields.

{}

cURL

curl -X POST "https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.icu/api/v1/exec/templates/create-custom" \
  -H "Content-Type: application/json" \
  -d '{}'

SDK

await client.exec.templates.createCustom({})

200

{
  "created": true,
  "name": "log-rotator",
  "path": "_hoody/templates/log-rotator",
  "metadata": {
    "name": "log-rotator",
    "category": "utility",
    "tags": ["logs", "cleanup"],
    "description": "Delete log files older than N days.",
    "params": ["logDir", "days"],
    "version": "1.0.0",
    "author": "ops"
  }
}

400

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2026-01-15T12:34:56.789Z"
}

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

403

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

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

409

{
  "error": "Template already exists",
  "code": "CONFLICT",
  "timestamp": "2026-01-15T12:34:56.789Z"
}

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

500

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

POST /api/v1/exec/templates/generate

Generates executable code from a named template by substituting the supplied variables. Optionally writes the result to disk if saveFile is true.

Request Body

Name	Type	Required	Description
name	string	Yes	Name of the template to generate.
variables	object	No	Variable values to substitute into the template.
outputPath	string	No	Filesystem path to write the generated code to when saveFile is true.
saveFile	boolean	No	When true, persists the generated code to outputPath. Default false.

cURL

curl -X POST "https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.icu/api/v1/exec/templates/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api-fetch",
    "variables": {
      "url": "https://api.example.com/users",
      "method": "GET"
    },
    "outputPath": "/tmp/fetch.sh",
    "saveFile": false
  }'

SDK

await client.exec.templates.generate({
  name: 'api-fetch',
  variables: {
    url: 'https://api.example.com/users',
    method: 'GET'
  },
  outputPath: '/tmp/fetch.sh',
  saveFile: false
})

200

{
  "generated": true,
  "template": "api-fetch",
  "code": "curl -sS -X GET https://api.example.com/users | jq .",
  "saved": false,
  "path": null,
  "variables": {
    "url": "https://api.example.com/users",
    "method": "GET"
  }
}

400

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2026-01-15T12:34:56.789Z"
}

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

403

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

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

404

{
  "error": "Template not found",
  "code": "NOT_FOUND",
  "timestamp": "2026-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

500

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

PUT /api/v1/exec/templates/update-custom/{name}

Updates an existing custom template. The supplied metadata object is merged with the existing metadata; supply code to replace the template source.

Parameters

Name	In	Type	Required	Description
name	path	string	Yes	Name of the custom template to update.

Request Body

Name	Type	Required	Description
code	string	No	New template source. Omit to leave unchanged.
metadata	object	No	Metadata fields to merge into the existing template metadata.

cURL

curl -X PUT "https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.icu/api/v1/exec/templates/update-custom/log-rotator" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "find {{logDir}} -name \"*.log\" -mtime +{{days}} -exec rm {} \\;",
    "metadata": {
      "version": "1.1.0",
      "description": "Delete log files older than N days (safe rm)."
    }
  }'

SDK

await client.exec.templates.updateCustom('log-rotator', {
  code: 'find {{logDir}} -name "*.log" -mtime +{{days}} -exec rm {} \\;',
  metadata: {
    version: '1.1.0',
    description: 'Delete log files older than N days (safe rm).'
  }
})

200

{
  "updated": true,
  "name": "log-rotator",
  "metadata": {
    "name": "log-rotator",
    "category": "utility",
    "tags": ["logs", "cleanup"],
    "description": "Delete log files older than N days (safe rm).",
    "params": ["logDir", "days"],
    "version": "1.1.0",
    "author": "ops"
  }
}

400

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2026-01-15T12:34:56.789Z"
}

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

404

{
  "error": "Template not found",
  "code": "NOT_FOUND",
  "timestamp": "2026-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

500

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

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 of the custom template to delete.

cURL

curl -X DELETE "https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.icu/api/v1/exec/templates/delete-custom/log-rotator"

SDK

await client.exec.templates.deleteCustom('log-rotator')

200

{
  "deleted": true,
  "name": "log-rotator"
}

400

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2026-01-15T12:34:56.789Z"
}

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

404

{
  "error": "Template not found",
  "code": "NOT_FOUND",
  "timestamp": "2026-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

500

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