Clear VM execution caches and manage hostname-scoped shared state values that persist across scripts. VM cache entries are keyed by hostname; shared state values are scoped per hostname (and optionally per path) and accept arbitrary JSON. Use these endpoints during development to reset cached executions, and at runtime to coordinate values between scripts.

Caution

The scriptPath field on the Clear Cache endpoint is deprecated. Sending it returns HTTP 400. VM cache is keyed by hostname — pass hostname or set clearAll: true instead.

Clear Cache

POST /api/v1/exec/cache/clear

Clear the VM execution cache and (optionally) the shared state for a hostname.

Request Body

Field	Type	Required	Default	Description
hostname	string	No	—	Hostname key for the cache entry to clear.
scriptPath	string	No	—	Deprecated. Returns HTTP 400 if supplied.
clearVm	boolean	No	true	Clear the VM execution cache.
clearState	boolean	No	false	Also clear shared state for the hostname.
clearAll	boolean	No	false	Clear both VM cache and shared state for the hostname.

Responses

200

Success.

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

400

{
  "error": "Invalid parameter format",
  "code": "VALIDATION_ERROR",
  "timestamp": "2024-01-15T12:00:00.000Z",
  "details": {
    "field": "scriptPath",
    "reason": "Field is deprecated"
  }
}

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-15T12:00:00.000Z",
  "details": {
    "requestId": "req_abc123"
  }
}

SDK

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

Shared State

Shared state is a persistent, hostname-scoped JSON store. Values are arbitrary JSON, addressed by hostname and (optionally) a path. Use clearAll: true to wipe all paths under a hostname.

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

Remove one or all shared state values for a hostname.

Request Body

Field	Type	Required	Default	Description
hostname	string	Yes	—	Hostname key for the shared state.
path	string	No	—	Specific state path to clear. Ignored when clearAll: true.
clearAll	boolean	No	false	Clear all shared state for the hostname.

Responses

200

Success.

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

400

{
  "error": "Missing required field: hostname",
  "code": "VALIDATION_ERROR",
  "timestamp": "2024-01-15T12:00:00.000Z",
  "details": {
    "field": "hostname",
    "reason": "Required"
  }
}

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-15T12:00:00.000Z",
  "details": {
    "requestId": "req_abc123"
  }
}

SDK

await client.exec.state.clear({
  hostname: "example.com",
  path: "/user/profile",
  clearAll: false,
});

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

Read the current shared state value for a hostname and (optionally) a path.

Request Body

Field	Type	Required	Default	Description
hostname	string	Yes	—	Hostname key for the shared state.
path	string	No	—	Specific state path to read.

Responses

200

Success. The response shape depends on whether the state exists.

When state exists at the requested path:

{
  "hostname": "example.com",
  "path": "/user/profile",
  "exists": true,
  "state": {
    "name": "Ada Lovelace",
    "score": 42
  },
  "size": 42
}

When state does not exist at the requested path:

{
  "hostname": "example.com",
  "path": "/user/missing",
  "exists": false,
  "state": null
}

400

{
  "error": "Missing required field: hostname",
  "code": "VALIDATION_ERROR",
  "timestamp": "2024-01-15T12:00:00.000Z",
  "details": {
    "field": "hostname",
    "reason": "Required"
  }
}

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-15T12:00:00.000Z",
  "details": {
    "requestId": "req_abc123"
  }
}

SDK

const { exists, state } = await client.exec.state.get({
  hostname: "example.com",
  path: "/user/profile",
});

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

Write (or merge into) the shared state value at a hostname and (optionally) a path.

Request Body

Field	Type	Required	Default	Description
hostname	string	Yes	—	Hostname key for the shared state.
path	string	No	—	Specific state path to write to.
value	string	Yes	—	Arbitrary JSON value to store.
merge	boolean	No	false	Merge the supplied value into the existing object at path instead of replacing it.

Responses

200

Success.

{
  "hostname": "example.com",
  "path": "/user/profile",
  "updated": true,
  "merged": false,
  "size": 256
}

400

{
  "error": "Missing required field: value",
  "code": "VALIDATION_ERROR",
  "timestamp": "2024-01-15T12:00:00.000Z",
  "details": {
    "field": "value",
    "reason": "Required"
  }
}

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-15T12:00:00.000Z",
  "details": {
    "requestId": "req_abc123"
  }
}

SDK

await client.exec.state.set({
  hostname: "example.com",
  path: "/user/profile",
  value: { name: "Ada Lovelace", score: 42 },
  merge: true,
});