Dependency Management

Use these endpoints to inspect, verify, and install the npm modules available to a script running inside a container. The bundled list describes what is preinstalled in the container image, the check endpoint compares the modules required by a script against what is installed, and the install endpoint resolves and adds any missing modules on demand. The SDK types endpoint is a lookup aid for writing scripts: it inspects the installed hoody-sdk copy and returns the methods it exposes.

All requests target the container-scoped exec service. Hostname template: {projectId}-{containerId}-exec-1.{server}.containers.hoody.com.

List Bundled Dependencies

Returns the set of npm modules that are preinstalled in the container image, along with a flag indicating whether every module listed is currently available in the node_modules tree.

GET /api/v1/exec/dependencies/bundled

This endpoint takes no parameters.

cURL

curl -X GET "https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.com/api/v1/exec/dependencies/bundled" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

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.modules.listBundled();

200

{
  "total": 2,
  "packages": [
    {
      "name": "axios",
      "declaredVersion": "^1.18.1",
      "resolvedVersion": "1.18.1",
      "available": true,
      "description": "Promise-based HTTP client for making external API requests"
    },
    {
      "name": "lodash",
      "declaredVersion": "^4.18.1",
      "resolvedVersion": null,
      "available": false,
      "description": "Utility library — deep clone, merge, groupBy, debounce, and 300+ helpers"
    }
  ],
  "allAvailable": false
}

Field	Type	Required	Description
total	integer	Yes	Number of bundled packages listed.
packages[].name	string	Yes	npm package name.
packages[].declaredVersion	string	Yes	The semver range hoody-exec bundles.
packages[].resolvedVersion	string | null	Yes	The installed version scripts resolve, or null when it is not installed.
packages[].available	boolean	Yes	true when require(name) resolves from the scripts directory.
packages[].description	string	Yes	Short description of what the package provides.
allAvailable	boolean	Yes	true when every listed package is available.

400

{
  "error": "Malformed query string",
  "code": "ERROR_400",
  "timestamp": "2026-01-01T00:00:00.000Z"
}

Error Code	Title	Description	Resolution
ERROR_400	Bad request	The service answers 400 with this code; the message names the cause.	Percent-encoding failed to decode. Use valid %XX escapes.

500

{
  "error": "Failed to list bundled dependencies",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

Error Code	Title	Description	Resolution
ERROR_500	Internal server error	The service answers 500 with this code; the message names the cause. Other messages on this status are composed at runtime and are not listed here.	—

429

Error Code	Title	Description	Resolution
ERROR_429	Too many requests	The service answers 429 with this code; the message names the cause. Messages: “Too many distinct clients”, “Too many requests”.	—

Check Dependencies

Compares the modules required by a script (either supplied directly as a modules array, or inferred from the script code via require / import parsing) against the modules currently installed in the container. The response distinguishes installed packages, missing packages, and may include per-module diagnostic details.

POST /api/v1/exec/dependencies/check

This endpoint takes no parameters.

Request Body

The body must match one of two shapes: provide code to scan script source for imports, or provide modules as an array of module specs to check. Supplying both fields is allowed, but at least one of the two must be present.

Field	Type	Required	Description
code	string	Yes (one of code or modules)	Script source whose imports are checked. Used when modules is not given.
modules	array of strings	Yes (one of code or modules)	Module specs to check (e.g. "lodash", "axios@1.2.3"). When omitted or null, the modules imported by code are checked.

cURL

curl -X POST "https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.com/api/v1/exec/dependencies/check" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "const _ = require(\"lodash\"); const axios = require(\"axios\");",
    "modules": ["lodash", "axios"]
  }'

TypeScript SDK

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.modules.test({
  code: 'const _ = require("lodash"); const axios = require("axios");',
  modules: ['lodash', 'axios']
});

200

{
  "total": 2,
  "installed": [
    { "name": "lodash", "version": "4.17.21" }
  ],
  "missing": [
    "axios"
  ],
  "message": "1 of 2 modules are installed; 1 missing."
}

400

{
  "error": "code or modules array is required",
  "code": "ERROR_400",
  "timestamp": "2026-01-01T00:00:00.000Z"
}

Error Code	Title	Description	Resolution
ERROR_400	Bad request	The service answers 400 with this code; the message names the cause. Messages: “code or modules array is required”, “Malformed query string” (Percent-encoding failed to decode. Use valid %XX escapes.), “Invalid JSON body” (Ensure the request body is valid JSON. Example: a backslash followed by a backtick is not a valid JSON escape.), “Request aborted before the body was fully received”. Other messages on this status are composed at runtime and are not listed here.	—

500

{
  "error": "Failed to check dependencies",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T10:30:40.000Z",
  "details": {}
}

Error Code	Title	Description	Resolution
ERROR_500	Internal server error	The service answers 500 with this code; the message names the cause. Other messages on this status are composed at runtime and are not listed here.	—

429

Error Code	Title	Description	Resolution
ERROR_429	Too many requests	The service answers 429 with this code; the message names the cause. Messages: “Too many distinct clients”, “Too many requests”.	—

413

Error Code	Title	Description	Resolution
ERROR_413	Payload too large	The service answers 413 with this code; the message names the cause.	—

408

Error Code	Title	Description	Resolution
ERROR_408	Request timeout	The service answers 408 with this code; the message names the cause.	—

Note

The 200 response can take one of two shapes. When only one of code or modules is supplied, the response includes a message field summarizing the check. When both are supplied, the response additionally includes a details array with per-module diagnostic information.

Install Dependencies

Resolves and installs the specified npm module(s) into the container’s node_modules directory. Pass either a single module spec (e.g. lodash, axios@1.2.3) or an array of specs to install multiple modules in sequence. Already-present modules are reported as already-installed unless force is set to true.

POST /api/v1/exec/dependencies/install

This endpoint takes no parameters.

Request Body

Field	Type	Required	Default	Description
modules	string | array of strings	Yes		One npm module spec (e.g. "lodash", "axios@1.2.3") or an array of specs. Array form installs every module in sequence.
force	boolean	No	false	When true, reinstall modules that are already present instead of reporting them as already-installed.

cURL

curl -X POST "https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.com/api/v1/exec/dependencies/install" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "modules": ["lodash", "axios@1.6.2"],
    "force": false
  }'

TypeScript SDK

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.modules.install({
  modules: ['lodash', 'axios@1.6.2'],
  force: false
});

200

{
  "total": 2,
  "installed": 2,
  "failed": 0,
  "installedModules": ["lodash", "axios"],
  "failedModules": [],
  "details": [
    { "module": "lodash", "status": "installed", "version": "4.17.21" },
    { "module": "axios", "status": "installed", "version": "1.6.2" }
  ]
}

400

{
  "error": "modules (string or array) is required",
  "code": "ERROR_400",
  "timestamp": "2026-01-01T00:00:00.000Z"
}

Error Code	Title	Description	Resolution
ERROR_400	Bad request	The service answers 400 with this code; the message names the cause. Messages: “modules (string or array) is required”, “Malformed query string” (Percent-encoding failed to decode. Use valid %XX escapes.), “Invalid JSON body” (Ensure the request body is valid JSON. Example: a backslash followed by a backtick is not a valid JSON escape.), “Request aborted before the body was fully received”. Other messages on this status are composed at runtime and are not listed here.	—

500

{
  "error": "Failed to install dependencies",
  "code": "ERROR_500",
  "timestamp": "2025-01-15T10:30:50.000Z",
  "details": {}
}

Error Code	Title	Description	Resolution
ERROR_500	Internal server error	The service answers 500 with this code; the message names the cause. Other messages on this status are composed at runtime and are not listed here.	—

503

{
  "error": "npm registry unavailable",
  "code": "ERROR_503",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "details": {}
}

429

Error Code	Title	Description	Resolution
ERROR_429	Too many requests	The service answers 429 with this code; the message names the cause. Messages: “Too many distinct clients”, “Too many requests”.	—

413

Error Code	Title	Description	Resolution
ERROR_413	Payload too large	The service answers 413 with this code; the message names the cause.	—

408

Error Code	Title	Description	Resolution
ERROR_408	Request timeout	The service answers 408 with this code; the message names the cause.	—

Caution

The 503 response indicates the upstream npm registry could not be reached. The operation is safe to retry once network connectivity is restored.

Look Up Hoody SDK Methods

Look up hoody-sdk methods in the copy of the SDK that scripts load (the one in the scripts directory’s node_modules). This is a lookup aid for writing scripts, not a dependency check: it inspects the installed SDK and returns the methods it exposes, optionally filtered by kit, free-text query, or limited in count. Use kit to scope the result to a single client property (for example files, api, exec, sqlite), use q to find methods whose path, name, or summary contain every word, and use raw to also fetch the .d.ts source of the matched methods.

GET /api/v1/exec/sdk-types

Parameters

Name	In	Type	Required	Description
kit	query	string	No	Kit to list: a client property (files, api, exec, sqlite, …), or client for the client’s own methods (withContainer, login, …). Any letter case. An unknown kit is a 404 with details.kits.
q	query	string	No	Words, all of which must appear in the method’s path, name or summary (any letter case).
limit	query	integer	No	Most methods to return, 1 to 100 (default 20). total counts every match.
raw	query	string	No	When true, also return the .d.ts text of the files declaring the returned methods (dts, at most 256 KB). Needs kit or q. Accepted literal values: true, false, 1, 0 (default "false").

cURL

curl -X GET "https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.com/api/v1/exec/sdk-types?kit=files&limit=20" \
  -H "Authorization: Bearer <token>"

TypeScript SDK

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.sdkTypes.list({ kit: 'files', limit: 20 });

200

{
  "sdkVersion": "1.18.1",
  "kits": [
    { "name": "files", "methods": 12 },
    { "name": "api", "methods": 84 },
    { "name": "exec", "methods": 9 },
    { "name": "sqlite", "methods": 18 }
  ],
  "total": 12,
  "truncated": false,
  "methods": [
    {
      "kit": "files",
      "path": "hoody.files",
      "method": "upload",
      "signature": "upload(file: Blob | string, options?: { … }): Promise<UploadResult>",
      "summary": "Upload a file to the container's filesystem.",
      "example": "await hoody.files.upload(file)",
      "file": "dist/files.d.ts",
      "params": [
        {
          "name": "file",
          "type": "Blob | string",
          "optional": false
        },
        {
          "name": "options",
          "type": "{ … }",
          "optional": true
        }
      ]
    }
  ],
  "message": "OK"
}

Field	Type	Required	Description
sdkVersion	string | null	Yes	Version of the hoody-sdk copy in <scripts>/node_modules, the one scripts load.
kits	array	Yes	Every kit of the client with its method count. A kit is the client property the methods hang under (files, api, exec, …); client holds the client’s own methods (withContainer, login, …).
kits[].name	string	Yes	The kit name (a client property).
kits[].methods	integer	Yes	Number of methods on the kit.
total	integer	Yes	Methods matching kit and q (0 when neither is given).
truncated	boolean	Yes	More methods matched than limit returned.
methods	array	Yes	Matching methods, best match first: a whole-name match, then a name containing a word, then the path, then the summary. An overloaded method has one entry per signature; methods the SDK adds by module augmentation (files.readText, …) are included.
methods[].kit	string	Yes	The kit the method hangs under.
methods[].path	string	Yes	What the method is called on: hoody.files, hoody.api.containers, hoody for the client.
methods[].method	string	Yes	The method name.
methods[].signature	string	Yes	The declaration, whitespace collapsed, at most 1500 characters. The URL-template and request-option parameters every kit method ends with are shown as { … }.
methods[].summary	string	Yes	First paragraph of the method’s doc comment (empty when it has none).
methods[].example	string	Yes	The doc comment’s @example, else a call built from the required parameters; (…) for arguments the index cannot fill.
methods[].file	string	Yes	The declaring .d.ts, relative to the package directory.
methods[].params	array	Yes	The parameters in order.
methods[].params[].name	string	Yes	The declared parameter name.
methods[].params[].type	string	Yes	The declared type, whitespace collapsed, at most 200 characters.
methods[].params[].optional	boolean	Yes	True for an optional or defaulted parameter.
dts	string	No	With raw=true: the .d.ts files declaring the returned methods, each headed by // <file>, at most 256 KB.
dtsFiles	array of strings	No	With raw=true: the files in dts.
dtsOmitted	integer	No	With raw=true: declaring files left out of dts to stay under 256 KB.
message	string	Yes	A short status message.

400

{
  "error": "raw must be true or false",
  "code": "ERROR_400",
  "timestamp": "2026-01-01T00:00:00.000Z"
}

Error Code	Title	Description	Resolution
ERROR_400	Bad request	The service answers 400 with this code; the message names the cause. Messages: “raw must be true or false”, “raw needs kit or q: the whole SDK is too large to return”, “Malformed query string” (Percent-encoding failed to decode. Use valid %XX escapes.). Other messages on this status are composed at runtime and are not listed here.	—

404

{
  "error": "hoody-sdk is not installed in the scripts directory (node_modules/hoody-sdk)",
  "code": "ERROR_404",
  "timestamp": "2026-01-01T00:00:00.000Z"
}

Error Code	Title	Description	Resolution
ERROR_404	Not found	The service answers 404 with this code; the message names the cause. Other messages on this status are composed at runtime and are not listed here.	—

429

{
  "error": "Too many distinct clients",
  "code": "ERROR_429",
  "timestamp": "2026-01-01T00:00:00.000Z",
  "retryAfter": 60
}

Error Code	Title	Description	Resolution
ERROR_429	Too many requests	The service answers 429 with this code; the message names the cause. Messages: “Too many distinct clients”, “Too many requests”.	—

500

{
  "error": "Internal server error",
  "code": "ERROR_500",
  "timestamp": "2026-01-01T00:00:00.000Z"
}

Error Code	Title	Description	Resolution
ERROR_500	Internal server error	The service answers 500 with this code; the message names the cause. Other messages on this status are composed at runtime and are not listed here.	—