The exec service provides cache management and shared state operations for scripts running inside a container. Use these endpoints to clear the execution VM cache (for example, after a deployment that changes script sources) or to read, write, and delete entries in the shared state store keyed by hostname. All endpoints are scoped to a single container via the exec-1 service URL template below.

Base URL template for all endpoints on this page: https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.icu

Clear Cache

POST /api/v1/exec/cache/clear

Clear the execution VM cache, the shared state, or both for a given hostname. The VM cache is keyed by hostname, so clearAll=true or a target hostname is required to purge VM entries. The deprecated scriptPath field is rejected by the server and returns HTTP 400.

This endpoint takes no parameters.

Request Body

Field	Type	Required	Default	Description
hostname	string	No	-	Hostname identifying the VM whose cache should be cleared.
scriptPath	string	No	-	DEPRECATED. Script-path-based clear returns HTTP 400. VM cache is keyed by hostname; use hostname or clearAll=true instead.
clearVm	boolean	No	true	Clear the VM cache.
clearState	boolean	No	false	Clear the shared state for the hostname.
clearAll	boolean	No	false	Clear cache and shared state for every hostname on the container.

Response

200

{
  "cleared": true,
  "vmCache": {
    "cleared": 3,
    "remaining": 0
  },
  "sharedState": {
    "cleared": 0,
    "remaining": 12
  }
}

400

{
  "error": "Invalid parameter format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {
    "field": "scriptPath",
    "issue": "scriptPath-based clear is no longer supported"
  }
}

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

Example

cURL

curl -X POST https://proj12345-cont67890-exec-1.us-east.containers.hoody.icu/api/v1/exec/cache/clear \
  -H "Content-Type: application/json" \
  -d '{"hostname":"node-app","clearVm":true,"clearState":false}'

SDK

await client.exec.cache.clear({
  hostname: "node-app",
  clearVm: true,
  clearState: false
});

Shared State

The shared state store is keyed by hostname and optionally by path. Use get to read a value, set to write (or merge into) a value, and clear to remove entries.

POST /api/v1/exec/shared-state/get

Retrieve the current shared state for a hostname and optional path. When no value exists at the requested path the response indicates exists: false and state is null. When the value exists, the response includes the arbitrary JSON state and its size (number of top-level keys).

This endpoint takes no parameters.

Request Body

Field	Type	Required	Default	Description
hostname	string	Yes	-	Hostname identifying the shared state namespace.
path	string	No	-	Optional dotted path to a sub-key within the hostname namespace.

Response

200

{
  "hostname": "node-app",
  "path": null,
  "exists": true,
  "state": {
    "counter": 42,
    "lastUpdated": "2024-01-15T10:30:00Z"
  },
  "size": 2
}

400

{
  "error": "Invalid parameter format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {
    "field": "hostname",
    "issue": "required field missing"
  }
}

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

Example

cURL

curl -X POST https://proj12345-cont67890-exec-1.us-east.containers.hoody.icu/api/v1/exec/shared-state/get \
  -H "Content-Type: application/json" \
  -d '{"hostname":"node-app"}'

SDK

await client.exec.state.get({
  hostname: "node-app"
});

POST /api/v1/exec/shared-state/set

Write a value into the shared state namespace for a hostname and optional path. Pass merge: true to deep-merge the supplied value into the existing object instead of replacing it.

This endpoint takes no parameters.

Request Body

Field	Type	Required	Default	Description
hostname	string	Yes	-	Hostname identifying the shared state namespace.
path	string	No	-	Optional dotted path to a sub-key within the hostname namespace.
value	string	Yes	-	Arbitrary JSON value to store.
merge	boolean	No	false	When true, deep-merge value into the existing state instead of replacing it.

Response

200

{
  "hostname": "node-app",
  "path": null,
  "updated": true,
  "merged": false,
  "size": 1
}

400

{
  "error": "Invalid parameter format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {
    "field": "value",
    "issue": "required field missing"
  }
}

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

Example

cURL

curl -X POST https://proj12345-cont67890-exec-1.us-east.containers.hoody.icu/api/v1/exec/shared-state/set \
  -H "Content-Type: application/json" \
  -d '{"hostname":"node-app","value":{"counter":43},"merge":true}'

SDK

await client.exec.state.set({
  hostname: "node-app",
  value: { counter: 43 },
  merge: true
});

POST /api/v1/exec/shared-state/clear

Remove entries from the shared state namespace. Provide path to clear a single sub-key, or clearAll: true to wipe every entry for the hostname.

This endpoint takes no parameters.

Request Body

Field	Type	Required	Default	Description
hostname	string	Yes	-	Hostname identifying the shared state namespace to clear.
path	string	No	-	Optional dotted path to a single sub-key to remove.
clearAll	boolean	No	false	When true, remove every entry for the hostname (ignores path).

Response

200

{
  "cleared": true,
  "count": 5,
  "remaining": 7
}

400

{
  "error": "Invalid parameter format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "details": {
    "field": "hostname",
    "issue": "required field missing"
  }
}

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

Example

cURL

curl -X POST https://proj12345-cont67890-exec-1.us-east.containers.hoody.icu/api/v1/exec/shared-state/clear \
  -H "Content-Type: application/json" \
  -d '{"hostname":"node-app","path":"counter","clearAll":false}'

SDK

await client.exec.state.clear({
  hostname: "node-app",
  path: "counter",
  clearAll: false
});