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

{
  "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"
      }
    }
  ]
}

{
  "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

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

SDK Usage

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

{
  "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
  }
}

{
  "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

{
  "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

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

SDK Usage

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

{
  "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"
  }
}

{
  "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

{
  "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

{
  "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

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

SDK Usage

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

{
  "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"
  }
}

{
  "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

{
  "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

{
  "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

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

SDK Usage

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

{
  "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"
  }
}

{
  "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

{
  "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

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

SDK Usage

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

{
  "deleted": true,
  "name": "fetch-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

{
  "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

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

SDK Usage

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