Cache & Shared State

The execution API exposes two complementary state surfaces: a VM cache keyed by hostname that accelerates script execution, and a shared state store that scripts can read, write, merge, and clear across runs. Use these endpoints to invalidate cached VMs, reset persistent state between deployments, or coordinate values that multiple scripts on the same hostname must share.

Clear VM cache

`POST /api/v1/exec/cache/clear`

Invalidate the VM cache for a hostname and optionally wipe its associated shared state. By default, the VM cache is cleared and shared state is preserved.

Request body

Field	Type	Required	Default	Description
`hostname`	string	No	—	Hostname whose VM cache entry should be cleared.
`scriptPath`	string	No	—	Deprecated. `scriptPath`-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 for the given hostname.
`clearState`	boolean	No	`false`	Also clear shared state for the given hostname.
`clearAll`	boolean	No	`false`	Clear VM cache and shared state for every hostname.

curl -X POST https://api.hoody.com/v1/exec/cache/clear \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "api.example.com",
    "clearVm": true,
    "clearState": false
  }'

await client.exec.cache.clear({
  hostname: "api.example.com",
  clearVm: true,
  clearState: false,
});

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

{
  "error": "Invalid input: scriptPath is no longer supported",
  "code": "VALIDATION_ERROR",
  "timestamp": "2026-01-15T10:42:13.214Z",
  "details": {
    "field": "scriptPath"
  }
}

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Invalid input	Request parameters failed validation (e.g. supplying the deprecated `scriptPath` field)	Check parameter format and requirements; use `hostname` or `clearAll=true` instead of `scriptPath`

{
  "error": "Failed to clear cache",
  "code": "ERROR_500",
  "timestamp": "2026-01-15T10:42:13.214Z",
  "details": {
    "reason": "storage backend unavailable"
  }
}

Set shared state

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

Write a value into the shared state store for a given hostname and path. When merge is true, the value is shallow-merged into the existing state object instead of replacing it. The value field accepts an arbitrary JSON value (object, array, string, number, boolean, or null).

Request body

Field	Type	Required	Default	Description
`hostname`	string	Yes	—	Hostname that owns the state entry.
`path`	string	No	—	Dot-notation path under which the value is stored.
`value`	any	Yes	—	Arbitrary JSON value to store (object, array, string, number, boolean, or `null`).
`merge`	boolean	No	`false`	When `true`, shallow-merge `value` into the existing state at `path` instead of replacing it.

curl -X POST https://api.hoody.com/v1/exec/shared-state/set \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "api.example.com",
    "path": "deploy",
    "value": {
      "lastSha": "a1b2c3d4e5f6",
      "timestamp": "2026-01-15T10:30:00Z"
    },
    "merge": false
  }'

await client.exec.state.set({
  hostname: "api.example.com",
  path: "deploy",
  value: {
    lastSha: "a1b2c3d4e5f6",
    timestamp: "2026-01-15T10:30:00Z",
  },
  merge: false,
});

{
  "hostname": "api.example.com",
  "path": "deploy",
  "updated": true,
  "merged": false,
  "size": 78
}

{
  "error": "Missing required field: value",
  "code": "VALIDATION_ERROR",
  "timestamp": "2026-01-15T10:42:13.214Z",
  "details": {
    "field": "value"
  }
}

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Invalid input	Request parameters failed validation	Check parameter format and requirements; ensure `hostname` and `value` are present

{
  "error": "Failed to persist shared state",
  "code": "ERROR_500",
  "timestamp": "2026-01-15T10:42:13.214Z",
  "details": {
    "reason": "storage backend unavailable"
  }
}

Get shared state

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

Retrieve a value from the shared state store. The response shape depends on whether the requested entry exists: a missing entry returns exists: false with a null state; a present entry returns exists: true, the stored state, and its size in bytes.

Request body

Field	Type	Required	Default	Description
`hostname`	string	Yes	—	Hostname that owns the state entry.
`path`	string	No	—	Dot-notation path of the value to read. When omitted, the entire hostname state is returned.

curl -X POST https://api.hoody.com/v1/exec/shared-state/get \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "api.example.com",
    "path": "deploy.lastSha"
  }'

const result = await client.exec.state.get({
  hostname: "api.example.com",
  path: "deploy.lastSha",
});

{
  "hostname": "api.example.com",
  "path": "deploy.lastSha",
  "exists": true,
  "state": "a1b2c3d4e5f6",
  "size": 12
}

{
  "hostname": "api.example.com",
  "path": "deploy.missing",
  "exists": false,
  "state": null
}

{
  "error": "Missing required field: hostname",
  "code": "VALIDATION_ERROR",
  "timestamp": "2026-01-15T10:42:13.214Z",
  "details": {
    "field": "hostname"
  }
}

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Invalid input	Request parameters failed validation	Check parameter format and requirements; ensure `hostname` is present

{
  "error": "Failed to read shared state",
  "code": "ERROR_500",
  "timestamp": "2026-01-15T10:42:13.214Z",
  "details": {
    "reason": "storage backend unavailable"
  }
}

Clear shared state

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

Remove a value, a subtree, or every entry from a hostname’s shared state store. By default, the value at the supplied path is cleared; pass clearAll: true to wipe the entire hostname state.

Request body

Field	Type	Required	Default	Description
`hostname`	string	Yes	—	Hostname whose shared state should be cleared.
`path`	string	No	—	Dot-notation path of the value to clear. Ignored when `clearAll` is `true`.
`clearAll`	boolean	No	`false`	Clear all shared state entries for the given hostname.

curl -X POST https://api.hoody.com/v1/exec/shared-state/clear \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "api.example.com",
    "path": "deploy.lastSha",
    "clearAll": false
  }'

await client.exec.state.clear({
  hostname: "api.example.com",
  path: "deploy.lastSha",
  clearAll: false,
});

{
  "cleared": true,
  "count": 1,
  "remaining": 2
}

{
  "error": "Missing required field: hostname",
  "code": "VALIDATION_ERROR",
  "timestamp": "2026-01-15T10:42:13.214Z",
  "details": {
    "field": "hostname"
  }
}

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Invalid input	Request parameters failed validation	Check parameter format and requirements; ensure `hostname` is present

{
  "error": "Failed to clear shared state",
  "code": "ERROR_500",
  "timestamp": "2026-01-15T10:42:13.214Z",
  "details": {
    "reason": "storage backend unavailable"
  }
}