# Script Management

**Page:** api/exec/script-management

[Download Raw Markdown](./api/exec/script-management.md)

---

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



# 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.



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


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


```json
{
  "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**



Success.

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


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


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



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


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


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



**Response statuses**



Success.

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


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


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


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


```json
{
  "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.



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


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


```json
{
  "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**



Success.


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


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



```bash
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
  }'
```


```ts
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
  }
});
```


```json
{
  "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**



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.


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


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


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


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



```bash
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
  }'
```


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


```json
{
  "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**



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.


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


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


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


```json
{
  "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/&#123;execId&#125;/ 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. |



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


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


```json
{
  "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**



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`.


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


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


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


```json
{
  "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/&#123;execId&#125;/ 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. |



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


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


```json
{
  "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**



Success.


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


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


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


```json
{
  "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/&#123;execId&#125;/ 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. |



```bash
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
  }'
```


```ts
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
  }
});
```


```json
{
  "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**



Success.


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


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


```json
{
  "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/&#123;execId&#125;/ 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. |



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


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


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



**Response statuses**



Success.


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


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


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


```json
{
  "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/&#123;execId&#125;/ 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. |



```bash
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
  }'
```


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


```json
{
  "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**



Success.


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


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


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


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


```json
{
  "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/&#123;execId&#125;/ 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. |



```bash
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
  }'
```


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


```json
{
  "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**



Success.


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


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


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


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




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}/`.