The Agent MITM API lets you inspect and manage the request/response interception rules that apply to your own workspace. Use these endpoints to read the effective state, manage overlay rules and tags, observe firings via logs and a live SSE event stream, run rule-match diagnostics, and verify webhook targets before saving a rule.

Note

All endpoints are scoped to the caller’s own workspace. The overlay is a per-workspace layer on top of the base config (typically hoody.json); changes to the overlay do not modify the base config on disk.

Snapshot

GET /api/v1/workspaces/{workspaceID}/mitm/snapshot

Returns the composed effective state — base config + overlay + transient enables — that the firing path uses. Includes the version triple (configEpoch, overlayRevision, transientEpoch), the rule list with effectiveEnabled, source, and overlayState, and the effective tag catalog.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier

Response (200)

{
  "scope": "ws_abc123",
  "rules": [
    {
      "id": "block-dangerous-rm",
      "name": "Block dangerous rm -rf",
      "enabled": true,
      "description": "Prevents accidental recursive deletion",
      "severity": "critical",
      "trigger": {
        "event": "tool.execute.before",
        "tags": ["destructive"],
        "toolName": "Bash"
      },
      "action": {
        "type": "message",
        "content": "Refusing to run rm -rf on this project."
      },
      "cooldownMs": 0,
      "maxDepth": 1,
      "blocking": true,
      "effectiveEnabled": true,
      "source": "base",
      "overlayState": "active"
    }
  ],
  "tags": [
    {
      "id": "destructive",
      "label": "Destructive",
      "description": "Operations that mutate or delete user data",
      "color": "red"
    }
  ],
  "version": {
    "configEpoch": 12,
    "overlayRevision": 3,
    "transientEpoch": 0
  },
  "builtAt": 1730000000000,
  "processEpoch": 7
}

SDK

const snapshot = await client.agent.workspaceMitmSnapshot.getWorkspaceMitmSnapshot({
  workspaceID: "ws_abc123",
});

Rules

GET /api/v1/workspaces/{workspaceID}/mitm/rules

Returns the list of effective rules, including overlay provenance (source) and the effectiveEnabled flag (which reflects any overlay enabledOverride and any transient override).

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier

Response (200)

[
  {
    "id": "block-dangerous-rm",
    "name": "Block dangerous rm -rf",
    "enabled": true,
    "severity": "critical",
    "trigger": {
      "event": "tool.execute.before",
      "tags": ["destructive"],
      "toolName": "Bash"
    },
    "action": {
      "type": "message",
      "content": "Refusing to run rm -rf on this project."
    },
    "cooldownMs": 0,
    "maxDepth": 1,
    "blocking": true,
    "effectiveEnabled": true,
    "source": "base",
    "overlayState": "active"
  },
  {
    "id": "inject-safety-prompt",
    "name": "Inject safety prompt",
    "enabled": true,
    "severity": "info",
    "trigger": {
      "event": "chat.system.transform"
    },
    "action": {
      "type": "prompt-inject",
      "content": "Always confirm before running shell commands.",
      "position": "prepend",
      "target": "system"
    },
    "cooldownMs": 60000,
    "maxDepth": 1,
    "blocking": false,
    "effectiveEnabled": false,
    "source": "overlay",
    "overlayState": "active"
  }
]

SDK

const rules = await client.agent.workspaceMitmRules.listWorkspaceMitmRules({
  workspaceID: "ws_abc123",
});

POST /api/v1/workspaces/{workspaceID}/mitm/rules

Adds a new rule to the overlay. The base config (e.g. hoody.json) is not modified. The new overlay revision is returned in the ETag header.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier

Request Body

Name	Type	Required	Description
id	string	Yes	Unique rule identifier
name	string	Yes	Human-readable rule name
enabled	boolean	No	Whether the rule is enabled (Default: true)
description	string	No	Free-form description
severity	string	No	One of info, warn, error, critical
trigger	object	Yes	Trigger configuration; event is required
action	object	Yes	One of: shell, message, prompt-inject, webhook, notification
cooldownMs	number	No	Per-(rule,session) cooldown (Default: 0)
maxDepth	number	No	Max recursion depth (Default: 1)
blocking	boolean	No	Block the underlying call when matched (Default: false)

Request

{
  "id": "notify-on-write",
  "name": "Notify on file write",
  "description": "Logs every file write to the workspace channel",
  "severity": "info",
  "trigger": {
    "event": "tool.execute.before",
    "toolName": "Write"
  },
  "action": {
    "type": "notification",
    "title": "File write",
    "body": "Tool Write is about to run."
  },
  "cooldownMs": 0,
  "maxDepth": 1,
  "blocking": false
}

Response (201)

{
  "id": "notify-on-write",
  "name": "Notify on file write",
  "enabled": true,
  "description": "Logs every file write to the workspace channel",
  "severity": "info",
  "trigger": {
    "event": "tool.execute.before",
    "tags": [],
    "toolName": "Write"
  },
  "action": {
    "type": "notification",
    "title": "File write",
    "body": "Tool Write is about to run."
  },
  "cooldownMs": 0,
  "maxDepth": 1,
  "blocking": false
}

409

{
  "error": "Rule with this id already exists in overlay",
  "code": "rule_already_exists"
}

412

{
  "error": "If-Match did not match current overlay revision"
}

422

{
  "error": "Validation failed: trigger.event is required"
}

428

{
  "error": "If-Match header is required for overlay writes"
}

SDK

await client.agent.workspaceMitmRule.createWorkspaceMitmRule({
  workspaceID: "ws_abc123",
  data: {
    id: "notify-on-write",
    name: "Notify on file write",
    severity: "info",
    trigger: { event: "tool.execute.before", toolName: "Write" },
    action: {
      type: "notification",
      title: "File write",
      body: "Tool Write is about to run.",
    },
  },
});

PUT /api/v1/workspaces/{workspaceID}/mitm/rules/{id}

Replaces the rule at :id in the overlay with the request body. If :id refers to a base-config rule, the overlay records a full overlay patch (with baseContentHash for stale detection on subsequent rebase).

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier
id	path	string	Yes	Rule identifier

Request Body

Name	Type	Required	Description
id	string	Yes	Must equal the path :id
name	string	Yes	Human-readable rule name
enabled	boolean	No	Whether the rule is enabled (Default: true)
description	string	No	Free-form description
severity	string	No	One of info, warn, error, critical
trigger	object	Yes	Trigger configuration; event is required
action	object	Yes	One of: shell, message, prompt-inject, webhook, notification
cooldownMs	number	No	Per-(rule,session) cooldown (Default: 0)
maxDepth	number	No	Max recursion depth (Default: 1)
blocking	boolean	No	Block the underlying call when matched (Default: false)

Request

{
  "id": "notify-on-write",
  "name": "Notify on file write (updated)",
  "description": "Logs file writes and shell commands",
  "severity": "warn",
  "trigger": {
    "event": "tool.execute.before",
    "toolName": "Write"
  },
  "action": {
    "type": "notification",
    "title": "File write",
    "body": "Tool Write is about to run."
  },
  "cooldownMs": 0,
  "maxDepth": 1,
  "blocking": false
}

Response (200)

{
  "id": "notify-on-write",
  "name": "Notify on file write (updated)",
  "enabled": true,
  "description": "Logs file writes and shell commands",
  "severity": "warn",
  "trigger": {
    "event": "tool.execute.before",
    "tags": [],
    "toolName": "Write"
  },
  "action": {
    "type": "notification",
    "title": "File write",
    "body": "Tool Write is about to run."
  },
  "cooldownMs": 0,
  "maxDepth": 1,
  "blocking": false
}

412

{
  "error": "If-Match did not match current overlay revision"
}

422

{
  "error": "Validation failed: trigger.event is required"
}

428

{
  "error": "If-Match header is required for overlay writes"
}

SDK

await client.agent.rules.replaceWorkspaceMitmRule({
  workspaceID: "ws_abc123",
  id: "notify-on-write",
  data: {
    id: "notify-on-write",
    name: "Notify on file write (updated)",
    severity: "warn",
    trigger: { event: "tool.execute.before", toolName: "Write" },
    action: {
      type: "notification",
      title: "File write",
      body: "Tool Write is about to run.",
    },
  },
});

PATCH /api/v1/workspaces/{workspaceID}/mitm/rules/{id}

Applies a shallow-merge patch to the overlay rule at :id. Pass null explicitly to delete a field on merge (the schema accepts nullable().optional() on every property).

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier
id	path	string	Yes	Rule identifier

Request Body

This endpoint accepts a partial rule object. Any field listed in the rule schema may be supplied. Set a field to null to remove it from the merged result.

Request

{
  "name": "Notify on file write (v2)",
  "severity": "warn",
  "description": null
}

Response (200)

{
  "id": "notify-on-write",
  "name": "Notify on file write (v2)",
  "enabled": true,
  "severity": "warn",
  "trigger": {
    "event": "tool.execute.before",
    "tags": [],
    "toolName": "Write"
  },
  "action": {
    "type": "notification",
    "title": "File write",
    "body": "Tool Write is about to run."
  },
  "cooldownMs": 0,
  "maxDepth": 1,
  "blocking": false
}

412

{
  "error": "If-Match did not match current overlay revision"
}

422

{
  "error": "Validation failed: severity must be one of info, warn, error, critical"
}

428

{
  "error": "If-Match header is required for overlay writes"
}

SDK

await client.agent.workspaceMitmRule.patchWorkspaceMitmRule({
  workspaceID: "ws_abc123",
  id: "notify-on-write",
  data: {
    name: "Notify on file write (v2)",
    severity: "warn",
    description: null,
  },
});

DELETE /api/v1/workspaces/{workspaceID}/mitm/rules/{id}

Removes the rule at :id from the overlay. If :id refers to a base-config rule, the overlay records a deletion tombstone so the rule is omitted from the effective state.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier
id	path	string	Yes	Rule identifier

This endpoint accepts no body.

Response (204)

{
  "description": "Deleted"
}

412

{
  "error": "If-Match did not match current overlay revision"
}

428

{
  "error": "If-Match header is required for overlay writes"
}

SDK

await client.agent.workspaceMitmRule.deleteWorkspaceMitmRule({
  workspaceID: "ws_abc123",
  id: "notify-on-write",
});

POST /api/v1/workspaces/{workspaceID}/mitm/rules/{id}/enable

Records an enabledOverride on the overlay so the rule’s effective enabled state flips, without rewriting any other fields. Persists across restart.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier
id	path	string	Yes	Rule identifier

Request Body

Name	Type	Required	Description
enabled	boolean	Yes	The new effective enabled state

Request

{
  "enabled": false
}

Response (200)

{
  "description": "Override recorded"
}

412

{
  "error": "If-Match did not match current overlay revision"
}

428

{
  "error": "If-Match header is required for overlay writes"
}

SDK

await client.agent.enable.setWorkspaceMitmRuleEnabled({
  workspaceID: "ws_abc123",
  id: "notify-on-write",
  data: { enabled: false },
});

POST /api/v1/workspaces/{workspaceID}/mitm/rules/{id}/transient-enable

Volatile per-process enable/disable. Does NOT persist across restart. Bumps transientEpoch and triggers a snapshot rebuild. Useful for short-lived A/B testing or temporary disables.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier
id	path	string	Yes	Rule identifier

Request Body

Name	Type	Required	Description
enabled	boolean	Yes	The new effective enabled state
ttlMs	integer	No	Time-to-live in milliseconds (Default: 300000, minimum 1000, maximum 86400000)

Request

{
  "enabled": false,
  "ttlMs": 60000
}

Response (200)

{
  "description": "Transient override recorded"
}

SDK

await client.agent.transientEnable.setWorkspaceMitmRuleTransientEnabled({
  workspaceID: "ws_abc123",
  id: "notify-on-write",
  data: { enabled: false, ttlMs: 60000 },
});

Tags

GET /api/v1/workspaces/{workspaceID}/mitm/tags

Returns the effective tag catalog for the workspace’s MITM scope.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier

Response (200)

[
  {
    "id": "destructive",
    "label": "Destructive",
    "description": "Operations that mutate or delete user data",
    "color": "red"
  },
  {
    "id": "review",
    "label": "Review",
    "description": "",
    "color": "gray"
  }
]

SDK

const tags = await client.agent.workspaceMitmTags.listWorkspaceMitmTags({
  workspaceID: "ws_abc123",
});

POST /api/v1/workspaces/{workspaceID}/mitm/tags

Adds a new tag to the overlay.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	workspaceID path parameter

Request Body

Name	Type	Required	Description
id	string	Yes	Unique tag identifier
label	string	Yes	Human-readable tag label
description	string	No	Free-form description (Default: "")
color	string	No	One of green, blue, yellow, purple, red, orange, gray (Default: "gray")

Request

{
  "id": "review",
  "label": "Review",
  "description": "Sessions under human review",
  "color": "blue"
}

Response (201)

{
  "id": "review",
  "label": "Review",
  "description": "Sessions under human review",
  "color": "blue"
}

409

{
  "error": "Tag with this id already exists in overlay",
  "code": "tag_already_exists"
}

412

{
  "error": "If-Match did not match current overlay revision"
}

428

{
  "error": "If-Match header is required for overlay writes"
}

SDK

await client.agent.workspaceMitmTag.createWorkspaceMitmTag({
  workspaceID: "ws_abc123",
  data: {
    id: "review",
    label: "Review",
    description: "Sessions under human review",
    color: "blue",
  },
});

DELETE /api/v1/workspaces/{workspaceID}/mitm/tags/{id}

Removes the tag at :id from the overlay. If :id refers to a base-config tag, the overlay records a deletion tombstone so the tag is omitted from the effective state.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier
id	path	string	Yes	Tag identifier

This endpoint accepts no body.

Response (204)

{
  "description": "Deleted"
}

412

{
  "error": "If-Match did not match current overlay revision"
}

428

{
  "error": "If-Match header is required for overlay writes"
}

SDK

await client.agent.workspaceMitmTag.deleteWorkspaceMitmTag({
  workspaceID: "ws_abc123",
  id: "review",
});

PATCH /api/v1/workspaces/{workspaceID}/mitm/sessions/{sessionID}/tags

Replaces the mitm_tags on a session. The handler canonicalises the incoming list (sorted + deduped) and short-circuits to a no-op when canonical equality is detected.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier
sessionID	path	string	Yes	Session identifier

Request Body

Name	Type	Required	Description
tags	array	Yes	The full replacement list of tag ids

Request

{
  "tags": ["review", "destructive"]
}

Response (200)

{
  "description": "Tags updated (or no-op)"
}

404

{
  "description": "Session not found"
}

SDK

await client.agent.sessionMitmTags.patchSessionMitmTags({
  workspaceID: "ws_abc123",
  sessionID: "sess_xyz",
  data: { tags: ["review", "destructive"] },
});

Cooldowns & Logs

GET /api/v1/workspaces/{workspaceID}/mitm/cooldowns

Returns the list of active per-(rule, session) cooldowns currently in effect for this scope.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier

Response (200)

[
  {
    "ruleId": "notify-on-write",
    "sessionID": "sess_xyz",
    "lastFiredAt": 1730000040000
  },
  {
    "ruleId": "inject-safety-prompt",
    "sessionID": "sess_abc",
    "lastFiredAt": 1730000055000
  }
]

SDK

const cooldowns = await client.agent.workspaceMitmCooldowns.listWorkspaceMitmCooldowns({
  workspaceID: "ws_abc123",
});

GET /api/v1/workspaces/{workspaceID}/mitm/logs

Returns a paginated, redacted projection of the MITM log scoped to this workspace. Pass sessionID to filter by session.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier
page	query	integer	No	Page number (Default: 1)
limit	query	integer	No	Items per page (Default: 50)
sessionID	query	string	No	Filter entries by session id

Response (200)

{
  "items": [
    {
      "id": "log_01HXYZ",
      "ruleId": "notify-on-write",
      "ruleName": "Notify on file write",
      "event": "tool.execute.before",
      "sessionID": "sess_xyz",
      "messageID": "msg_001",
      "timestamp": 1730000040000,
      "status": "success",
      "durationMs": 12,
      "actionType": "notification",
      "rule": {
        "id": "notify-on-write",
        "name": "Notify on file write",
        "enabled": true,
        "severity": "info",
        "trigger": {
          "event": "tool.execute.before",
          "tags": [],
          "toolName": "Write"
        },
        "action": {
          "type": "notification",
          "title": "File write",
          "body": "Tool Write is about to run."
        },
        "cooldownMs": 0,
        "maxDepth": 1,
        "blocking": false
      },
      "context": {
        "sessionTitle": "Refactor auth",
        "tags": ["review"],
        "directory": "/home/user/project",
        "projectID": "proj_1",
        "depth": 0,
        "toolName": "Write",
        "messageRole": "assistant"
      },
      "scope": "ws_abc123",
      "seq": 142,
      "processEpoch": 7,
      "severity": "info"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "pages": 1
  }
}

SDK

const logs = await client.agent.workspaceMitmLogsPaginated.listWorkspaceMitmLogsPaginated({
  workspaceID: "ws_abc123",
  page: 1,
  limit: 50,
  sessionID: "sess_xyz",
});

GET /api/v1/workspaces/{workspaceID}/mitm/logs/{id}

Returns the redacted projection of a single MITM log entry. Set the request header Hoody-MITM-Include-Secrets: 1 to receive the unredacted entry.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier
id	path	string	Yes	Log entry identifier

Response (200)

{
  "id": "log_01HXYZ",
  "ruleId": "notify-on-write",
  "ruleName": "Notify on file write",
  "event": "tool.execute.before",
  "sessionID": "sess_xyz",
  "messageID": "msg_001",
  "timestamp": 1730000040000,
  "status": "success",
  "durationMs": 12,
  "actionType": "notification",
  "rule": {
    "id": "notify-on-write",
    "name": "Notify on file write",
    "enabled": true,
    "severity": "info",
    "trigger": {
      "event": "tool.execute.before",
      "tags": [],
      "toolName": "Write"
    },
    "action": {
      "type": "notification",
      "title": "File write",
      "body": "Tool Write is about to run."
    },
    "cooldownMs": 0,
    "maxDepth": 1,
    "blocking": false
  },
  "context": {
    "sessionTitle": "Refactor auth",
    "tags": ["review"],
    "directory": "/home/user/project",
    "projectID": "proj_1",
    "depth": 0,
    "toolName": "Write",
    "messageRole": "assistant"
  },
  "scope": "ws_abc123",
  "seq": 142,
  "processEpoch": 7,
  "severity": "info"
}

404

{
  "description": "Entry not found"
}

SDK

const entry = await client.agent.workspaceMitmLogEntry.getWorkspaceMitmLogEntry({
  workspaceID: "ws_abc123",
  id: "log_01HXYZ",
});

Validation & Plugins

GET /api/v1/workspaces/{workspaceID}/mitm/validation-rules

Returns the discriminated-union list of validation rules the server applies to MITM rules on top of the Zod structural schema. SDK consumers can use this metadata to implement matching client-side validation.

Tip

This endpoint is pure metadata — no auth, no scope binding.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier

Response (200)

[
  {
    "type": "regex",
    "field": "id",
    "pattern": "^[a-z0-9][a-z0-9-]{2,62}$",
    "flags": "i",
    "message": "Rule id must be 3-63 chars, lowercase letters, digits, or hyphens"
  },
  {
    "type": "range",
    "field": "cooldownMs",
    "min": 0,
    "max": 86400000,
    "message": "cooldownMs must be between 0 and 24h"
  },
  {
    "type": "enum",
    "field": "severity",
    "values": ["info", "warn", "error", "critical"],
    "message": "severity must be one of info, warn, error, critical"
  },
  {
    "type": "depends-on",
    "field": "trigger.toolName",
    "requires": "trigger.event",
    "when": "tool.execute.before",
    "message": "toolName requires trigger.event to be a tool event"
  },
  {
    "type": "max-length",
    "field": "name",
    "max": 80,
    "message": "Rule name must be at most 80 characters"
  }
]

SDK

const validators = await client.agent.workspaceMitmValidationRules.listWorkspaceMitmValidationRules({
  workspaceID: "ws_abc123",
});

GET /api/v1/workspaces/{workspaceID}/mitm/plugin-descriptors

Returns plugin metadata in registration order, including id, source, declared hooks, declared tools, and the auth provider name.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier

Response (200)

[
  {
    "id": "hoody-builtin-notifier",
    "source": "internal",
    "exportName": "default",
    "packageName": "@hoody/plugin-notifier",
    "packageVersion": "1.4.2",
    "hooks": ["onRuleFire", "onSessionIdle"],
    "tools": ["sendDesktopNotification"],
    "auth": "none"
  },
  {
    "id": "user-slack-relay",
    "source": "npm",
    "exportName": "SlackRelay",
    "packageName": "@acme/hoody-slack-relay",
    "packageVersion": "0.9.0",
    "hooks": ["onRuleFire"],
    "tools": ["postToSlack"],
    "auth": "oauth2"
  }
]

SDK

const plugins = await client.agent.workspaceMitmPluginDescriptors.listWorkspaceMitmPluginDescriptors({
  workspaceID: "ws_abc123",
});

Overlay & Webhooks

POST /api/v1/workspaces/{workspaceID}/mitm/overlay/reset

Drops the entire overlay for this scope — every overlay entry, including tags, rules, deletions, and enabledOverride values. Effective state reverts to base config only.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier

This endpoint accepts no body.

Response (200)

{
  "description": "Overlay cleared"
}

412

{
  "error": "If-Match did not match current overlay revision"
}

428

{
  "error": "If-Match header is required for overlay writes"
}

SDK

await client.agent.reset.resetWorkspaceMitmOverlay({
  workspaceID: "ws_abc123",
});

POST /api/v1/workspaces/{workspaceID}/mitm/overlay/rebase

For every overlay rule whose baseContentHash has drifted, recompute the merged rule against the new base. On success, all baseContentHash values are refreshed. If a merged rule fails validation (e.g. the base rule’s type changed under you), the server returns 409 with the failed rule and a diff.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier

This endpoint accepts no body.

Response (200)

{
  "description": "Rebase completed"
}

409

{
  "description": "Conflict — merged rule fails validation"
}

412

{
  "description": "Optimistic-concurrency conflict"
}

428

{
  "description": "Missing If-Match header"
}

SDK

await client.agent.rebase.rebaseWorkspaceMitmOverlay({
  workspaceID: "ws_abc123",
});

POST /api/v1/workspaces/{workspaceID}/mitm/webhooks/verify

Dispatches a one-shot webhook via safeFetch and returns the response status plus a redacted summary. Use this to confirm that a URL and its auth headers work before saving a rule that targets that URL.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier

Request Body

Name	Type	Required	Description
url	string	Yes	The webhook URL to test
method	string	No	One of POST, GET (Default: "POST")
headers	object	No	Additional request headers (string-to-string map)
bodyJson	object	No	JSON body to send

Request

{
  "url": "https://example.com/hooks/hoody",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer test-token"
  },
  "bodyJson": {"ping": true}
}

Response (200)

{
  "description": "Diagnostic result"
}

SDK

await client.agent.verify.verifyWorkspaceMitmWebhook({
  workspaceID: "ws_abc123",
  data: {
    url: "https://example.com/hooks/hoody",
    method: "POST",
    headers: { Authorization: "Bearer test-token" },
    bodyJson: { ping: true },
  },
});

Events & Diagnostics

GET /api/v1/workspaces/{workspaceID}/mitm/events

Server-Sent Events stream of MitmLog.Event.RuleFired filtered to this scope.

Note

Each event carries an id formatted as <processEpoch>:<seq>. Reconnect with Last-Event-ID; if the epoch on the resume event does not match the running process, treat it as a restart. Fresh subscribers receive only future events — there is no replay. The stream emits a synthetic connected event on connect and closes with error: scope_changed if Instance.directory drift is detected. Rebinds are not supported within a single connection.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier

Response (200)

HTTP/1.1 200 OK
Content-Type: text/event-stream

event: connected
id: 7:0
data: {"scope":"ws_abc123","processEpoch":7}

event: rule_fired
id: 7:142
data: {"ruleId":"notify-on-write","sessionID":"sess_xyz","event":"tool.execute.before","timestamp":1730000040000}

event: rule_fired
id: 7:143
data: {"ruleId":"notify-on-write","sessionID":"sess_xyz","event":"tool.execute.before","timestamp":1730000041000}

SDK

await client.agent.events.streamWorkspaceMitmEvents({
  workspaceID: "ws_abc123",
});

POST /api/v1/workspaces/{workspaceID}/mitm/diagnostics/dry-run

Simulates rule firing against the current snapshot for a synthetic event. Returns the matched rules and each rule’s cooldown status. Pure read-only — no actions are executed.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	workspaceID path parameter

Request Body

Name	Type	Required	Description
event	string	Yes	One of session.created, session.idle, session.error, chat.message, tool.execute.before, tool.execute.after, chat.system.transform
sessionTags	array	No	Tags on the synthetic session (Default: [])
depth	integer	No	Recursion depth for the synthetic event (Default: 0)
toolName	string	No	Tool name for tool.execute.* events
role	string	No	One of user, assistant
messageContent	string	No	Message content for chat.message

Request

{
  "event": "tool.execute.before",
  "sessionTags": ["review"],
  "depth": 0,
  "toolName": "Bash"
}

Response (200)

{
  "description": "Match diagnostic"
}

SDK

const result = await client.agent.dryRun.diagnoseWorkspaceMitmDryRun({
  workspaceID: "ws_abc123",
  data: {
    event: "tool.execute.before",
    sessionTags: ["review"],
    depth: 0,
    toolName: "Bash",
  },
});

POST /api/v1/workspaces/{workspaceID}/mitm/diagnostics/match-trace

Same shape as the dry-run endpoint, but reports WHY each rule did or did not match — at every filter stage (event, depth, tags, toolName, role, contentMatch, overlayState). Pure read-only on the snapshot.

Parameters

Name	In	Type	Required	Description
workspaceID	path	string	Yes	Workspace identifier

Request Body

Name	Type	Required	Description
event	string	Yes	One of session.created, session.idle, session.error, chat.message, tool.execute.before, tool.execute.after, chat.system.transform
sessionTags	array	No	Tags on the synthetic session (Default: [])
depth	integer	No	Recursion depth for the synthetic event (Default: 0)
toolName	string	No	Tool name for tool.execute.* events
role	string	No	One of user, assistant
messageContent	string	No	Message content for chat.message

Request

{
  "event": "chat.message",
  "sessionTags": ["review"],
  "depth": 0,
  "role": "user",
  "messageContent": "Please delete the staging database."
}

Response (200)

{
  "description": "Per-rule trace"
}

SDK

const trace = await client.agent.matchTrace.diagnoseWorkspaceMitmMatchTrace({
  workspaceID: "ws_abc123",
  data: {
    event: "chat.message",
    sessionTags: ["review"],
    depth: 0,
    role: "user",
    messageContent: "Please delete the staging database.",
  },
});