Cache & Shared State

Manage execution-side caching and the shared state store that lets scripts persist and share data across executions. Use these endpoints to clear cached VM state, inspect or update shared state scoped to a hostname, or wipe state on demand during debugging or test teardown.

Note

All four endpoints are scoped to the container’s exec service. Requests target the container hostname {projectId}-{containerId}-exec-1.{server}.containers.hoody.com, where {projectId} and {containerId} are 24-character hexadecimal IDs and {server} is the regional node label (for example node-us).

Cache Management

POST /api/v1/exec/cache/clear

Clear cached VM state and/or shared state for a hostname. By default, only the VM cache is cleared; pass clearAll=true to wipe both caches in one call.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
hostname	string	No	Hostname whose cache should be cleared.
scriptPath	string	No	Not accepted - a scriptPath-based clear returns HTTP 400. The VM cache is keyed by hostname, so use hostname or clearAll=true.
clearVm	boolean	No	Whether to clear the VM cache. Default: true.
clearState	boolean	No	Whether to clear shared state. Default: false.
clearAll	boolean	No	Whether to clear both VM cache and shared state. Default: false.

Response

200

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

400

{
  "error": "Invalid parameter format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {
    "field": "scriptPath",
    "reason": "scriptPath is deprecated; use hostname or clearAll=true"
  }
}

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": "2025-01-15T12:34:56.789Z"
}

SDK Usage

cURL

curl -X POST "https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.com/api/v1/exec/cache/clear" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "hostname": "shop.example.com",
    "clearAll": true
  }'

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.cache.clear({ hostname: 'shop.example.com', clearAll: true });

---

Shared State

Shared state is a hostname-scoped key-value store that persists across script executions. The four endpoints below cover the full lifecycle: read, write, and wipe.

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

Read the current shared state for a hostname. Returns the value at a specific path, or the entire state object when no path is supplied.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
hostname	string	Yes	Hostname whose shared state should be returned.
path	string	No	Path within the state object. Omit to return the entire state.

Response

200

{
  "hostname": "shop.example.com",
  "path": "cart.items",
  "exists": true,
  "state": [
    { "sku": "ABC-001", "qty": 2 },
    { "sku": "ABC-014", "qty": 1 }
  ],
  "size": 84
}

400

{
  "error": "Missing required field: hostname",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {
    "field": "hostname"
  }
}

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": "2025-01-15T12:34:56.789Z"
}

SDK Usage

cURL

curl -X POST "https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.com/api/v1/exec/shared-state/get" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "hostname": "shop.example.com",
    "path": "cart.items"
  }'

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.state.get({ hostname: 'shop.example.com', path: 'cart.items' });

---

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

Write or update the shared state for a hostname. Pass merge=true to deep-merge the incoming value into the existing state rather than replacing it.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
hostname	string	Yes	Hostname whose shared state should be written.
path	string	No	Path within the state object. Omit to set the entire state.
value	any (JSON)	Yes	Arbitrary JSON value to store. May be an object, array, number, boolean, string, or null.
merge	boolean	No	When true, deep-merge value into the existing state instead of replacing it. Default: false.

Response

200

{
  "hostname": "shop.example.com",
  "path": "cart.items",
  "updated": true,
  "merged": false,
  "size": 124
}

400

{
  "error": "Missing required field: value",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {
    "field": "value"
  }
}

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": "2025-01-15T12:34:56.789Z"
}

SDK Usage

cURL

curl -X POST "https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.com/api/v1/exec/shared-state/set" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "hostname": "shop.example.com",
    "path": "cart.items",
    "value": [
      { "sku": "ABC-001", "qty": 2 }
    ],
    "merge": 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.state.set({
  hostname: 'shop.example.com',
  path: 'cart.items',
  value: [{ sku: 'ABC-001', qty: 2 }],
  merge: false,
});

---

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

Remove a path from shared state, or wipe the entire state for a hostname when clearAll=true. The response shape differs depending on whether a single path was cleared or the full state was wiped.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
hostname	string	Yes	Hostname whose shared state should be cleared.
path	string	No	Path within the state object to remove. Required unless clearAll=true.
clearAll	boolean	No	When true, wipe all shared state for the hostname. Default: false.

Response

200

{
  "hostname": "shop.example.com",
  "path": "cart.items",
  "cleared": true,
  "reason": "path-removed"
}

When clearAll=true, the response shape changes to a summary:

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

400

{
  "error": "Either path or clearAll=true is required",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-01-15T12:34:56.789Z",
  "details": {
    "field": "path"
  }
}

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": "2025-01-15T12:34:56.789Z"
}

SDK Usage

cURL

curl -X POST "https://{projectId}-{containerId}-exec-1.{server}.containers.hoody.com/api/v1/exec/shared-state/clear" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "hostname": "shop.example.com",
    "path": "cart.items"
  }'

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.state.clear({ hostname: 'shop.example.com', path: 'cart.items' });