# Cache & Shared State

**Page:** api/exec/cache-state

[Download Raw Markdown](./api/exec/cache-state.md)

---

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



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


All four endpoints in this group are `POST` requests with JSON bodies. VM cache is keyed by `hostname`; the legacy `scriptPath` field on the cache-clear endpoint is deprecated and returns `HTTP 400` when supplied alone.


---

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



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


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


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


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


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



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


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


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


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


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



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


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


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


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


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


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



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


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


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


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


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




The `clearAll` flag is destructive and irreversible. It removes **every** shared state entry for the given hostname, including entries written by other scripts.