Script Management

The Script Management API lets you read, write, delete, list, and organize executable scripts and their associated metadata. Endpoints cover enumerating available exec contexts, reading and writing script source files, bulk and per-file magic-comment operations, and moving files within the script tree.

Use these endpoints to integrate script lifecycle management into your tooling: discover what scripts exist, inspect or modify their contents, manage declarative metadata (magic comments), and reorganize files programmatically.

---

Exec IDs

GET /api/v1/exec/list

List all exec IDs, including SDK- and custom-sourced scripts. Returns the catalog of executable contexts available in the current environment along with a summary of counts per type.

This endpoint takes no parameters.

cURL

curl -X GET https://api.hoody.com/api/v1/exec/list \
  -H "Authorization: Bearer <token>"

SDK

const result = await client.exec.ids.list();

Response (200)

{
  "execIds": [
    {
      "id": "exec_5f8a3b2c9d1e4f7a",
      "type": "sdk",
      "source_url": "https://sdk.hoody.com/v1.2.0",
      "files": 42
    },
    {
      "id": "exec_7c9d8e1f2a3b4c5d",
      "type": "custom",
      "files": 12
    }
  ],
  "total": 2,
  "summary": {
    "sdk": 1,
    "custom": 1
  }
}

Response statuses

200

Success.

{
  "execIds": [
    {
      "id": "exec_5f8a3b2c9d1e4f7a",
      "type": "sdk",
      "source_url": "https://sdk.hoody.com/v1.2.0",
      "files": 42
    }
  ],
  "total": 1,
  "summary": {
    "sdk": 1,
    "custom": 0
  }
}

400

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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": "2024-01-15T10:30:00.000Z",
  "details": {}
}

---

Magic Comments

Magic comments are inline directives placed at the top of a script that control execution behavior, logging, CORS, AI integration, and metadata. The endpoints below let you read, schema-inspect, and update these directives on a per-file or bulk basis.

GET /api/v1/exec/magic-comments/read

Read the parsed magic comments for a single script. Sensitive values such as tokens are redacted in the response.

Parameters

Name	In	Type	Required	Description
path	query	string	Yes	Path query parameter

cURL

curl -X GET "https://api.hoody.com/api/v1/exec/magic-comments/read?path=scripts/hello.ts" \
  -H "Authorization: Bearer <token>"

SDK

const result = await client.exec.magic.read({ path: "scripts/hello.ts" });

Response (200)

{
  "path": "scripts/hello.ts",
  "comments": {
    "mode": "sync",
    "timeout": 30000,
    "logging": {
      "level": "info"
    }
  }
}

Response statuses

200

Success.

{
  "path": "scripts/hello.ts",
  "comments": {
    "mode": "sync",
    "timeout": 30000
  }
}

400

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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

403

{
  "error": "FORBIDDEN",
  "code": "FORBIDDEN",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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

404

{
  "error": "NOT_FOUND",
  "code": "NOT_FOUND",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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": "2024-01-15T10:30:00.000Z",
  "details": {}
}

---

GET /api/v1/exec/magic-comments/schema

Retrieve the schema document describing every supported magic comment directive, including field types, defaults per context, enums, ranges, and categorizations.

This endpoint takes no parameters.

cURL

curl -X GET https://api.hoody.com/api/v1/exec/magic-comments/schema \
  -H "Authorization: Bearer <token>"

SDK

const result = await client.exec.magic.getSchema();

Response (200)

{
  "schema_version": "1.0.0",
  "total_fields": 18,
  "parse_window_lines": 50,
  "unknown_keys_behavior": "warn",
  "defaults_context": {
    "when_omitted": "runtime",
    "runtime": "server-side execution",
    "sdk_import": "client-side import"
  },
  "source_of_truth": {
    "interface": "MagicCommentMap",
    "parser": "scripts/magic-comments/parser.ts",
    "runtime_defaults": "scripts/magic-comments/defaults.ts",
    "sdk_import_defaults": "packages/sdk/src/magic.ts"
  },
  "categories": {
    "execution": ["mode", "timeout"],
    "logging": ["level", "destination"],
    "cors": ["origin", "credentials"],
    "ai": ["model", "temperature"],
    "metadata": ["label", "tags"]
  },
  "fields": [
    {
      "key": "mode",
      "directive": "@hoody-mode",
      "category": "execution",
      "type": "string",
      "enum_values": ["sync", "async", "stream"],
      "description": "Execution mode of the script",
      "defaults": {
        "when_omitted": "sync",
        "runtime": "sync",
        "sdk_import": "sync"
      }
    }
  ]
}

Response statuses

200

Success.

400

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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": "2024-01-15T10:30:00.000Z",
  "details": {}
}

---

POST /api/v1/exec/magic-comments/bulk-update

Update magic comments across every script in a directory in a single request. Supports a dry_run mode that previews the affected files and proposed changes without modifying them.

This endpoint takes no parameters.

Request body

Name	Type	Required	Default	Description
directory	string	No	—	Directory
execId	string	No	—	Exec Id
comments	string	No	—	Comments
extension	string	No	".ts"	Extension
recursive	boolean	No	true	Recursive
dry_run	boolean	No	false	Dry_run

cURL

curl -X POST https://api.hoody.com/api/v1/exec/magic-comments/bulk-update \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "directory": "scripts/handlers",
    "execId": "exec_5f8a3b2c9d1e4f7a",
    "comments": "@hoody-mode async\n@hoody-timeout 60000",
    "extension": ".ts",
    "recursive": true,
    "dry_run": true
  }'

SDK

const result = await client.exec.magic.bulkUpdate({
  data: {
    directory: "scripts/handlers",
    execId: "exec_5f8a3b2c9d1e4f7a",
    comments: "@hoody-mode async\n@hoody-timeout 60000",
    extension: ".ts",
    recursive: true,
    dry_run: true
  }
});

Response (200)

{
  "dry_run": true,
  "directory": "scripts/handlers",
  "execId": "exec_5f8a3b2c9d1e4f7a",
  "recursive": true,
  "comments": {
    "mode": "async",
    "timeout": 60000
  },
  "would_affect": {
    "total": 3,
    "files": [
      {
        "file": "scripts/handlers/a.ts",
        "current": { "mode": "sync" },
        "proposed": { "mode": "async", "timeout": 60000 },
        "changes": ["mode", "timeout"]
      },
      {
        "file": "scripts/handlers/b.ts",
        "current": null,
        "proposed": { "mode": "async", "timeout": 60000 },
        "changes": ["mode", "timeout"]
      },
      {
        "file": "scripts/handlers/c.ts",
        "error": "permission denied"
      }
    ]
  },
  "message": "Preview only - set dry_run=false to apply changes"
}

Response statuses

200

Success. The discriminator is the message field: "Preview only - set dry_run=false to apply changes" indicates a dry run, while "Magic comments updated successfully" indicates an applied change.

400

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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

403

{
  "error": "FORBIDDEN",
  "code": "FORBIDDEN",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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

404

{
  "error": "NOT_FOUND",
  "code": "NOT_FOUND",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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": "2024-01-15T10:30:00.000Z",
  "details": {}
}

---

PUT /api/v1/exec/magic-comments/update

Update the magic comments block of a single script file. Supports a dry_run mode that returns the current and proposed states plus a list of change keys without writing.

This endpoint takes no parameters.

Request body

Name	Type	Required	Default	Description
path	string	Yes	—	Path
comments	string	No	—	Comments
dry_run	boolean	No	false	Dry_run

cURL

curl -X PUT https://api.hoody.com/api/v1/exec/magic-comments/update \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "scripts/handlers/a.ts",
    "comments": "@hoody-mode async\n@hoody-timeout 60000",
    "dry_run": true
  }'

SDK

const result = await client.exec.magic.updateHandler({
  data: {
    path: "scripts/handlers/a.ts",
    comments: "@hoody-mode async\n@hoody-timeout 60000",
    dry_run: true
  }
});

Response (200)

{
  "dry_run": true,
  "path": "scripts/handlers/a.ts",
  "current": {
    "mode": "sync"
  },
  "proposed": {
    "mode": "async",
    "timeout": 60000
  },
  "changes": ["mode", "timeout"],
  "message": "Preview only - set dry_run=false to apply changes"
}

Response statuses

200

Success. The discriminator is the message field: "Preview only - set dry_run=false to apply changes" indicates a dry run, while "Magic comments updated successfully" indicates an applied change.

400

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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

403

{
  "error": "FORBIDDEN",
  "code": "FORBIDDEN",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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

404

{
  "error": "NOT_FOUND",
  "code": "NOT_FOUND",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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": "2024-01-15T10:30:00.000Z",
  "details": {}
}

---

Scripts

The script file operations cover the full lifecycle: discover files, read their contents and metadata, create or update them, move them within the tree, and delete them.

GET /api/v1/exec/scripts/list

List scripts in a directory. Supports filtering by label, tag, mode, enabled state, websocket usage, and includes an option to recurse into subdirectories and parse magic comments for each entry.

Parameters

Name	In	Type	Required	Description
dir	query	string	No	Dir query parameter
filter	query	string	No	Filter query parameter
metadata	query	string	No	Metadata query parameter
label	query	string	No	Label query parameter
tags	query	string	No	Tags query parameter
mode	query	string	No	Mode query parameter
enabled	query	string	No	Enabled query parameter
websocket	query	string	No	Websocket query parameter
recursive	query	string	No	Recursive query parameter
include_comments	query	string	No	Include_comments query parameter
execId	query	string	No	Optional execution scope. When provided, relative paths resolve under default/{execId}/ unless subdomain is also set. Query value takes precedence over body.
exec_id	query	string	No	Alias for execId (snake_case).
subdomain	query	string	No	Optional subdomain namespace used with execId for path resolution.

cURL

curl -X GET "https://api.hoody.com/api/v1/exec/scripts/list?dir=scripts/handlers&recursive=true&include_comments=true" \
  -H "Authorization: Bearer <token>"

SDK

const result = await client.exec.scripts.list({
  dir: "scripts/handlers",
  recursive: "true",
  include_comments: "true"
});

Response (200)

{
  "directory": "scripts/handlers",
  "count": 3,
  "recursive": true,
  "filters": {
    "label": "",
    "tags": "",
    "mode": "",
    "enabled": "",
    "websocket": ""
  },
  "scripts": [
    {
      "name": "a.ts",
      "path": "scripts/handlers/a.ts",
      "isDirectory": false
    },
    {
      "name": "b.ts",
      "path": "scripts/handlers/b.ts",
      "isDirectory": false
    },
    {
      "name": "sub",
      "path": "scripts/handlers/sub",
      "isDirectory": true
    }
  ]
}

Response statuses

200

Success. The response shape depends on the request: filtered/recursive listing returns the rich shape with filters and isDirectory flags; a minimal listing returns only directory, count, and scripts.

400

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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

403

{
  "error": "FORBIDDEN",
  "code": "FORBIDDEN",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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

404

{
  "error": "NOT_FOUND",
  "code": "NOT_FOUND",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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": "2024-01-15T10:30:00.000Z",
  "details": {}
}

---

GET /api/v1/exec/scripts/read

Read the full content of a script along with its parsed magic comments, resolved absolute path, and filesystem metadata.

Parameters

Name	In	Type	Required	Description
path	query	string	Yes	Path query parameter
execId	query	string	No	Optional execution scope. When provided, relative paths resolve under default/{execId}/ unless subdomain is also set. Query value takes precedence over body.
exec_id	query	string	No	Alias for execId (snake_case).
subdomain	query	string	No	Optional subdomain namespace used with execId for path resolution.

cURL

curl -X GET "https://api.hoody.com/api/v1/exec/scripts/read?path=scripts/handlers/a.ts" \
  -H "Authorization: Bearer <token>"

SDK

const result = await client.exec.scripts.read({ path: "scripts/handlers/a.ts" });

Response (200)

{
  "path": "scripts/handlers/a.ts",
  "resolvedPath": "/var/hoody/exec/exec_5f8a3b2c9d1e4f7a/scripts/handlers/a.ts",
  "content": "export default async function handler(req) {\n  return { ok: true };\n}\n",
  "magicComments": {
    "mode": "async",
    "timeout": 30000
  },
  "metadata": {
    "size": 1280,
    "created": "2024-01-10T08:15:30.000Z",
    "modified": "2024-01-15T10:30:00.000Z",
    "isDirectory": false,
    "extension": ".ts"
  }
}

Response statuses

200

Success.

400

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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

403

{
  "error": "FORBIDDEN",
  "code": "FORBIDDEN",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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

404

{
  "error": "NOT_FOUND",
  "code": "NOT_FOUND",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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": "2024-01-15T10:30:00.000Z",
  "details": {}
}

---

POST /api/v1/exec/scripts/write

Create a new script or overwrite an existing one. By default, missing parent directories are created automatically and the script is validated before being persisted. The response includes a schedule object describing any scheduling action that should follow (for example, enabling a new script in the exec environment).

Parameters

Name	In	Type	Required	Description
execId	query	string	No	Optional execution scope. When provided, relative paths resolve under default/{execId}/ unless subdomain is also set. Query value takes precedence over body.
exec_id	query	string	No	Alias for execId (snake_case).
subdomain	query	string	No	Optional subdomain namespace used with execId for path resolution.

Request body

Name	Type	Required	Default	Description
path	string	Yes	—	Path
content	string	Yes	—	Content
createDirs	boolean	No	true	Create Dirs
validate	boolean	No	true	Validate
execId	string	No	—	Optional execution scope in request body. Query execId/exec_id takes precedence when both are provided.
exec_id	string	No	—	Alias for execId (snake_case).
subdomain	string	No	—	Optional subdomain namespace used with execId for path resolution.

cURL

curl -X POST "https://api.hoody.com/api/v1/exec/scripts/write" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "scripts/handlers/a.ts",
    "content": "export default async function handler(req) {\n  return { ok: true };\n}\n",
    "createDirs": true,
    "validate": true
  }'

SDK

const result = await client.exec.scripts.write({
  data: {
    path: "scripts/handlers/a.ts",
    content: "export default async function handler(req) {\n  return { ok: true };\n}\n",
    createDirs: true,
    validate: true
  }
});

Response (200)

{
  "path": "scripts/handlers/a.ts",
  "resolvedPath": "/var/hoody/exec/exec_5f8a3b2c9d1e4f7a/scripts/handlers/a.ts",
  "created": true,
  "updated": false,
  "size": 1280,
  "modified": "2024-01-15T10:30:00.000Z",
  "validated": true,
  "env": {
    "API_KEY": "<redacted>"
  },
  "schedule": {
    "action": "enable",
    "reason": "New script detected"
  }
}

Response statuses

200

Success.

400

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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

403

{
  "error": "FORBIDDEN",
  "code": "FORBIDDEN",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

---

DELETE /api/v1/exec/scripts/delete

Delete a script from the file system. The confirm flag can be supplied to assert intent for safety; without it, the server may reject the request depending on policy.

Parameters

Name	In	Type	Required	Description
path	query	string	Yes	Path query parameter
confirm	query	string	No	Confirm query parameter
execId	query	string	No	Optional execution scope. When provided, relative paths resolve under default/{execId}/ unless subdomain is also set. Query value takes precedence over body.
exec_id	query	string	No	Alias for execId (snake_case).
subdomain	query	string	No	Optional subdomain namespace used with execId for path resolution.

cURL

curl -X DELETE "https://api.hoody.com/api/v1/exec/scripts/delete?path=scripts/handlers/a.ts&confirm=true" \
  -H "Authorization: Bearer <token>"

SDK

const result = await client.exec.scripts.delete({
  path: "scripts/handlers/a.ts",
  confirm: "true"
});

Response (200)

{
  "deleted": true,
  "path": "scripts/handlers/a.ts",
  "resolvedPath": "/var/hoody/exec/exec_5f8a3b2c9d1e4f7a/scripts/handlers/a.ts",
  "size": 1280
}

Response statuses

200

Success.

400

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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

403

{
  "error": "FORBIDDEN",
  "code": "FORBIDDEN",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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

404

{
  "error": "NOT_FOUND",
  "code": "NOT_FOUND",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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": "2024-01-15T10:30:00.000Z",
  "details": {}
}

---

POST /api/v1/exec/scripts/move

Rename or relocate a script within the file tree. Returns both the requested and resolved source/destination paths along with the file size.

Parameters

Name	In	Type	Required	Description
execId	query	string	No	Optional execution scope. When provided, relative paths resolve under default/{execId}/ unless subdomain is also set. Query value takes precedence over body.
exec_id	query	string	No	Alias for execId (snake_case).
subdomain	query	string	No	Optional subdomain namespace used with execId for path resolution.

Request body

Name	Type	Required	Default	Description
from	string	Yes	—	From
to	string	Yes	—	To
overwrite	boolean	No	false	Overwrite
execId	string	No	—	Optional execution scope in request body. Query execId/exec_id takes precedence when both are provided.
exec_id	string	No	—	Alias for execId (snake_case).
subdomain	string	No	—	Optional subdomain namespace used with execId for path resolution.

cURL

curl -X POST "https://api.hoody.com/api/v1/exec/scripts/move" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "scripts/handlers/a.ts",
    "to": "scripts/handlers/renamed/a.ts",
    "overwrite": false
  }'

SDK

const result = await client.exec.scripts.move({
  data: {
    from: "scripts/handlers/a.ts",
    to: "scripts/handlers/renamed/a.ts",
    overwrite: false
  }
});

Response (200)

{
  "moved": true,
  "from": "scripts/handlers/a.ts",
  "to": "scripts/handlers/renamed/a.ts",
  "resolvedFrom": "/var/hoody/exec/exec_5f8a3b2c9d1e4f7a/scripts/handlers/a.ts",
  "resolvedTo": "/var/hoody/exec/exec_5f8a3b2c9d1e4f7a/scripts/handlers/renamed/a.ts",
  "size": 1280
}

Response statuses

200

Success.

400

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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

403

{
  "error": "FORBIDDEN",
  "code": "FORBIDDEN",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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

404

{
  "error": "NOT_FOUND",
  "code": "NOT_FOUND",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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

409

{
  "error": "CONFLICT",
  "code": "CONFLICT",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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": "2024-01-15T10:30:00.000Z",
  "details": {}
}

---

POST /api/v1/exec/scripts/tree

Get a hierarchical tree representation of the script directory. Depth and per-node metadata are controllable.

Parameters

Name	In	Type	Required	Description
execId	query	string	No	Optional execution scope. When provided, relative paths resolve under default/{execId}/ unless subdomain is also set. Query value takes precedence over body.
exec_id	query	string	No	Alias for execId (snake_case).
subdomain	query	string	No	Optional subdomain namespace used with execId for path resolution.

Request body

Name	Type	Required	Default	Description
baseDir	string	No	""	Base Dir
maxDepth	integer	No	10	Max Depth
includeMetadata	boolean	No	false	Include Metadata
execId	string	No	—	Optional execution scope in request body. Query execId/exec_id takes precedence when both are provided.
exec_id	string	No	—	Alias for execId (snake_case).
subdomain	string	No	—	Optional subdomain namespace used with execId for path resolution.

cURL

curl -X POST "https://api.hoody.com/api/v1/exec/scripts/tree" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "baseDir": "scripts/handlers",
    "maxDepth": 5,
    "includeMetadata": true
  }'

SDK

const result = await client.exec.scripts.getTree({
  data: {
    baseDir: "scripts/handlers",
    maxDepth: 5,
    includeMetadata: true
  }
});

Response (200)

{
  "baseDir": "scripts/handlers",
  "tree": [
    {
      "name": "a.ts",
      "path": "scripts/handlers/a.ts",
      "type": "file",
      "size": 1280,
      "children": []
    },
    {
      "name": "sub",
      "path": "scripts/handlers/sub",
      "type": "directory",
      "children": [
        {
          "name": "b.ts",
          "path": "scripts/handlers/sub/b.ts",
          "type": "file",
          "size": 980,
          "children": []
        }
      ]
    }
  ]
}

Response statuses

200

Success.

400

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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

403

{
  "error": "FORBIDDEN",
  "code": "FORBIDDEN",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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

404

{
  "error": "NOT_FOUND",
  "code": "NOT_FOUND",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {}
}

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": "2024-01-15T10:30:00.000Z",
  "details": {}
}

Tip

The execId / exec_id / subdomain triple is shared across all script operations. When both query and body values are supplied, the query value always wins. Use subdomain to scope to a tenant or team namespace, and use execId to target a specific execution context — relative paths will then resolve under default/{execId}/.