Script Templates

The Script Templates API lets you browse built-in and custom templates, preview them with substituted variables, generate scripts on the fly, and manage your own custom templates stored under _hoody/templates/. Use these endpoints when you want to scaffold new scripts from a known-good starting point or curate a private library of reusable templates for your container.

All template operations target the exec service in your container. Output scripts are written under /hoody/storage/hoody-exec/scripts; the outputPath you pass to generate is relative to that scripts root and must carry the host/exec scope itself (for example, default/1/fetch-items.ts).

List Templates

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

Returns the catalog of templates available to this container. Built-in templates ship with the platform; custom templates are user-supplied files in _hoody/templates/. Use category to narrow the result to a single metadata bucket.

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": 3,
  "templates": [
    {
      "name": "api-fetch-items",
      "category": "api"
    },
    {
      "name": "utility-format-date",
      "category": "utility"
    },
    {
      "name": "internal-sync",
      "category": "internal"
    }
  ]
}

{
  "error": "Invalid parameter format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-04-12T18:21:00.451Z"
}

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-04-12T18:21:00.451Z"
}

curl -X GET "https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.com/api/v1/exec/templates/list?includeBuiltin=true&includeCustom=true" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

Preview Template

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

Renders a template with optional variable substitution without writing a script file. Use this to inspect what a template produces (code) versus the raw template body (originalCode) and whether placeholders have been resolved (substituted).

Parameters

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

Response

{
  "template": {
    "name": "api-fetch-items",
    "metadata": {
      "category": "api",
      "tags": ["fetch", "items"],
      "description": "Fetches items from a configured API endpoint",
      "params": ["url", "method"]
    },
    "code": "// resolved code with variables substituted\nexport async function main() {\n  const url = 'https://api.example.com/items';\n  const method = 'GET';\n  return await fetch(url, { method });\n}\n",
    "originalCode": "// raw template with placeholders\nexport async function main() {\n  const url = '{{url}}';\n  const method = '{{method}}';\n  return await fetch(url, { method });\n}\n",
    "substituted": true
  }
}

{
  "error": "Invalid parameter format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-04-12T18:21:00.451Z"
}

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

{
  "error": "Template not found",
  "code": "NOT_FOUND",
  "timestamp": "2025-04-12T18:21:00.451Z"
}

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-04-12T18:21:00.451Z"
}

SDK and cURL

cURL
TypeScript SDK

curl -X GET "https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.com/api/v1/exec/templates/preview?name=api-fetch-items&variables=%7B%22url%22%3A%22https%3A%2F%2Fapi.example.com%2Fitems%22%2C%22method%22%3A%22GET%22%7D" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

Create Custom Template

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

Persists a new user-supplied template under _hoody/templates/. The response echoes the metadata recorded for the template and the resolved on-disk path.

Request Body

The request body schema is open; no specific fields are documented by the server contract. Supply the template payload as a JSON object in the body.

Response

{
  "created": true,
  "name": "internal-sync",
  "path": "default/1/internal-sync.ts",
  "metadata": {
    "name": "internal-sync",
    "category": "internal",
    "tags": ["sync", "internal"],
    "description": "Internal sync script template",
    "params": ["batchSize", "dryRun"],
    "version": "1.0.0",
    "author": "team-platform"
  }
}

{
  "error": "Invalid parameter format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-04-12T18:21:00.451Z"
}

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-04-12T18:21:00.451Z"
}

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

{
  "error": "Template already exists",
  "code": "CONFLICT",
  "timestamp": "2025-04-12T18:21:00.451Z"
}

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-04-12T18:21:00.451Z"
}

SDK and cURL

cURL
TypeScript SDK

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

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

Generate From Template

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

Expands a template with the supplied variables and returns the generated code. Set saveFile to true and provide outputPath to persist the result to disk under /hoody/storage/hoody-exec/scripts/.

Request Body

Name	Type	Required	Description
`name`	string	Yes	Name of the template to expand.
`variables`	object	No	Map of placeholder name to value used during expansion.
`outputPath`	string	No	Destination path relative to `/hoody/storage/hoody-exec/scripts`, including the host/exec scope (for example, `default/1/fetch-items.ts`). Required when `saveFile` is `true`.
`saveFile`	boolean	No	When `true`, write the generated script to `outputPath`. Default `false`.

Response

{
  "generated": true,
  "template": "api-fetch-items",
  "code": "export async function main() {\n  const url = 'https://api.example.com/items';\n  const method = 'GET';\n  return await fetch(url, { method });\n}\n",
  "saved": true,
  "path": "default/1/fetch-items.ts",
  "variables": {
    "url": "https://api.example.com/items",
    "method": "GET"
  }
}

{
  "error": "Invalid parameter format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-04-12T18:21:00.451Z"
}

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-04-12T18:21:00.451Z"
}

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

{
  "error": "Template not found",
  "code": "NOT_FOUND",
  "timestamp": "2025-04-12T18:21:00.451Z"
}

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-04-12T18:21:00.451Z"
}

SDK and cURL

cURL
TypeScript SDK

curl -X POST "https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.com/api/v1/exec/templates/generate" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api-fetch-items",
    "variables": {
      "url": "https://api.example.com/items",
      "method": "GET"
    },
    "outputPath": "default/1/fetch-items.ts",
    "saveFile": true
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.exec.templates.generate({
  name: 'api-fetch-items',
  variables: {
    url: 'https://api.example.com/items',
    method: 'GET'
  },
  outputPath: 'default/1/fetch-items.ts',
  saveFile: true
});

Update Custom Template

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

Patches an existing custom template. Pass only the fields you want to change; the server merges metadata with the existing record and replaces code when supplied.

Parameters

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

Request Body

Name	Type	Required	Description
`code`	string	No	New source body for the template. Replaces the existing code on success.
`metadata`	object	No	Partial metadata patch; merged with the existing record.

Response

{
  "updated": true,
  "name": "internal-sync",
  "metadata": {
    "name": "internal-sync",
    "category": "internal",
    "tags": ["sync", "internal", "v2"],
    "description": "Internal sync script template (updated)",
    "params": ["batchSize", "dryRun", "timeoutMs"],
    "version": "1.1.0",
    "author": "team-platform"
  }
}

{
  "error": "Invalid parameter format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-04-12T18:21:00.451Z"
}

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

{
  "error": "Template not found",
  "code": "NOT_FOUND",
  "timestamp": "2025-04-12T18:21:00.451Z"
}

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-04-12T18:21:00.451Z"
}

SDK and cURL

cURL
TypeScript SDK

curl -X PUT "https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.com/api/v1/exec/templates/update-custom/internal-sync" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "export async function main() {\n  console.log(\"updated\");\n}\n",
    "metadata": {
      "version": "1.1.0",
      "tags": ["sync", "internal", "v2"]
    }
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.exec.templates.updateCustom('internal-sync', {
  code: 'export async function main() {\n  console.log("updated");\n}\n',
  metadata: {
    version: '1.1.0',
    tags: ['sync', 'internal', 'v2']
  }
});

Delete Custom Template

`DELETE /api/v1/exec/templates/delete-custom/{name}`

Removes a user-supplied 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": "internal-sync"
}

{
  "error": "Invalid parameter format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-04-12T18:21:00.451Z"
}

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

{
  "error": "Template not found",
  "code": "NOT_FOUND",
  "timestamp": "2025-04-12T18:21:00.451Z"
}

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-04-12T18:21:00.451Z"
}

SDK and cURL

cURL
TypeScript SDK

curl -X DELETE "https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.com/api/v1/exec/templates/delete-custom/internal-sync" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.exec.templates.deleteCustom('internal-sync');