# Trustvice + Trustvice Receipts — Agentic Control Surface

> Auto-generated from `@trustvice/contracts@0.91.0` on 2026-11-08T20:41:05.782Z.
> Do not edit by hand — re-run `npm run codegen` in the contracts repo.

This document is the **single source of truth** for every programmatic + agentic action a customer can invoke against Trustvice and Trustvice Receipts. It is consumed by:

- AI coding assistants (Claude Code, Cursor, GitHub Copilot, OpenAI Codex) — for retrieval-augmented code generation against the Trustvice API.
- AI chat surfaces (ChatGPT, Claude, Gemini, Perplexity) — for context priming when an end-user grants the connector access.
- The Trustvice developer portal — as the canonical narrative pairing of `openapi.json`.
- Internal Worker handler tests — every example here is exercised in CI.

## Topology

- **Gateway**: `https://api.trustvice.com` — REST surface (OAuth 2.1 + PKCE + DPoP, PAT, workspace API keys).
- **MCP server**: `https://mcp.trustvice.com/mcp` — streamable HTTP transport (POST, JSON replies). Tool list mirrors this catalogue.
- **A2A capability card**: `https://trustvice.com/.well-known/agent-card.json` — declarative agent-to-agent capability card (REST + MCP; there is no `/a2a` transport).
- **AGENTS.md (this file)**: `https://trustvice.com/AGENTS.md`.

## Safety hierarchy

Every action is classified by `safetyLevel`:

- `read` — no side effects. Safe to auto-execute. Emits `agent_read` audit envelope.
- `mutation` — writes state but reversible. Default `confirmationPolicy=ask` (agent SHOULD prompt; server permits).
- `destructive` — hard to reverse. Default `confirmationPolicy=always` (server enforces — returns 412 without confirmation token).
- `billing_impacting` — costs the customer money. Default `confirmationPolicy=always`; threshold-gated actions escalate to `mandate` (AP2 Verifiable Credential required).

Mutating + destructive + billing-impacting actions also require a workspace context header (`Trustvice-Workspace-Id`) and an `X-Idempotency-Key`.

## Anti-confused-deputy: membership floor

Cross-workspace confused-deputy defense is the membership floor (record 0639). Intent-claim minting was retired before it ever wrote a row — do not send `X-Intent-Claim`. There is no `intents/claim` issuer.

## Domains

### `account` (23 actions)

Login session, profile, passkeys, locale, notification preferences. Always accessible to the authenticated principal.

##### `account.session.list`

- **Summary**: List active sessions on this account.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/account.session.list`

**Example**:

```jsonc
// input
{
  "limit": 10
}
// → output
{
  "sessions": [],
  "nextCursor": null
}
// note: List active sessions.
```

##### `account.session.revoke`

- **Summary**: Revoke an active session by id (cannot be disabled — safety floor).
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/account.session.revoke`

**Example**:

```jsonc
// input
{
  "sessionId": "sess_abc"
}
// → output
{
  "revoked": true,
  "propagatedAt": "2026-05-22T12:00:00.000Z"
}
// note: Kill an active session.
```

##### `account.session.current`

- **Summary**: Get the calling principal's current session.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/account.session.current`

**Example**:

```jsonc
// input
{}
// → output
{
  "sessionId": "sess_abc",
  "accountId": "acc_DEMO00000000000000000000",
  "issuedAt": "2026-05-22T12:00:00.000Z",
  "expiresAt": "2026-05-22T12:30:00.000Z",
  "authMethod": "session_cookie",
  "isCurrent": true
}
// note: Read your own session.
```

##### `account.profile.get`

- **Summary**: Get the authenticated account's profile.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/account.profile.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "accountId": "acc_DEMO00000000000000000000",
  "email": "owner@example.com",
  "displayName": "Ada Lovelace",
  "locale": "en",
  "createdAt": "2026-01-01T00:00:00.000Z"
}
// note: Read your profile.
```

##### `account.profile.update`

- **Summary**: Update account profile (display name, avatar URL).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/account.profile.update`

**Example**:

```jsonc
// input
{
  "displayName": "Ada Lovelace"
}
// → output
{
  "accountId": "acc_DEMO00000000000000000000",
  "displayName": "Ada Lovelace"
}
// note: Update display name.
```

##### `account.email.change`

- **Summary**: Request an email change. A verification email is sent to the new address; the change applies only after click-through.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/account.email.change`

**Example**:

```jsonc
// input
{
  "newEmail": "new@example.com"
}
// → output
{
  "pending": true,
  "verificationSentTo": "new@example.com"
}
// note: Start email change flow.
```

##### `account.email.change.pending`

- **Summary**: Read the email change already in flight, and which of the two addresses still has to confirm. Null when none is pending.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/account.email.change.pending`

**Example**:

```jsonc
// input
{}
// → output
{
  "pending": {
    "newEmail": "new@example.com",
    "requestedAt": "2026-05-22T12:00:00.000Z",
    "expiresAt": "2026-05-23T12:00:00.000Z",
    "awaitingOldAddress": true,
    "awaitingNewAddress": false
  }
}
// note: A change waiting on the old address.
```

##### `account.passkey.list`

- **Summary**: List registered passkeys.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/account.passkey.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "passkeys": []
}
// note: List passkeys.
```

##### `account.passkey.register-challenge`

- **Summary**: Begin passkey registration — returns a WebAuthn PublicKeyCredentialCreationOptions challenge.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, dashboard
- **REST endpoint**: `POST /v1/actions/account.passkey.register-challenge`

**Example**:

```jsonc
// input
{
  "nickname": "YubiKey 5C"
}
// → output
{
  "challenge": "abc...",
  "rp": {
    "id": "trustvice.com",
    "name": "Trustvice"
  },
  "user": {
    "id": "u",
    "name": "owner@example.com",
    "displayName": "Ada"
  },
  "pubKeyCredParams": [
    {
      "type": "public-key",
      "alg": -7
    }
  ]
}
// note: WebAuthn registration challenge.
```

##### `account.passkey.register-finish`

- **Summary**: Complete passkey registration with the WebAuthn attestation response.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, dashboard
- **REST endpoint**: `POST /v1/actions/account.passkey.register-finish`

**Example**:

```jsonc
// input
{
  "nickname": "YubiKey 5C",
  "attestationObject": "...",
  "clientDataJSON": "..."
}
// → output
{
  "credentialId": "cred_abc",
  "nickname": "YubiKey 5C",
  "createdAt": "2026-05-22T12:00:00.000Z",
  "lastUsedAt": null,
  "backupEligible": false
}
// note: Finish passkey registration.
```

##### `account.passkey.revoke`

- **Summary**: Revoke a registered passkey.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/account.passkey.revoke`

**Example**:

```jsonc
// input
{
  "credentialId": "cred_abc"
}
// → output
{
  "revoked": true
}
// note: Remove a passkey.
```

##### `account.recovery-codes.generate`

- **Summary**: Generate a fresh set of 10 single-use recovery codes (existing codes are invalidated).
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, dashboard
- **REST endpoint**: `POST /v1/actions/account.recovery-codes.generate`

**Example**:

```jsonc
// input
{}
// → output
{
  "codes": [
    "AAAA-BBBB-CCCC",
    "DDDD-EEEE-FFFF",
    "GGGG-HHHH-IIII",
    "JJJJ-KKKK-LLLL",
    "MMMM-NNNN-OOOO",
    "PPPP-QQQQ-RRRR",
    "SSSS-TTTT-UUUU",
    "VVVV-WWWW-XXXX",
    "YYYY-ZZZZ-AAAA",
    "BBBB-CCCC-DDDD"
  ],
  "generatedAt": "2026-05-22T12:00:00.000Z"
}
// note: 10 fresh recovery codes.
```

##### `account.locale.set`

- **Summary**: Set the account-level preferred locale (overrides browser default).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/account.locale.set`

**Example**:

```jsonc
// input
{
  "locale": "de"
}
// → output
{
  "locale": "de"
}
// note: Switch UI language to German.
```

##### `account.display-preferences.set`

- **Summary**: Set the account-level display preferences: colour theme and IANA timezone. Either field may be omitted; neither is a no-op.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/account.display-preferences.set`

**Example**:

```jsonc
// input
{
  "theme": "dark",
  "timezone": "Europe/Berlin"
}
// → output
{
  "theme": "dark",
  "timezone": "Europe/Berlin"
}
// note: Dark theme, Berlin time.
```

##### `account.notifications.get`

- **Summary**: Read notification preferences.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/account.notifications.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "marketingEmails": false,
  "securityAlerts": true,
  "billingAlerts": true,
  "productUpdates": false,
  "agentSessionStarted": true,
  "agentSessionAnomaly": true,
  "digestCadence": "weekly"
}
// note: Read prefs.
```

##### `account.notifications.update`

- **Summary**: Update notification preferences.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/account.notifications.update`

**Example**:

```jsonc
// input
{
  "agentSessionAnomaly": true
}
// → output
{
  "marketingEmails": false,
  "securityAlerts": true,
  "billingAlerts": true,
  "productUpdates": false,
  "agentSessionStarted": true,
  "agentSessionAnomaly": true,
  "digestCadence": "weekly"
}
// note: Turn on anomaly alerts.
```

##### `account.token.list`

- **Summary**: List your Personal Access Tokens (PATs).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/account.token.list`

**Example**:

```jsonc
// input
{
  "includeRevoked": false
}
// → output
{
  "tokens": []
}
// note: List active PATs.
```

##### `account.token.issue`

- **Summary**: Issue a new Personal Access Token. Cleartext shown ONCE.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `key.issued`
- **Rate class**: `default`
- **Surfaces**: rest, dashboard
- **REST endpoint**: `POST /v1/actions/account.token.issue`

**Example**:

```jsonc
// input
{
  "label": "CI pipeline",
  "scopes": [
    "read:workspace",
    "write:entpoind"
  ],
  "expiresInDays": 90
}
// → output
{
  "token": {
    "id": "tv_pat_ABC20CHARSFOREXAMPLEID",
    "prefix": "tv_pat_abc",
    "label": "CI pipeline",
    "scopes": [
      "read:workspace",
      "write:entpoind"
    ],
    "createdAt": "2026-05-22T12:00:00.000Z",
    "expiresAt": "2026-08-20T12:00:00.000Z",
    "lastUsedAt": null,
    "revokedAt": null
  },
  "cleartext": "tv_pat_abc_REDACTED_EXAMPLE_ONLY"
}
// note: Mint a new PAT; cleartext shown once.
```

##### `account.token.revoke`

- **Summary**: Revoke a PAT (cannot be disabled — safety floor).
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `key.revoked`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/account.token.revoke`

**Example**:

```jsonc
// input
{
  "tokenId": "tv_pat_ABC20CHARSFOREXAMPLEID"
}
// → output
{
  "revoked": true,
  "propagatedAt": "2026-05-22T12:00:00.000Z"
}
// note: Revoke a PAT.
```

##### `account.oauth-grants.list`

- **Summary**: List active OAuth grants to third-party agents (Claude, ChatGPT, Gemini, etc.).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/account.oauth-grants.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "grants": []
}
// note: List active connected apps.
```

##### `account.oauth-grants.revoke`

- **Summary**: Revoke an OAuth grant. The third-party agent's tokens are immediately invalidated.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `key.revoked`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/account.oauth-grants.revoke`

**Example**:

```jsonc
// input
{
  "clientId": "oauth_CLAUDECOWORK0000000000"
}
// → output
{
  "revoked": true,
  "propagatedAt": "2026-05-22T12:00:00.000Z"
}
// note: Kill a connected app session.
```

##### `account.security-log.list`

- **Summary**: Read the account-level security log (logins, MFA, key issuance, anomalies).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/account.security-log.list`

**Example**:

```jsonc
// input
{
  "limit": 25
}
// → output
{
  "entries": [],
  "nextCursor": null
}
// note: Last 25 security events.
```

##### `account.delete`

- **Summary**: Schedule account deletion in 30 days. Requires WebAuthn step-up.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/account.delete`

**Example**:

```jsonc
// input
{
  "reason": "I no longer use this account; please delete in 30 days",
  "exportFirst": true
}
// → output
{
  "scheduledDeletionAt": "2026-06-21T00:00:00.000Z",
  "gracePeriodDays": 30
}
// note: Start account deletion with grace period.
```

### `org` (26 actions)

Organization-level CRUD, members, roles. Requires `organization.admin` for writes.

##### `org.get`

- **Summary**: Get the current organization's details.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "id": "org_DEMO00000000000000000000",
  "name": "Demo Org",
  "plan": "pro",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "scheduledDeletionAt": null
}
// note: Read org metadata.
```

##### `org.update`

- **Summary**: Update organization name + locale.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `organization.rename`
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.update`

**Example**:

```jsonc
// input
{
  "name": "New Org Name"
}
// → output
{
  "id": "org_DEMO00000000000000000000",
  "name": "New Org Name",
  "plan": "pro",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "scheduledDeletionAt": null
}
// note: Rename the organization.
```

##### `org.locale.set`

- **Summary**: Set the organization-default locale (inherited by new workspaces).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `organization.rename`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.locale.set`

**Example**:

```jsonc
// input
{
  "locale": "de"
}
// → output
{
  "locale": "de"
}
// note: Org-default locale → German.
```

##### `org.billing-state.get`

- **Summary**: Get the org's current billing state (plan, subscription status, add-ons).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `billing.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.billing-state.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "plan": "pro",
  "subscriptionStatus": "active",
  "multiWorkspaceAddonActive": true,
  "extraWorkspacesCount": 2,
  "currentPeriodEnd": "2026-06-22T00:00:00.000Z"
}
// note: Read billing state.
```

##### `org.member.list`

- **Summary**: List organization members.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `members.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.member.list`

**Example**:

```jsonc
// input
{
  "limit": 25
}
// → output
{
  "members": [],
  "nextCursor": null
}
// note: List org members.
```

##### `org.member.invite`

- **Summary**: Invite a new member to the organization. Sends a verification email.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `members.invite`
- **Audit kind**: `member.invited`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.member.invite`

**Example**:

```jsonc
// input
{
  "email": "newmember@example.com",
  "role": "member"
}
// → output
{
  "invitationId": "inv_abc",
  "email": "newmember@example.com",
  "role": "member",
  "invitedBy": "acc_DEMO00000000000000000000",
  "invitedAt": "2026-05-22T12:00:00.000Z",
  "expiresAt": "2026-05-29T12:00:00.000Z",
  "status": "pending"
}
// note: Invite a new member.
```

##### `org.member.remove`

- **Summary**: Remove a member from the organization. They lose access to all workspaces immediately.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `members.remove`
- **Audit kind**: `member.removed`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.member.remove`

**Example**:

```jsonc
// input
{
  "accountId": "acc_DEMO00000000000000000000"
}
// → output
{
  "removed": true
}
// note: Remove a member.
```

##### `org.member.role.change`

- **Summary**: Change an org member's role.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `members.change_role`
- **Audit kind**: `member.role_changed`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.member.role.change`

**Example**:

```jsonc
// input
{
  "accountId": "acc_DEMO00000000000000000000",
  "role": "admin"
}
// → output
{
  "accountId": "acc_DEMO00000000000000000000",
  "email": "member@example.com",
  "role": "admin",
  "joinedAt": "2026-01-01T00:00:00.000Z"
}
// note: Promote to admin.
```

##### `org.invitations.list`

- **Summary**: List pending/expired invitations.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `members.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.invitations.list`

**Example**:

```jsonc
// input
{
  "status": "pending"
}
// → output
{
  "invitations": []
}
// note: List pending invites.
```

##### `org.invitations.resend`

- **Summary**: Resend a pending invitation (subject to 5-minute cooldown).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `members.invite`
- **Audit kind**: `member.invited`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.invitations.resend`

**Example**:

```jsonc
// input
{
  "invitationId": "inv_abc"
}
// → output
{
  "resent": true,
  "nextResendAvailableAt": "2026-05-22T12:05:00.000Z"
}
// note: Resend invite.
```

##### `org.invitations.revoke`

- **Summary**: Revoke a pending invitation.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `members.invite`
- **Audit kind**: `member.removed`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.invitations.revoke`

**Example**:

```jsonc
// input
{
  "invitationId": "inv_abc"
}
// → output
{
  "revoked": true
}
// note: Cancel pending invite.
```

##### `org.transfer-ownership`

- **Summary**: Transfer org ownership to another admin. Requires WebAuthn step-up + reason.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `organization.transfer_ownership`
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.transfer-ownership`

**Example**:

```jsonc
// input
{
  "newOwnerAccountId": "acc_DEMO00000000000000000000",
  "reason": "Stepping down from CEO role; handing over to incoming lead"
}
// → output
{
  "id": "org_DEMO00000000000000000000",
  "name": "Demo Org",
  "plan": "pro",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "scheduledDeletionAt": null
}
// note: Hand off org ownership.
```

##### `org.delete.schedule`

- **Summary**: Schedule organization deletion in 30 days. Cancellable within the grace window.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `organization.delete`
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.delete.schedule`

**Example**:

```jsonc
// input
{
  "reason": "Winding down the company; please delete after 30 days of grace"
}
// → output
{
  "scheduledDeletionAt": "2026-06-21T00:00:00.000Z"
}
// note: Schedule org deletion.
```

##### `org.delete.cancel`

- **Summary**: Cancel a previously-scheduled org deletion (within grace).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `organization.delete`
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.delete.cancel`

**Example**:

```jsonc
// input
{}
// → output
{
  "id": "org_DEMO00000000000000000000",
  "name": "Demo Org",
  "plan": "pro",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "scheduledDeletionAt": null
}
// note: Cancel scheduled deletion.
```

##### `org.audit.list`

- **Summary**: Read org-level audit log entries (admin actions, member changes, billing).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view_audit_log`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.audit.list`

**Example**:

```jsonc
// input
{
  "limit": 25
}
// → output
{
  "entries": [],
  "nextCursor": null
}
// note: Read org audit log.
```

##### `org.sso.connections.list`

- **Summary**: List the organization's SSO connections (SAML/OIDC), with sealed secrets redacted to booleans.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.configure_sso`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.sso.connections.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "connections": []
}
// note: List SSO connections.
```

##### `org.sso.connections.upsert`

- **Summary**: Create or update a SAML/OIDC SSO connection. A provided OIDC client secret is sealed; SAML certificates are validated.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `settings.configure_sso`
- **Audit kind**: `org.sso_config_changed`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.sso.connections.upsert`

**Example**:

```jsonc
// input
{
  "type": "oidc",
  "displayName": "Okta",
  "oidcIssuer": "https://acme.okta.com",
  "oidcClientId": "0oa1"
}
// → output
{
  "connection": null
}
// note: Create an OIDC connection.
```

##### `org.sso.connections.delete`

- **Summary**: Delete an SSO connection by id (org-scoped).
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `settings.configure_sso`
- **Audit kind**: `org.sso_config_changed`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.sso.connections.delete`

**Example**:

```jsonc
// input
{
  "id": "ssoc_abc"
}
// → output
{
  "deleted": true
}
// note: Delete a connection.
```

##### `org.sso.domains.list`

- **Summary**: List the organization's captured SSO domains (verified state + the DNS TXT record to publish).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.configure_sso`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.sso.domains.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "domains": []
}
// note: List SSO domains.
```

##### `org.sso.domains.create`

- **Summary**: Claim an email domain for SSO and mint its DNS TXT verification challenge.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `settings.configure_sso`
- **Audit kind**: `org.sso_config_changed`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.sso.domains.create`

**Example**:

```jsonc
// input
{
  "domain": "acme.com"
}
// → output
{
  "domain": null
}
// note: Claim acme.com.
```

##### `org.sso.domains.verify`

- **Summary**: Verify a claimed domain via a DNS-over-HTTPS TXT lookup (proof of control).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `settings.configure_sso`
- **Audit kind**: `org.sso_config_changed`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.sso.domains.verify`

**Example**:

```jsonc
// input
{
  "id": "ssod_abc"
}
// → output
{
  "verified": true
}
// note: Verify domain control.
```

##### `org.sso.domains.enforcement`

- **Summary**: Toggle SSO enforcement for a verified domain (requires a verified domain + an active connection).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `settings.configure_sso`
- **Audit kind**: `org.sso_config_changed`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.sso.domains.enforcement`

**Example**:

```jsonc
// input
{
  "id": "ssod_abc",
  "enforceSso": true
}
// → output
{
  "domain": null
}
// note: Require SSO for the domain.
```

##### `org.sso.domains.delete`

- **Summary**: Remove a captured SSO domain (org-scoped).
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `settings.configure_sso`
- **Audit kind**: `org.sso_config_changed`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.sso.domains.delete`

**Example**:

```jsonc
// input
{
  "id": "ssod_abc"
}
// → output
{
  "deleted": true
}
// note: Delete a domain.
```

##### `org.sso.scim-tokens.list`

- **Summary**: List a connection's SCIM bearer tokens (hash-only; the raw token is never returned).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.configure_sso`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.sso.scim-tokens.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "tokens": []
}
// note: List SCIM tokens.
```

##### `org.sso.scim-tokens.mint`

- **Summary**: Mint a SCIM 2.0 bearer token for a connection. The RAW token is returned exactly once; only its hash is stored.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `settings.configure_sso`
- **Audit kind**: `org.sso_config_changed`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.sso.scim-tokens.mint`

**Example**:

```jsonc
// input
{
  "connectionId": "ssoc_abc"
}
// → output
{
  "id": "scimt_1",
  "connectionId": "ssoc_abc",
  "token": "scim_…",
  "scimBaseUrl": "https://api.trustvice.com/scim/v2",
  "createdAt": "2026-07-21T00:00:00.000Z"
}
// note: Mint a SCIM token (shown once).
```

##### `org.sso.scim-tokens.revoke`

- **Summary**: Revoke a SCIM bearer token by id.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `settings.configure_sso`
- **Audit kind**: `org.sso_config_changed`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/org.sso.scim-tokens.revoke`

**Example**:

```jsonc
// input
{
  "id": "scimt_1"
}
// → output
{
  "revoked": true
}
// note: Revoke a SCIM token.
```

### `workspace` (16 actions)

Workspace CRUD, members, settings, region binding. Workspace creation is billing-impacting (free tier permanent; paid workspaces require Stripe).

##### `workspace.list`

- **Summary**: List all workspaces in the current organization.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `workspaces.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/workspace.list`

**Example**:

```jsonc
// input
{
  "limit": 10
}
// → output
{
  "workspaces": [],
  "nextCursor": null
}
// note: List up to 10 workspaces in the active organization.
```

##### `workspace.get`

- **Summary**: Get the full state of a single workspace by id.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `workspaces.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/workspace.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "id": "ws_DEMODEFAULT0000000000",
  "name": "Default workspace"
}
// note: Read the active workspace's full state.
```

##### `workspace.create`

- **Summary**: Create a new workspace in the current organization.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `workspaces.create`
- **Audit kind**: `workspace.created`
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/workspace.create`

**Example**:

```jsonc
// input
{
  "name": "EU production",
  "regionId": "cloudflare-d1:weur-1",
  "euJurisdictionBound": true
}
// → output
{
  "id": "ws_new",
  "name": "EU production",
  "organizationId": "org_demo",
  "jurisdiction": "WEUR"
}
// note: Create an EU-bound workspace in Western Europe.
```

##### `workspace.update`

- **Summary**: Update workspace settings (name, retention, locale, Trustvice Receipts controls).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `settings.view`, `workspace.rename`
- **Audit kind**: `workspace.renamed`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/workspace.update`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "name": "Default"
}
// → output
{
  "id": "ws_DEMODEFAULT0000000000",
  "name": "Default",
  "organizationId": "org_demo",
  "jurisdiction": "WEUR"
}
// note: Rename a workspace — the one field this surface updates today.
```

##### `workspace.rename`

- **Summary**: Rename a workspace (convenience alias of workspace.update).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `settings.view`, `workspace.rename`
- **Audit kind**: `workspace.renamed`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/workspace.rename`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "name": "EU production v2"
}
// → output
{
  "id": "ws_DEMODEFAULT0000000000",
  "name": "EU production v2",
  "organizationId": "org_demo",
  "jurisdiction": "WEUR"
}
// note: Rename a workspace.
```

##### `workspace.delete.schedule`

- **Summary**: Schedule a workspace for deletion in 30 days (grace period).
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `workspaces.delete`, `workspace.schedule_deletion`
- **Audit kind**: `workspace.scheduled_deletion`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/workspace.delete.schedule`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "reason": "Migrated to new workspace; cleanup in progress"
}
// → output
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "scheduledDeletionAt": "2026-06-21T00:00:00.000Z"
}
// note: Schedule deletion with a 30-day grace.
```

##### `workspace.delete.cancel`

- **Summary**: Cancel a previously-scheduled workspace deletion (within grace).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `workspaces.delete`, `workspace.schedule_deletion`
- **Audit kind**: `workspace.deletion_canceled`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/workspace.delete.cancel`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "id": "ws_DEMODEFAULT0000000000",
  "name": "Default",
  "organizationId": "org_demo",
  "jurisdiction": "WEUR"
}
// note: Cancel deletion within the grace window.
```

##### `workspace.region.binding-proof`

- **Summary**: Download the OpenTimestamps proof of the workspace's region binding.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `workspaces.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/workspace.region.binding-proof`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "otsProof": "base64-encoded-ots-proof-string-here-at-least-20-chars",
  "anchoredAt": "2026-05-22T12:00:00.000Z",
  "blockHeight": 854321
}
// note: Pull the region-binding OTS proof for offline verification.
```

##### `workspace.member.list`

- **Summary**: List members of a workspace with their roles.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `workspaces.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/workspace.member.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "members": [
    {
      "accountId": "acc_001demo000000000000000000",
      "role": "owner"
    }
  ]
}
// note: List workspace members.
```

##### `workspace.member.add`

- **Summary**: Add an organization member to a workspace with a specific role.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `members.invite`
- **Audit kind**: `member.joined`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/workspace.member.add`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "accountId": "acc_002DEMO000000000000000000",
  "role": "member"
}
// → output
{
  "accountId": "acc_002DEMO000000000000000000",
  "role": "member"
}
// note: Add a member.
```

##### `workspace.member.role.change`

- **Summary**: Change a workspace member's role.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `members.change_role`
- **Audit kind**: `member.role_changed`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/workspace.member.role.change`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "accountId": "acc_002DEMO000000000000000000",
  "role": "admin"
}
// → output
{
  "accountId": "acc_002DEMO000000000000000000",
  "role": "admin"
}
// note: Promote a member to admin.
```

##### `workspace.member.remove`

- **Summary**: Remove a member from a workspace.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `members.remove`
- **Audit kind**: `member.removed`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/workspace.member.remove`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "accountId": "acc_002DEMO000000000000000000"
}
// → output
{
  "removed": true
}
// note: Remove a workspace member.
```

##### `workspace.transfer-ownership`

- **Summary**: Transfer workspace ownership to another admin.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `workspaces.transfer`
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/workspace.transfer-ownership`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "newOwnerAccountId": "acc_002DEMO000000000000000000",
  "reason": "Handing over to new compliance lead per Q3 reorg"
}
// → output
{
  "id": "ws_DEMODEFAULT0000000000",
  "name": "Default",
  "organizationId": "org_demo",
  "jurisdiction": "WEUR"
}
// note: Transfer ownership — destructive, requires confirmation.
```

##### `workspace.entpoind.enable`

- **Summary**: Enable Trustvice Receipts on a workspace (requires an org-level Trustvice Receipts subscription).
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `settings.view`, `workspace.rename`
- **Audit kind**: `workspace.renamed`
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/workspace.entpoind.enable`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "id": "ws_DEMODEFAULT0000000000",
  "name": "Default",
  "organizationId": "org_demo",
  "jurisdiction": "WEUR"
}
// note: Enable Entpoind on a workspace.
```

##### `workspace.entpoind.disable`

- **Summary**: Disable Trustvice Receipts on a workspace.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `settings.view`, `workspace.rename`
- **Audit kind**: `workspace.renamed`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/workspace.entpoind.disable`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "id": "ws_DEMODEFAULT0000000000",
  "name": "Default",
  "organizationId": "org_demo",
  "jurisdiction": "WEUR"
}
// note: Turn off Entpoind on this workspace.
```

##### `workspace.regions.list`

- **Summary**: List the available regions a workspace can be created in.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/workspace.regions.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "regions": [
    {
      "id": "cloudflare-d1:weur-1",
      "label": "Europe Central",
      "countryCode": "EU",
      "euJurisdictionBound": true
    }
  ]
}
// note: List every supported region for region picker UIs.
```

### `billing` (30 actions)

Subscription, packs, top-ups, invoices, cost centers. All write actions require confirmation tokens.

##### `billing.subscription.get`

- **Summary**: Get the org's current Stripe subscription.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `billing.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.subscription.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "subscriptionId": "sub_abc",
  "organizationId": "org_DEMO00000000000000000000",
  "plan": "pro",
  "status": "active",
  "currentPeriodStart": "2026-05-01T00:00:00.000Z",
  "currentPeriodEnd": "2026-06-01T00:00:00.000Z",
  "cancelAtPeriodEnd": false
}
// note: Read subscription.
```

##### `billing.subscription.upgrade`

- **Summary**: Upgrade to a higher tier. Prorates charges; takes effect immediately.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `billing.change_plan`
- **Audit kind**: `plan.changed`
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.subscription.upgrade`

**Example**:

```jsonc
// input
{
  "targetPlan": "team"
}
// → output
{
  "subscriptionId": "sub_abc",
  "organizationId": "org_DEMO00000000000000000000",
  "plan": "team",
  "status": "active",
  "currentPeriodStart": "2026-05-22T12:00:00.000Z",
  "currentPeriodEnd": "2026-06-22T12:00:00.000Z",
  "cancelAtPeriodEnd": false
}
// note: Upgrade to Team.
```

##### `billing.subscription.downgrade`

- **Summary**: Downgrade to a lower tier. Effective at next billing period.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `billing.change_plan`
- **Audit kind**: `plan.changed`
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.subscription.downgrade`

**Example**:

```jsonc
// input
{
  "targetPlan": "starter",
  "reason": "Reducing usage; no longer need Pro"
}
// → output
{
  "subscriptionId": "sub_abc",
  "organizationId": "org_DEMO00000000000000000000",
  "plan": "pro",
  "status": "active",
  "currentPeriodStart": "2026-05-01T00:00:00.000Z",
  "currentPeriodEnd": "2026-06-01T00:00:00.000Z",
  "cancelAtPeriodEnd": false
}
// note: Downgrade scheduled for period end.
```

##### `billing.subscription.cancel`

- **Summary**: Cancel subscription at current period end. Workspace remains accessible until then.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `billing.change_plan`
- **Audit kind**: `plan.changed`
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.subscription.cancel`

**Example**:

```jsonc
// input
{
  "reason": "Migrating to alternative provider; export complete"
}
// → output
{
  "subscriptionId": "sub_abc",
  "organizationId": "org_DEMO00000000000000000000",
  "plan": "pro",
  "status": "active",
  "currentPeriodStart": "2026-05-01T00:00:00.000Z",
  "currentPeriodEnd": "2026-06-01T00:00:00.000Z",
  "cancelAtPeriodEnd": true
}
// note: Cancel at period end.
```

##### `billing.subscription.reactivate`

- **Summary**: Reactivate a subscription that's been scheduled to cancel.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `billing.change_plan`
- **Audit kind**: `plan.changed`
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.subscription.reactivate`

**Example**:

```jsonc
// input
{}
// → output
{
  "subscriptionId": "sub_abc",
  "organizationId": "org_DEMO00000000000000000000",
  "plan": "pro",
  "status": "active",
  "currentPeriodStart": "2026-05-01T00:00:00.000Z",
  "currentPeriodEnd": "2026-06-01T00:00:00.000Z",
  "cancelAtPeriodEnd": false
}
// note: Reactivate.
```

##### `billing.invoices.list`

- **Summary**: List invoices.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `billing.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.invoices.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "invoices": [],
  "nextCursor": null
}
// note: List invoices.
```

##### `billing.invoices.get`

- **Summary**: Get a single invoice.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `billing.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.invoices.get`

**Example**:

```jsonc
// input
{
  "invoiceId": "in_abc"
}
// → output
{
  "id": "in_abc",
  "organizationId": "org_DEMO00000000000000000000",
  "amount": 4900,
  "currency": "USD",
  "status": "paid",
  "issuedAt": "2026-05-01T00:00:00.000Z",
  "dueAt": null,
  "paidAt": "2026-05-01T00:00:00.000Z"
}
// note: Read invoice.
```

##### `billing.invoices.download`

- **Summary**: Get a signed download URL for the invoice PDF.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `billing.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.invoices.download`

**Example**:

```jsonc
// input
{
  "invoiceId": "in_abc"
}
// → output
{
  "url": "https://files.stripe.com/invoices/abc.pdf",
  "expiresAt": "2026-05-22T13:00:00.000Z"
}
// note: Download invoice PDF.
```

##### `billing.payment-method.get`

- **Summary**: Get the current default payment method (masked).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `billing.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.payment-method.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "paymentMethodId": "pm_abc",
  "brand": "Visa",
  "last4": "4242",
  "expMonth": 12,
  "expYear": 2027
}
// note: Read masked payment method.
```

##### `billing.payment-method.update-url`

- **Summary**: Get a signed URL to Stripe's hosted payment-method update page. Update happens in Stripe's UI.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `billing.change_plan`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.payment-method.update-url`

**Example**:

```jsonc
// input
{}
// → output
{
  "url": "https://billing.stripe.com/p/session/abc",
  "expiresAt": "2026-05-22T13:00:00.000Z"
}
// note: Get Stripe Portal URL.
```

##### `billing.packs.list`

- **Summary**: List available top-up packs (runs, Number One queries, Trustvice calls).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.packs.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "packs": [
    {
      "packId": "runs_1k",
      "kind": "runs",
      "unitCount": 1000,
      "priceUsdMinor": 2900
    }
  ]
}
// note: Discover packs.
```

##### `billing.packs.purchase`

- **Summary**: Purchase a top-up pack.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `billing.buy_pack`
- **Audit kind**: `pack.purchased`
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.packs.purchase`

**Example**:

```jsonc
// input
{
  "packId": "runs_1k",
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "topUpId": "tu_abc",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "packKind": "runs",
  "unitCount": 1000,
  "priceUsdMinor": 2900,
  "purchasedAt": "2026-05-22T12:00:00.000Z",
  "unitsRemaining": 1000,
  "forfeitedAt": null
}
// note: Buy a 1k-run pack.
```

##### `billing.auto-topup.get`

- **Summary**: Get auto-topup configuration.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `billing.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.auto-topup.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "enabled": false,
  "packId": null,
  "triggerAtPercent": null,
  "monthlyCapUsdMinor": null
}
// note: Read auto-topup config.
```

##### `billing.auto-topup.configure`

- **Summary**: Configure auto-topup. Fires when balance drops below threshold; capped at monthly USD limit.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `billing.configure_autotopup`
- **Audit kind**: `auto_topup.configured`
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.auto-topup.configure`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "enabled": true,
  "packId": "runs_1k",
  "triggerAtPercent": 80,
  "monthlyCapUsdMinor": 10000
}
// → output
{
  "enabled": true,
  "packId": "runs_1k",
  "triggerAtPercent": 80,
  "monthlyCapUsdMinor": 10000
}
// note: Enable auto-topup.
```

##### `billing.cost-centers.list`

- **Summary**: List org cost centers (for tagging charges + per-cost-center invoicing).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `billing.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.cost-centers.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "costCenters": []
}
// note: List cost centers.
```

##### `billing.cost-centers.create`

- **Summary**: Create a cost center.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `billing.change_plan`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.cost-centers.create`

**Example**:

```jsonc
// input
{
  "name": "Engineering",
  "description": "All engineering teams"
}
// → output
{
  "id": "cc_DEMO00000000000000000000",
  "organizationId": "org_DEMO00000000000000000000",
  "name": "Engineering",
  "taggableProducts": [
    "both"
  ],
  "monthlyCapUsdMinor": null,
  "notificationThresholdPercents": [
    50,
    80,
    100
  ],
  "createdAt": "2026-05-22T12:00:00.000Z"
}
// note: Create cost center.
```

##### `billing.cost-centers.update`

- **Summary**: Update a cost center.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `billing.change_plan`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.cost-centers.update`

**Example**:

```jsonc
// input
{
  "costCenterId": "cc_DEMO00000000000000000000",
  "monthlyCapUsdMinor": 50000
}
// → output
{
  "id": "cc_DEMO00000000000000000000",
  "organizationId": "org_DEMO00000000000000000000",
  "name": "Engineering",
  "taggableProducts": [
    "both"
  ],
  "monthlyCapUsdMinor": 50000,
  "notificationThresholdPercents": [
    50,
    80,
    100
  ],
  "createdAt": "2026-05-22T12:00:00.000Z"
}
// note: Set monthly cap.
```

##### `billing.cost-centers.delete`

- **Summary**: Delete a cost center. Tagged charges keep historical tag.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `billing.change_plan`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.cost-centers.delete`

**Example**:

```jsonc
// input
{
  "costCenterId": "cc_DEMO00000000000000000000"
}
// → output
{
  "deleted": true
}
// note: Delete.
```

##### `billing.cost-centers.assign-charge`

- **Summary**: Tag a charge / invoice line with a cost center.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `billing.change_plan`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.cost-centers.assign-charge`

**Example**:

```jsonc
// input
{
  "chargeId": "ch_abc",
  "costCenterId": "cc_DEMO00000000000000000000"
}
// → output
{
  "tagged": true
}
// note: Tag a charge.
```

##### `billing.entpoind.tier.set`

- **Summary**: Set the Trustvice Receipts subscription tier for the org.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `billing.change_plan`
- **Audit kind**: `plan.changed`
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.entpoind.tier.set`

**Example**:

```jsonc
// input
{
  "tier": "scale"
}
// → output
{
  "subscriptionId": "sub_entp_abc",
  "organizationId": "org_DEMO00000000000000000000",
  "plan": "scale",
  "status": "active",
  "currentPeriodStart": "2026-05-22T12:00:00.000Z",
  "currentPeriodEnd": "2026-06-22T12:00:00.000Z",
  "cancelAtPeriodEnd": false
}
// note: Set Entpoind tier.
```

##### `billing.entpoind.tier.get`

- **Summary**: Get the current Trustvice Receipts tier.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `billing.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.entpoind.tier.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "tier": "team",
  "monthlyCalls": 100000,
  "retentionDays": 365
}
// note: Read Entpoind tier.
```

##### `billing.entpoind.top-up.purchase`

- **Summary**: Purchase a Trustvice Receipts top-up pack (extra call quota for the current month).
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `billing.buy_pack`
- **Audit kind**: `pack.purchased`
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.entpoind.top-up.purchase`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "packId": "entpoind_100k"
}
// → output
{
  "topUpId": "tu_entp_abc",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "packKind": "entpoind-calls",
  "unitCount": 100000,
  "priceUsdMinor": 1900,
  "purchasedAt": "2026-05-22T12:00:00.000Z",
  "unitsRemaining": 100000,
  "forfeitedAt": null
}
// note: Buy 100k Entpoind calls.
```

##### `billing.entpoind.auto-overage.set`

- **Summary**: Configure auto-overage for an Entpoind-enabled workspace.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `billing.configure_autotopup`
- **Audit kind**: `auto_topup.configured`
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.entpoind.auto-overage.set`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "enabled": true,
  "capMultiplier": 3
}
// → output
{
  "enabled": true,
  "capMultiplier": 3
}
// note: Enable auto-overage at 3× cap.
```

##### `billing.entpoind.billing-mode.set`

- **Summary**: Set the Trustvice Receipts billing mode (combined vs separate Stripe subscription).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `billing.change_plan`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.entpoind.billing-mode.set`

**Example**:

```jsonc
// input
{
  "mode": "separate"
}
// → output
{
  "mode": "separate"
}
// note: Separate Stripe subscriptions for Trustvice + Entpoind.
```

##### `billing.entpoind.usage.current`

- **Summary**: Get current Trustvice Receipts usage for the org (calls used + remaining quota + auto-overage status).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `billing.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.entpoind.usage.current`

**Example**:

```jsonc
// input
{}
// → output
{
  "callsUsed": 45000,
  "monthlyAllowance": 100000,
  "remaining": 55000,
  "autoOverageActive": false,
  "periodEnd": "2026-06-01T00:00:00.000Z"
}
// note: Read current Entpoind usage.
```

##### `billing.notarian.subscribe`

- **Summary**: Subscribe to the Notarian add-on (per-tier subscription pricing).
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `billing.subscribe_addons`
- **Audit kind**: `notarian.subscribed`
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.notarian.subscribe`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "subscribed": true
}
// note: Subscribe to Notarian.
```

##### `billing.notarian.unsubscribe`

- **Summary**: Unsubscribe from Notarian at next billing period.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `billing.subscribe_addons`
- **Audit kind**: `notarian.canceled`
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.notarian.unsubscribe`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "unsubscribed": true,
  "effectiveAt": "2026-06-22T00:00:00.000Z"
}
// note: Unsubscribe Notarian.
```

##### `billing.infinite-memory.subscribe`

- **Summary**: Subscribe to the Infinite Memory add-on for Number One ($19/mo on paid tiers).
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `billing.subscribe_addons`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.infinite-memory.subscribe`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "subscribed": true
}
// note: Subscribe Infinite Memory.
```

##### `billing.infinite-memory.unsubscribe`

- **Summary**: Unsubscribe Infinite Memory at next billing period.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `billing.subscribe_addons`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.infinite-memory.unsubscribe`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "unsubscribed": true,
  "effectiveAt": "2026-06-22T00:00:00.000Z"
}
// note: Unsubscribe Infinite Memory.
```

##### `billing.retention-extension.subscribe`

- **Summary**: Subscribe to the universal paid retention extension. Convenience alias of retention.extension.subscribe.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `billing.subscribe_addons`
- **Audit kind**: `retention.updated`
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/billing.retention-extension.subscribe`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "extendedToDays": 1095
}
// → output
{
  "subscribed": true,
  "perGbCostUsdMinor": 1000
}
// note: Subscribe to 3-year retention extension.
```

### `keys` (10 actions)

Personal access tokens (`tv_pat_*`) + workspace API keys (`tv_*` control plane, `entp_*` Trustvice Receipts data plane).

##### `keys.list`

- **Summary**: List workspace API keys (active + revoked filter).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `keys.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/keys.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "keys": [],
  "nextCursor": null
}
// note: List active keys.
```

##### `keys.get`

- **Summary**: Get a single workspace API key by id.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `keys.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/keys.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "keyId": "tv_workspace_ABC20CHARSFOREXAMPLEID"
}
// → output
{
  "id": "tv_workspace_ABC20CHARSFOREXAMPLEID",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "product": "trustvice",
  "label": "Prod key",
  "prefix": "tv_abc",
  "scopes": [
    "ingest:write"
  ],
  "createdAt": "2026-05-22T12:00:00.000Z",
  "lastUsedAt": null,
  "expiresAt": null,
  "revokedAt": null
}
// note: Fetch one key.
```

##### `keys.issue`

- **Summary**: Issue a new workspace API key. Cleartext returned ONCE.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `keys.create`
- **Audit kind**: `key.issued`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/keys.issue`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "product": "trustvice",
  "label": "Prod ingest key",
  "scopes": [
    "ingest:write"
  ],
  "expiry": "1y"
}
// → output
{
  "key": {
    "id": "tv_workspace_ABC20CHARSFOREXAMPLEID",
    "workspaceId": "ws_DEMODEFAULT0000000000",
    "product": "trustvice",
    "label": "Prod ingest key",
    "prefix": "tv_abc",
    "scopes": [
      "ingest:write"
    ],
    "createdAt": "2026-05-22T12:00:00.000Z",
    "lastUsedAt": null,
    "expiresAt": "2027-05-22T12:00:00.000Z",
    "revokedAt": null
  },
  "cleartext": "tv_abc_REDACTED_EXAMPLE_ONLY"
}
// note: Mint a new key; cleartext shown once.
```

##### `keys.revoke`

- **Summary**: Revoke a workspace API key. Propagates in ≤30s.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `keys.revoke`
- **Audit kind**: `key.revoked`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/keys.revoke`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "keyId": "tv_workspace_ABC20CHARSFOREXAMPLEID"
}
// → output
{
  "revoked": true,
  "propagatedAt": "2026-05-22T12:00:00.000Z"
}
// note: Revoke a key.
```

##### `keys.rotate`

- **Summary**: Rotate a key: revoke the current value + issue a replacement with the same label + scopes. Cleartext returned ONCE.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `keys.create`, `keys.revoke`
- **Audit kind**: `key.rotated`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/keys.rotate`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "keyId": "tv_workspace_ABC20CHARSFOREXAMPLEID"
}
// → output
{
  "revokedKeyId": "tv_workspace_ABC20CHARSFOREXAMPLEID",
  "newKey": {
    "id": "tv_workspace_def20charsforexampleid",
    "workspaceId": "ws_DEMODEFAULT0000000000",
    "product": "trustvice",
    "label": "Prod ingest key",
    "prefix": "tv_def",
    "scopes": [
      "ingest:write"
    ],
    "createdAt": "2026-05-22T12:00:00.000Z",
    "lastUsedAt": null,
    "expiresAt": null,
    "revokedAt": null
  },
  "cleartext": "tv_def_REDACTED_EXAMPLE_ONLY",
  "graceUntil": "2026-05-22T12:05:00.000Z"
}
// note: Rotate a key with 5-min grace.
```

##### `keys.scopes.list`

- **Summary**: List the available scope grants for workspace API keys.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/keys.scopes.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "scopes": [
    {
      "id": "ingest:write",
      "product": "tools",
      "label": "Ingest write",
      "description": "Send runs / events into the workspace",
      "severity": "write"
    }
  ]
}
// note: Discover scopes.
```

##### `keys.usage.get`

- **Summary**: Get usage statistics (calls + last-used + IP CIDRs) for a key over a time window.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `keys.view`
- **Audit kind**: `agent_read`
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/keys.usage.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "keyId": "tv_workspace_ABC20CHARSFOREXAMPLEID"
}
// → output
{
  "totalCalls": 12345,
  "uniqueIpCidrs": 3,
  "lastUsedAt": "2026-05-22T12:00:00.000Z",
  "perEndpointBreakdown": [
    {
      "path": "/v1/ingest",
      "count": 12000
    }
  ]
}
// note: Read key usage.
```

##### `keys.last-used.get`

- **Summary**: Quick lookup: when was this key last used?
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `keys.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/keys.last-used.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "keyId": "tv_workspace_ABC20CHARSFOREXAMPLEID"
}
// → output
{
  "lastUsedAt": "2026-05-22T12:00:00.000Z"
}
// note: Lightweight last-used check.
```

##### `keys.entpoind.list`

- **Summary**: Convenience: list only the Entpoind-product workspace keys.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `keys.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/keys.entpoind.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "keys": [],
  "nextCursor": null
}
// note: List Entpoind-only keys.
```

##### `keys.entpoind.issue`

- **Summary**: Issue an Entpoind-product workspace key (entp_*). Cleartext shown ONCE.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `keys.create`
- **Audit kind**: `key.issued`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/keys.entpoind.issue`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "label": "Trustvice Receipts attestation key",
  "scopes": [
    "entpoind:agent-call:write",
    "entpoind:content-attest:write"
  ],
  "expiry": "90d"
}
// → output
{
  "key": {
    "id": "entp_workspace_abc20charsforexampleid",
    "workspaceId": "ws_DEMODEFAULT0000000000",
    "product": "entpoind",
    "label": "Trustvice Receipts attestation key",
    "prefix": "entp_abc",
    "scopes": [
      "entpoind:agent-call:write",
      "entpoind:content-attest:write"
    ],
    "createdAt": "2026-05-22T12:00:00.000Z",
    "lastUsedAt": null,
    "expiresAt": "2026-08-20T12:00:00.000Z",
    "revokedAt": null
  },
  "cleartext": "entp_abc_REDACTED_EXAMPLE_ONLY"
}
// note: Mint an Entpoind key.
```

### `webhooks` (12 actions)

Outbound webhook endpoints + signing secrets + deliveries.

##### `webhooks.list`

- **Summary**: List webhook endpoints for a workspace.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `webhooks.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/webhooks.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "webhooks": [],
  "nextCursor": null
}
// note: List webhooks.
```

##### `webhooks.get`

- **Summary**: Get a single webhook endpoint.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `webhooks.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/webhooks.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "webhookId": "wh_DEMO00000000000000000000"
}
// → output
{
  "id": "wh_DEMO00000000000000000000",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "url": "https://example.com/webhook",
  "label": "Production hook",
  "events": [
    "alert.fired"
  ],
  "enabled": true,
  "secretPrefix": "whsec_ab",
  "createdAt": "2026-05-22T12:00:00.000Z",
  "updatedAt": "2026-05-22T12:00:00.000Z"
}
// note: Read a webhook.
```

##### `webhooks.create`

- **Summary**: Register a new webhook endpoint. Returns the signing secret cleartext ONCE.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `webhooks.create`
- **Audit kind**: `webhook.created`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/webhooks.create`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "url": "https://example.com/webhook",
  "label": "Prod hook",
  "events": [
    "alert.fired",
    "export.ready"
  ]
}
// → output
{
  "webhook": {
    "id": "wh_DEMO00000000000000000000",
    "workspaceId": "ws_DEMODEFAULT0000000000",
    "url": "https://example.com/webhook",
    "label": "Prod hook",
    "events": [
      "alert.fired",
      "export.ready"
    ],
    "enabled": true,
    "secretPrefix": "whsec_ab",
    "createdAt": "2026-05-22T12:00:00.000Z",
    "updatedAt": "2026-05-22T12:00:00.000Z"
  },
  "signingSecretCleartext": "whsec_REDACTED_EXAMPLE_ONLY"
}
// note: Create + receive signing secret.
```

##### `webhooks.update`

- **Summary**: Update a webhook's URL, label, or event subscriptions.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `webhooks.create`
- **Audit kind**: `webhook.updated`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/webhooks.update`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "webhookId": "wh_DEMO00000000000000000000",
  "events": [
    "alert.fired"
  ]
}
// → output
{
  "id": "wh_DEMO00000000000000000000",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "url": "https://example.com/webhook",
  "label": "Prod hook",
  "events": [
    "alert.fired"
  ],
  "enabled": true,
  "secretPrefix": "whsec_ab",
  "createdAt": "2026-05-22T12:00:00.000Z",
  "updatedAt": "2026-05-22T12:05:00.000Z"
}
// note: Narrow subscription set.
```

##### `webhooks.delete`

- **Summary**: Delete a webhook endpoint. Pending deliveries are abandoned.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `webhooks.delete`
- **Audit kind**: `webhook.deleted`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/webhooks.delete`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "webhookId": "wh_DEMO00000000000000000000"
}
// → output
{
  "deleted": true
}
// note: Remove a webhook.
```

##### `webhooks.enable`

- **Summary**: Enable or disable a webhook without deleting it.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `webhooks.create`
- **Audit kind**: `webhook.updated`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/webhooks.enable`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "webhookId": "wh_DEMO00000000000000000000",
  "enabled": false
}
// → output
{
  "id": "wh_DEMO00000000000000000000",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "url": "https://example.com/webhook",
  "label": "Prod hook",
  "events": [
    "alert.fired"
  ],
  "enabled": false,
  "secretPrefix": "whsec_ab",
  "createdAt": "2026-05-22T12:00:00.000Z",
  "updatedAt": "2026-05-22T12:10:00.000Z"
}
// note: Disable temporarily.
```

##### `webhooks.test-fire`

- **Summary**: Fire a synthetic test event to a webhook to verify delivery + signature validation.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `webhooks.create`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/webhooks.test-fire`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "webhookId": "wh_DEMO00000000000000000000"
}
// → output
{
  "deliveryId": "del_abc",
  "webhookId": "wh_DEMO00000000000000000000",
  "eventType": "webhook.test",
  "status": "success",
  "statusCode": 200,
  "attemptCount": 1,
  "attemptedAt": "2026-05-22T12:00:00.000Z",
  "responseTimeMs": 87
}
// note: Test webhook delivery.
```

##### `webhooks.events.list`

- **Summary**: List the event types this webhook can subscribe to (from the AsyncAPI 3 spec).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/webhooks.events.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "events": [
    {
      "id": "alert.fired",
      "description": "An alert rule fired.",
      "severity": "warning"
    }
  ]
}
// note: Discover event types.
```

##### `webhooks.events.replay`

- **Summary**: Replay missed events from a time window. Useful for recovering after webhook downtime.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `webhooks.create`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/webhooks.events.replay`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "webhookId": "wh_DEMO00000000000000000000",
  "since": "2026-05-21T00:00:00.000Z"
}
// → output
{
  "replayId": "rep_abc",
  "eventsQueued": 42
}
// note: Replay events from yesterday.
```

##### `webhooks.signing-secret.rotate`

- **Summary**: Rotate the HMAC signing secret. Old secret valid for 24h grace.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `webhooks.create`
- **Audit kind**: `webhook.updated`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/webhooks.signing-secret.rotate`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "webhookId": "wh_DEMO00000000000000000000"
}
// → output
{
  "newSigningSecretCleartext": "whsec_REDACTED_EXAMPLE_ONLY",
  "oldSecretValidUntil": "2026-05-23T12:00:00.000Z"
}
// note: Rotate webhook signing secret.
```

##### `webhooks.deliveries.list`

- **Summary**: List delivery attempts for a webhook (success + failure history).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `webhooks.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/webhooks.deliveries.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "webhookId": "wh_DEMO00000000000000000000"
}
// → output
{
  "deliveries": [],
  "nextCursor": null
}
// note: List delivery attempts.
```

##### `webhooks.deliveries.retry`

- **Summary**: Retry a specific failed delivery.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `webhooks.create`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/webhooks.deliveries.retry`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "webhookId": "wh_DEMO00000000000000000000",
  "deliveryId": "del_abc"
}
// → output
{
  "deliveryId": "del_abc",
  "webhookId": "wh_DEMO00000000000000000000",
  "eventType": "alert.fired",
  "status": "success",
  "statusCode": 200,
  "attemptCount": 2,
  "attemptedAt": "2026-05-22T12:00:00.000Z",
  "responseTimeMs": 42
}
// note: Retry a delivery.
```

### `alerts` (10 actions)

Alert rules + test fires + history. Backed by the Tops feed.

##### `alerts.list`

- **Summary**: List alert rules for a workspace.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/alerts.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "alerts": [],
  "nextCursor": null
}
// note: List alerts.
```

##### `alerts.get`

- **Summary**: Get a single alert rule.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/alerts.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "alertId": "alert_DEMO00000000000000000000"
}
// → output
{
  "id": "alert_DEMO00000000000000000000",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "type": "quota_threshold",
  "label": "80% quota",
  "enabled": true,
  "config": {
    "type": "quota_threshold",
    "thresholdPercent": 80,
    "quotaKind": "runs"
  },
  "channels": [],
  "lastFiredAt": null,
  "firedCount": 0,
  "createdAt": "2026-05-22T12:00:00.000Z",
  "updatedAt": "2026-05-22T12:00:00.000Z"
}
// note: Read an alert rule.
```

##### `alerts.create`

- **Summary**: Create a new alert rule.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `settings.view`
- **Audit kind**: `alert.created`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/alerts.create`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "type": "quota_threshold",
  "label": "80% quota",
  "config": {
    "type": "quota_threshold",
    "thresholdPercent": 80,
    "quotaKind": "runs"
  },
  "channels": [
    {
      "kind": "email",
      "addresses": [
        "ops@example.com"
      ]
    }
  ]
}
// → output
{
  "id": "alert_new0000000000000000000",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "type": "quota_threshold",
  "label": "80% quota",
  "enabled": true,
  "config": {
    "type": "quota_threshold",
    "thresholdPercent": 80,
    "quotaKind": "runs"
  },
  "channels": [
    {
      "kind": "email",
      "addresses": [
        "ops@example.com"
      ]
    }
  ],
  "lastFiredAt": null,
  "firedCount": 0,
  "createdAt": "2026-05-22T12:00:00.000Z",
  "updatedAt": "2026-05-22T12:00:00.000Z"
}
// note: Create alert.
```

##### `alerts.update`

- **Summary**: Update an alert's label / config / channels / enabled flag.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `settings.view`
- **Audit kind**: `alert.updated`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/alerts.update`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "alertId": "alert_DEMO00000000000000000000",
  "label": "Renamed"
}
// → output
{
  "id": "alert_DEMO00000000000000000000",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "type": "quota_threshold",
  "label": "Renamed",
  "enabled": true,
  "config": {},
  "channels": [],
  "lastFiredAt": null,
  "firedCount": 0,
  "createdAt": "2026-05-22T12:00:00.000Z",
  "updatedAt": "2026-05-22T12:05:00.000Z"
}
// note: Update alert.
```

##### `alerts.delete`

- **Summary**: Delete an alert rule.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `settings.view`
- **Audit kind**: `alert.deleted`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/alerts.delete`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "alertId": "alert_DEMO00000000000000000000"
}
// → output
{
  "deleted": true
}
// note: Delete alert.
```

##### `alerts.enable`

- **Summary**: Enable an alert rule.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `settings.view`
- **Audit kind**: `alert.updated`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/alerts.enable`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "alertId": "alert_DEMO00000000000000000000"
}
// → output
{
  "id": "alert_DEMO00000000000000000000",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "type": "quota_threshold",
  "label": "Quota",
  "enabled": true,
  "config": {},
  "channels": [],
  "lastFiredAt": null,
  "firedCount": 0,
  "createdAt": "2026-05-22T12:00:00.000Z",
  "updatedAt": "2026-05-22T12:00:00.000Z"
}
// note: Enable.
```

##### `alerts.disable`

- **Summary**: Disable an alert rule without deleting it.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `settings.view`
- **Audit kind**: `alert.updated`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/alerts.disable`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "alertId": "alert_DEMO00000000000000000000"
}
// → output
{
  "id": "alert_DEMO00000000000000000000",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "type": "quota_threshold",
  "label": "Quota",
  "enabled": false,
  "config": {},
  "channels": [],
  "lastFiredAt": null,
  "firedCount": 0,
  "createdAt": "2026-05-22T12:00:00.000Z",
  "updatedAt": "2026-05-22T12:00:00.000Z"
}
// note: Disable.
```

##### `alerts.test-fire`

- **Summary**: Fire a synthetic test of an alert to verify channels.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `settings.view`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/alerts.test-fire`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "alertId": "alert_DEMO00000000000000000000"
}
// → output
{
  "fired": true,
  "channelResults": [
    {
      "kind": "email",
      "success": true
    }
  ]
}
// note: Test fire.
```

##### `alerts.kinds.list`

- **Summary**: List all supported alert kinds + their config shapes + severity classifications.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/alerts.kinds.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "kinds": [
    {
      "id": "quota_threshold",
      "label": "Quota threshold tripped",
      "description": "Run or Number One quota crossed a configured percent of the monthly allowance.",
      "severity": "ops",
      "configurable": true
    }
  ]
}
// note: Discover alert kinds.
```

##### `alerts.history.list`

- **Summary**: List historical firings for a given alert rule.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/alerts.history.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "alertId": "alert_DEMO00000000000000000000"
}
// → output
{
  "firings": [],
  "nextCursor": null
}
// note: Read alert fire history.
```

### `exports` (10 actions)

Compliance exports + receipt bundles + EU AI Act Article 12 (statutory by August 2, 2026).

##### `exports.list`

- **Summary**: List exports for a workspace.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `exports.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/exports.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "exports": [],
  "nextCursor": null
}
// note: List exports.
```

##### `exports.get`

- **Summary**: Get a single export's status + metadata.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `exports.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/exports.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "exportId": "exp_abc"
}
// → output
{
  "exportId": "exp_abc",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "kind": "audit-log",
  "status": "ready",
  "format": "json",
  "requestedAt": "2026-05-22T12:00:00.000Z",
  "readyAt": "2026-05-22T12:10:00.000Z",
  "expiresAt": "2026-05-29T12:10:00.000Z"
}
// note: Read export status.
```

##### `exports.request`

- **Summary**: Request a new compliance export. Returns the export id; status polls reveal readiness.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `exports.create`
- **Audit kind**: `export.requested`
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/exports.request`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "kind": "compliance-bundle",
  "format": "zip"
}
// → output
{
  "exportId": "exp_abc",
  "estimatedReadyAt": "2026-05-22T12:10:00.000Z"
}
// note: Request a compliance bundle.
```

##### `exports.download`

- **Summary**: Get the signed download URL for a ready export (URL is time-bounded; SHA-256 included for integrity check).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `exports.download`
- **Audit kind**: `export.completed`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/exports.download`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "exportId": "exp_abc"
}
// → output
{
  "url": "https://r2.trustvice.com/exports/abc",
  "expiresAt": "2026-05-22T13:00:00.000Z",
  "sha256": "abcd1234567890abcdef1234567890abcdef1234567890abcdef12345678abcd"
}
// note: Get signed download URL.
```

##### `exports.verify`

- **Summary**: Verify an export's Ed25519 signature + OTS Bitcoin proof. Offline-verifiable.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/exports.verify`

**Example**:

```jsonc
// input
{
  "exportSha256": "abcd1234567890abcdef1234567890abcdef1234567890abcdef12345678abcd",
  "signature": "...",
  "signingKeyId": "trustvice-2026-q2-enam"
}
// → output
{
  "valid": true,
  "signatureValid": true,
  "otsValid": true,
  "errors": []
}
// note: Offline verify an export.
```

##### `exports.entpoind.receipt-bundle.request`

- **Summary**: Request a portable Entpoind-receipt bundle — JSON manifest + receipt files + public key JWK + verify README. Verifiable with @entpoind/verify.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `exports.create`
- **Audit kind**: `export.requested`
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/exports.entpoind.receipt-bundle.request`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "primitiveFilter": [
    "agent.call",
    "content.attest"
  ]
}
// → output
{
  "exportId": "exp_entp_abc",
  "estimatedReadyAt": "2026-05-22T12:15:00.000Z"
}
// note: Bundle Entpoind receipts.
```

##### `exports.eu-ai-act.article-12.request`

- **Summary**: Request an EU AI Act Article 12 compliant log bundle (prEN 18229-1 + ISO/IEC DIS 24970 schema). Cannot be disabled — regulatory mandate.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `exports.create`
- **Audit kind**: `export.requested`
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/exports.eu-ai-act.article-12.request`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "since": "2026-04-01T00:00:00.000Z",
  "until": "2026-05-01T00:00:00.000Z"
}
// → output
{
  "exportId": "exp_eu12_abc",
  "estimatedReadyAt": "2026-05-22T12:30:00.000Z",
  "schemaVersion": "prEN-18229-1-draft-2026-03"
}
// note: EU AI Act Art. 12 compliance export.
```

##### `exports.audit-log.request`

- **Summary**: Request a JSON or CSV export of the workspace audit log filtered by time + kind.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `exports.create`, `settings.view_audit_log`
- **Audit kind**: `export.requested`
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/exports.audit-log.request`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "format": "csv"
}
// → output
{
  "exportId": "exp_audit_abc",
  "estimatedReadyAt": "2026-05-22T12:10:00.000Z"
}
// note: Export audit log as CSV.
```

##### `exports.kinds.list`

- **Summary**: List the supported export kinds + their output formats + retention.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/exports.kinds.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "kinds": [
    {
      "id": "compliance-bundle",
      "label": "Compliance bundle",
      "description": "Full audit + custody + receipts + signing keys for offline verification.",
      "supportedFormats": [
        "zip"
      ],
      "retentionDays": 7
    }
  ]
}
// note: Discover export kinds.
```

##### `exports.delete`

- **Summary**: Delete a completed export (frees R2 storage immediately).
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `exports.view`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/exports.delete`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "exportId": "exp_abc"
}
// → output
{
  "deleted": true
}
// note: Delete an export.
```

### `retention` (15 actions)

Retention policy + paid extension. Hard caps default to 90d / 365d / unlimited by tier.

##### `retention.policy.get`

- **Summary**: Get the active retention policy for a workspace.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/retention.policy.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "retentionDays": 365,
  "isCustom": false,
  "appliedAt": "2026-01-01T00:00:00.000Z",
  "appliedBy": "tier_default"
}
// note: Read retention policy.
```

##### `retention.policy.update`

- **Summary**: Update workspace retention days (within tier limits).
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `settings.edit_retention`
- **Audit kind**: `retention.updated`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/retention.policy.update`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "retentionDays": 730
}
// → output
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "retentionDays": 730,
  "isCustom": true,
  "appliedAt": "2026-05-22T12:00:00.000Z",
  "appliedBy": "acc_DEMO00000000000000000000"
}
// note: Extend retention via paid extension.
```

##### `retention.histogram.get`

- **Summary**: Get a histogram of record ages in the workspace (helps visualize what's near purge).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view`
- **Audit kind**: `agent_read`
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/retention.histogram.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "buckets": [
    {
      "ageDays": 0,
      "recordCount": 1000
    },
    {
      "ageDays": 7,
      "recordCount": 900
    }
  ],
  "totalRecords": 12000,
  "oldestRecordAge": 350
}
// note: Read age distribution.
```

##### `retention.next-purge.preview`

- **Summary**: Preview which records will purge in the next cycle (live 1-Hz countdown on the dashboard).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/retention.next-purge.preview`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "purgeAt": "2026-05-22T13:00:00.000Z",
  "recordsToBepurged": 42,
  "sampleEntries": []
}
// note: Preview upcoming purge.
```

##### `retention.purge-history.list`

- **Summary**: List historical purge events with verification status.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/retention.purge-history.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "purges": [],
  "nextCursor": null
}
// note: Read purge history.
```

##### `retention.extension.subscribe`

- **Summary**: Subscribe to the paid retention extension at the per-tier rate.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `billing.subscribe_addons`
- **Audit kind**: `retention.updated`
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/retention.extension.subscribe`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "extendedToDays": 1095
}
// → output
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "extendedToDays": 1095,
  "monthlyCostUsdMinor": 1200,
  "perGbMonthlyCostUsdMinor": 1000,
  "storageGbBilled": 1.2,
  "startedAt": "2026-05-22T12:00:00.000Z",
  "canceledAt": null,
  "effectiveUntil": null
}
// note: Subscribe to 3-year retention extension.
```

##### `retention.extension.get`

- **Summary**: Get the current retention extension subscription (if any).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `billing.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/retention.extension.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "extendedToDays": 1825,
  "monthlyCostUsdMinor": 2400,
  "perGbMonthlyCostUsdMinor": 1000,
  "storageGbBilled": 2.4,
  "startedAt": "2026-05-22T12:00:00.000Z",
  "canceledAt": null,
  "effectiveUntil": null
}
// note: A workspace with the 5-year retention extension.
```

##### `retention.extension.update`

- **Summary**: Update the active retention extension (change duration).
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `billing.subscribe_addons`
- **Audit kind**: `retention.updated`
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/retention.extension.update`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "extendedToDays": 1825
}
// → output
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "extendedToDays": 1825,
  "monthlyCostUsdMinor": 2400,
  "perGbMonthlyCostUsdMinor": 1000,
  "storageGbBilled": 2.4,
  "startedAt": "2026-05-22T12:00:00.000Z",
  "canceledAt": null,
  "effectiveUntil": null
}
// note: Bump to 5-year retention.
```

##### `retention.extension.cancel`

- **Summary**: Cancel the retention extension at the end of the current billing period.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `billing.subscribe_addons`
- **Audit kind**: `retention.updated`
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/retention.extension.cancel`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "extendedToDays": 1825,
  "monthlyCostUsdMinor": 2400,
  "perGbMonthlyCostUsdMinor": 1000,
  "storageGbBilled": 2.4,
  "startedAt": "2026-05-22T12:00:00.000Z",
  "canceledAt": "2026-05-22T12:00:00.000Z",
  "effectiveUntil": "2026-06-22T00:00:00.000Z"
}
// note: Cancel at period end.
```

##### `retention.extension.rates.list`

- **Summary**: List the per-tier retention extension rates (USD cents per GB per month).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/retention.extension.rates.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "rates": [
    {
      "tier": "free",
      "perGbCentsPerMonth": 1200
    },
    {
      "tier": "starter",
      "perGbCentsPerMonth": 1100
    }
  ]
}
// note: List per-tier rates.
```

##### `retention.policy.suggested-tier.get`

- **Summary**: Recommend a higher tier if the workspace's data growth + retention needs make extension uneconomical.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `billing.view`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/retention.policy.suggested-tier.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "suggestedTier": "pro",
  "monthlySavingsUsdMinor": 800,
  "explanation": "At your current storage growth, Pro tier's bundled retention saves about $8/mo over the extension."
}
// note: Suggested upgrade.
```

##### `retention.audit.list`

- **Summary**: List retention-policy audit events (changes, purges, extensions).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view_audit_log`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/retention.audit.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "entries": [],
  "nextCursor": null
}
// note: Read retention audit.
```

##### `retention.subject-key.issue`

- **Summary**: Issue (or fetch) the per-subject data key whose destruction IS the erasure.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `settings.edit_retention`
- **Audit kind**: `retention.updated`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/retention.subject-key.issue`

**Example**:

```jsonc
// input
{
  "dataSubjectRefHash": "sha256:9f2c…"
}
// → output
{
  "keyId": "sk_01J9",
  "dek": "base64url…",
  "created": true
}
// note: The plaintext key is never stored, so destroying the row is the shred.
```

##### `retention.subject.shred`

- **Summary**: Destroy a data subject's key and append the destruction to the hash-chained shred ledger.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `settings.edit_retention`
- **Audit kind**: `retention.updated`
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/retention.subject.shred`

**Example**:

```jsonc
// input
{
  "dataSubjectRefHash": "sha256:9f2c…"
}
// → output
{
  "shredded": true,
  "keyId": "sk_01J9",
  "bytesAffected": 40211,
  "recordKinds": [
    "support_attachment"
  ],
  "chainSeq": 12,
  "reason": "The key was destroyed; the ciphertext it protected is unopenable.",
  "notes": []
}
// note: Destroy first, then append — a ledger entry for a destruction that did not happen is worse than no entry.
```

##### `retention.erasure-certificate.get`

- **Summary**: Certify what was destroyed for one data subject, with the chain verified.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/retention.erasure-certificate.get`

**Example**:

```jsonc
// input
{
  "dsrRef": "dsr_01J9",
  "dataSubjectRefHash": "sha256:9f2c…"
}
// → output
{
  "certificate": {
    "dsrRef": "dsr_01J9",
    "entries": 1
  },
  "chainVerified": true,
  "notes": []
}
// note: GDPR Art. 17 — what was destroyed, and what provably was not.
```

### `audit` (22 actions)

Three-tier audit log: workspace events (visible), custody chain (operator-only metadata), Tops feed (selectable detail level).

##### `audit.workspace.list`

- **Summary**: List audit log entries for a workspace.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view_audit_log`
- **Audit kind**: `agent_read`
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/audit.workspace.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "entries": [],
  "nextCursor": null
}
// note: Read workspace audit log.
```

##### `audit.workspace.get`

- **Summary**: Get a specific audit entry by id.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view_audit_log`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/audit.workspace.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "entryId": "aud_DEMO00000000000000000000"
}
// → output
{
  "id": "aud_DEMO00000000000000000000",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "timestamp": "2026-05-22T12:00:00.000Z",
  "kind": "workspace.created",
  "outcome": "success"
}
// note: Fetch a single entry.
```

##### `audit.workspace.search`

- **Summary**: Full-text search across a workspace's audit log.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view_audit_log`
- **Audit kind**: `agent_read`
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/audit.workspace.search`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "query": "alice@example.com"
}
// → output
{
  "entries": []
}
// note: Search for any mention of an email in the audit log.
```

##### `audit.workspace.live-tail`

- **Summary**: Open a streaming subscription to new audit entries (SSE/streamable HTTP).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: no
- **Permissions**: `settings.view_audit_log`
- **Audit kind**: `agent_read`
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/audit.workspace.live-tail`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "subscription": "sub_abc",
  "startedAt": "2026-05-22T12:00:00.000Z"
}
// note: Open a live tail subscription.
```

##### `audit.workspace.share`

- **Summary**: Generate a time-bounded share URL to an audit entry (for external auditors).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `settings.view_audit_log`
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/audit.workspace.share`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "entryId": "aud_DEMO00000000000000000000",
  "ttlHours": 24,
  "note": "Q3 audit — Foo & Co LLP"
}
// → output
{
  "shareUrl": "https://trustvice.com/audit/share/abc",
  "expiresAt": "2026-05-23T12:00:00.000Z"
}
// note: Share with auditor.
```

##### `audit.workspace.share.list`

- **Summary**: List the audit share links this workspace has minted, and whether each is still live.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view_audit_log`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/audit.workspace.share.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "shares": [
    {
      "shareId": "a1b2c3d4e5f6a1b2c3d4e5f6",
      "entryId": "aud_DEMO00000000000000000000",
      "note": "Q3 audit — Foo & Co LLP",
      "createdAt": "2026-05-22T12:00:00.000Z",
      "expiresAt": "2026-05-23T12:00:00.000Z",
      "revokedAt": null,
      "live": true
    }
  ],
  "count": 1
}
// note: See what has been shared.
```

##### `audit.workspace.share.revoke`

- **Summary**: Revoke an audit share link before it expires.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `settings.view_audit_log`
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/audit.workspace.share.revoke`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "shareId": "a1b2c3d4e5f6a1b2c3d4e5f6"
}
// → output
{
  "shareId": "a1b2c3d4e5f6a1b2c3d4e5f6",
  "revokedAt": "2026-05-22T18:00:00.000Z",
  "alreadyRevoked": false
}
// note: Close a share early.
```

##### `audit.custody.list`

- **Summary**: List custody chain entries for a workspace (hash-chained, Ed25519-signed).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view_audit_log`
- **Audit kind**: `agent_read`
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/audit.custody.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "entries": [],
  "nextCursor": null
}
// note: Read custody chain.
```

##### `audit.custody.get`

- **Summary**: Get a custody entry by id (includes Ed25519 signature for offline verification).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view_audit_log`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/audit.custody.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "entryId": "cust_DEMO0000-0000-0000-0000-000000000000"
}
// → output
{
  "id": "cus_DEMO00000000000000000000",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "timestamp": "2026-05-22T12:00:00.000Z",
  "prevHash": "0000000000000000000000000000000000000000000000000000000000000000",
  "entryHash": "abcd567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "signature": "...",
  "signingKeyId": "entpoind-2026-q2-enam"
}
// note: Fetch a custody entry.
```

##### `audit.custody.verify`

- **Summary**: Walk the workspace's custody chain and report whether it holds, naming the sequence where it breaks.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view_audit_log`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/audit.custody.verify`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "limit": 1000
}
// → output
{
  "ok": true,
  "checkedCount": 42,
  "tipHash": "abcd567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "breakAtSeq": null,
  "breakReason": null,
  "truncated": false
}
// note: Verify the custody chain.
```

##### `audit.tops.list`

- **Summary**: List Tops feed entries (hash-chained + Ed25519-signed + OTS Bitcoin-anchored).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view_audit_log`
- **Audit kind**: `agent_read`
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/audit.tops.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "entries": [],
  "nextCursor": null
}
// note: Read Tops feed.
```

##### `audit.tops.verify`

- **Summary**: Verify the hash chain + signatures + OTS proof of a range of Tops entries.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view_audit_log`
- **Audit kind**: `agent_read`
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/audit.tops.verify`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "fromEntryId": "tops_AAAA00000000000000000000",
  "toEntryId": "tops_ZZZZ00000000000000000000"
}
// → output
{
  "chainValid": true,
  "signaturesValid": true,
  "otsValid": true,
  "errors": []
}
// note: Verify a Tops range end-to-end.
```

##### `audit.tops.continuity`

- **Summary**: Check whether a Tops chain is committed through the period — the gap a passing hash walk cannot show.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view_audit_log`
- **Audit kind**: `agent_read`
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/audit.tops.continuity`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "standing": "nothing_sealed",
  "entryCount": 3,
  "sealedCount": 0,
  "unsealedCount": 3,
  "attestedAnchorCount": 0,
  "periodEnd": "2026-09-04T00:00:00.000Z",
  "tail": null,
  "head": null,
  "continuous": false,
  "missingEntries": 0,
  "supportedClaim": "All 3 entr(ies) link correctly and NONE is covered by a seal.",
  "notes": []
}
// note: The same chain audit.tops.verify reports as valid.
```

##### `audit.shadow-sessions.list`

- **Summary**: List Trustvice-staff shadow-mode sessions on a workspace.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view_audit_log`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/audit.shadow-sessions.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "sessions": [],
  "nextCursor": null
}
// note: List Trustvice-staff shadow sessions.
```

##### `audit.shadow-sessions.get`

- **Summary**: Get full details + action feed of a shadow-mode session.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view_audit_log`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/audit.shadow-sessions.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "sessionId": "shadow_abc"
}
// → output
{
  "session": {},
  "actions": []
}
// note: Inspect a shadow session.
```

##### `audit.aggregate`

- **Summary**: Group + count audit entries by a dimension (kind, transport, outcome, agentClientId).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view_audit_log`
- **Audit kind**: `agent_read`
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/audit.aggregate`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "by": "transport"
}
// → output
{
  "buckets": [
    {
      "key": "rest",
      "count": 1234
    },
    {
      "key": "mcp",
      "count": 567
    }
  ]
}
// note: Group by transport.
```

##### `audit.kinds.list`

- **Summary**: List all audit-kind discriminator values supported by the platform.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/audit.kinds.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "kinds": [
    {
      "id": "workspace.created",
      "category": "workspace",
      "description": "A new workspace was created."
    }
  ]
}
// note: Discover audit kinds.
```

##### `audit.export.scoped`

- **Summary**: Request a scoped CSV/JSON export of audit entries matching filters. Returns a download URL when ready (signed, time-bounded).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `exports.create`
- **Audit kind**: `export.requested`
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/audit.export.scoped`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "format": "compliance-bundle"
}
// → output
{
  "exportId": "exp_abc",
  "status": "queued"
}
// note: Queue a compliance-bundle export.
```

##### `audit.outside-access.list`

- **Summary**: List entries representing access from outside the workspace's normal principals (admin reads, side-car reads, share-url access).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view_audit_log`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/audit.outside-access.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "entries": [],
  "nextCursor": null
}
// note: See every external touch on this workspace.
```

##### `audit.stream.list`

- **Summary**: List the workspace's SIEM/S3 audit-stream destinations (Splunk HEC / Datadog / webhook / S3), with sealed credentials masked.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/audit.stream.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "destinations": []
}
// note: List audit-stream destinations.
```

##### `audit.stream.configure`

- **Summary**: Create or update a SIEM/S3 audit-stream destination. A provided vendor token / S3 secret / webhook secret is sealed at rest.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `settings.edit_integrations`
- **Audit kind**: `audit.stream.configured`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/audit.stream.configure`

**Example**:

```jsonc
// input
{
  "kind": "splunk_hec",
  "displayName": "SOC Splunk",
  "endpoint": "https://http-inputs.splunkcloud.com",
  "token": "hec-EXAMPLE0000TOKEN0000"
}
// → output
{
  "destination": null
}
// note: Add a Splunk HEC destination.
```

##### `audit.stream.delete`

- **Summary**: Delete an audit-stream destination by id (workspace-scoped).
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `settings.edit_integrations`
- **Audit kind**: `audit.stream.configured`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/audit.stream.delete`

**Example**:

```jsonc
// input
{
  "id": "astr_abc"
}
// → output
{
  "deleted": true
}
// note: Delete a destination.
```

### `tops` (12 actions)

Tops config cascade: org → workspace → actor (leaf wins). Three presets: minimal, recommended, forensic.

##### `tops.config.get`

- **Summary**: Get the Tops config for a specific scope (org, workspace, or actor).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tops.config.get`

**Example**:

```jsonc
// input
{
  "scope": "workspace",
  "scopeId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "scope": "workspace",
  "scopeId": "ws_DEMODEFAULT0000000000",
  "enabled": true,
  "kinds": [
    "run",
    "policy_change"
  ],
  "environments": [
    "production"
  ],
  "samplingPercent": 100,
  "detailLevel": "safe",
  "updatedAt": "2026-05-22T12:00:00.000Z",
  "updatedBy": "acc_DEMO00000000000000000000"
}
// note: Read scope config.
```

##### `tops.config.set`

- **Summary**: Set the Tops config for a scope. Forensic detail level requires explicit acknowledgement.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `settings.view`
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tops.config.set`

**Example**:

```jsonc
// input
{
  "scope": "workspace",
  "scopeId": "ws_DEMODEFAULT0000000000",
  "enabled": true,
  "kinds": [
    "run",
    "policy_change"
  ],
  "environments": [
    "production"
  ],
  "samplingPercent": 100,
  "detailLevel": "extended"
}
// → output
{
  "scope": "workspace",
  "scopeId": "ws_DEMODEFAULT0000000000",
  "enabled": true,
  "kinds": [
    "run",
    "policy_change"
  ],
  "environments": [
    "production"
  ],
  "samplingPercent": 100,
  "detailLevel": "extended",
  "updatedAt": "2026-05-22T12:00:00.000Z",
  "updatedBy": "acc_DEMO00000000000000000000"
}
// note: Set scope config.
```

##### `tops.config.delete`

- **Summary**: Delete a scope-level Tops config (scope reverts to parent inheritance).
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `settings.view`
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tops.config.delete`

**Example**:

```jsonc
// input
{
  "scope": "workspace",
  "scopeId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "deleted": true
}
// note: Delete scope config.
```

##### `tops.config.list`

- **Summary**: List Tops configs (all scopes in an org or workspace).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tops.config.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "configs": [],
  "nextCursor": null
}
// note: List configs.
```

##### `tops.config.cascade.resolve`

- **Summary**: Resolve the effective Tops config at a specific (org, workspace, actor) leaf — applies the leaf-wins cascade.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tops.config.cascade.resolve`

**Example**:

```jsonc
// input
{
  "organizationId": "org_DEMO00000000000000000000",
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "effectiveConfig": {
    "scope": "workspace",
    "scopeId": "ws_DEMODEFAULT0000000000",
    "enabled": true,
    "kinds": [
      "run"
    ],
    "environments": [
      "production"
    ],
    "samplingPercent": 100,
    "detailLevel": "safe",
    "updatedAt": "2026-05-22T12:00:00.000Z",
    "updatedBy": "acc_DEMO00000000000000000000"
  },
  "source": "workspace",
  "inheritedFields": [
    "environments"
  ]
}
// note: Resolve effective config.
```

##### `tops.config.preset.apply`

- **Summary**: Apply one of the 3 presets (Minimal / Recommended / Forensic) to a scope.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `settings.view`
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tops.config.preset.apply`

**Example**:

```jsonc
// input
{
  "scope": "workspace",
  "scopeId": "ws_DEMODEFAULT0000000000",
  "presetId": "recommended"
}
// → output
{
  "scope": "workspace",
  "scopeId": "ws_DEMODEFAULT0000000000",
  "enabled": true,
  "kinds": [
    "run",
    "policy_change",
    "key_event"
  ],
  "environments": [
    "production"
  ],
  "samplingPercent": 100,
  "detailLevel": "safe",
  "updatedAt": "2026-05-22T12:00:00.000Z",
  "updatedBy": "acc_DEMO00000000000000000000"
}
// note: Apply recommended preset.
```

##### `tops.config.presets.list`

- **Summary**: List the 3 supported presets with their config shapes + tradeoff labels.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tops.config.presets.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "presets": [
    {
      "id": "minimal",
      "label": "Minimal",
      "description": "Smallest footprint; just the essentials.",
      "config": {},
      "tradeoff": "May miss forensic detail in incidents."
    }
  ]
}
// note: Discover presets.
```

##### `tops.config.testbed.run`

- **Summary**: Test the cascade resolver against a synthetic actor id to preview what entries it would generate.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tops.config.testbed.run`

**Example**:

```jsonc
// input
{
  "organizationId": "org_DEMO00000000000000000000",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "actorId": "actor_demo00000000000000000000",
  "syntheticEvent": {
    "kind": "run"
  }
}
// → output
{
  "resolved": {
    "scope": "workspace",
    "scopeId": "ws_DEMODEFAULT0000000000",
    "enabled": true,
    "kinds": [
      "run"
    ],
    "environments": [
      "production"
    ],
    "samplingPercent": 100,
    "detailLevel": "safe",
    "updatedAt": "2026-05-22T12:00:00.000Z",
    "updatedBy": "acc_DEMO00000000000000000000"
  },
  "wouldRecord": true,
  "wouldRecordFields": [
    "kind",
    "timestamp"
  ]
}
// note: Test cascade.
```

##### `tops.config.change-history.list`

- **Summary**: List Tops-config change events (audit cross-link).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tops.config.change-history.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "changes": [],
  "nextCursor": null
}
// note: Read config change history.
```

##### `tops.config.sparkline.get`

- **Summary**: Get a 30-day sparkline of Tops detail-level changes (visualizes forensic-cooldown nudge).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tops.config.sparkline.get`

**Example**:

```jsonc
// input
{
  "scope": "workspace",
  "scopeId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "data": []
}
// note: Sparkline data.
```

##### `tops.config.audit-cross-links.get`

- **Summary**: Get deep-links to the workspace audit log filtered by Tops-config-change events.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tops.config.audit-cross-links.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "links": [
    {
      "label": "Recent config changes",
      "href": "/app/audit-log?source=tops"
    }
  ]
}
// note: Audit cross-link helper.
```

##### `tops.config.cooldown-status.get`

- **Summary**: Check if a scope is in the forensic cooldown window (auto-revert nudge).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `settings.view`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tops.config.cooldown-status.get`

**Example**:

```jsonc
// input
{
  "scope": "workspace",
  "scopeId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "inCooldown": false,
  "enteredAt": null,
  "expiresAt": null
}
// note: Read cooldown state.
```

### `referrals` (10 actions)

Codes + redemption + spend ledger + Every.org charity donations.

##### `referrals.code.get`

- **Summary**: Get your active referral code + share URL.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/referrals.code.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "code": "DEMO12",
  "shareUrl": "https://trustvice.com/?ref=DEMO12",
  "qrCodeDataUrl": "data:image/png;base64,..."
}
// note: Read your referral code.
```

##### `referrals.code.regenerate`

- **Summary**: Regenerate referral code. Old code stops working.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/referrals.code.regenerate`

**Example**:

```jsonc
// input
{}
// → output
{
  "code": "NEWCODE99"
}
// note: Get a fresh referral code.
```

##### `referrals.list-sent`

- **Summary**: List referrals you have sent.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/referrals.list-sent`

**Example**:

```jsonc
// input
{}
// → output
{
  "referrals": [],
  "nextCursor": null
}
// note: List sent referrals.
```

##### `referrals.list-received`

- **Summary**: List referrals where you were the referee.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/referrals.list-received`

**Example**:

```jsonc
// input
{}
// → output
{
  "referrals": [],
  "nextCursor": null
}
// note: List received referrals.
```

##### `referrals.balance.get`

- **Summary**: Get your current point balance + lifetime multiplier tier.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/referrals.balance.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "pointBalance": 1500,
  "lifetimeMultiplier": 1.2,
  "nextMultiplierAt": 2500
}
// note: Read point balance.
```

##### `referrals.funnel.get`

- **Summary**: Get conversion funnel analytics (sent → clicked → joined → redeemed).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/referrals.funnel.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "sent": 50,
  "clicked": 30,
  "joined": 12,
  "redeemed": 8
}
// note: Read funnel.
```

##### `referrals.redeem`

- **Summary**: Redeem a referral or voucher code.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/referrals.redeem`

**Example**:

```jsonc
// input
{
  "code": "DEMO12"
}
// → output
{
  "redeemed": true,
  "rewardKind": "points",
  "rewardValue": 1000
}
// note: Redeem a code.
```

##### `referrals.spend`

- **Summary**: Spend points on a reward (run pack, add-on credit, Every.org charity, etc.).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/referrals.spend`

**Example**:

```jsonc
// input
{
  "product": "every-org-charity",
  "pointAmount": 200,
  "metadata": {
    "charityId": "every:childrens-hospital"
  }
}
// → output
{
  "spentAt": "2026-05-22T12:00:00.000Z",
  "transactionId": "tx_abc",
  "remainingBalance": 1300
}
// note: Donate to charity.
```

##### `referrals.spend-products.list`

- **Summary**: List the products you can redeem points against.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/referrals.spend-products.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "products": [
    {
      "id": "every-org-charity",
      "label": "Charity donation via Every.org",
      "pointCost": 1,
      "description": "Donate to any Every.org charity at the cents-per-point rate."
    }
  ]
}
// note: Discover spend products.
```

##### `referrals.ledger.list`

- **Summary**: List point transactions (earned + spent).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/referrals.ledger.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "transactions": [],
  "nextCursor": null
}
// note: Read point ledger.
```

### `number_one` (12 actions)

Number One AI chat in three modes: Calculator (math + cost projections), Analyst (semantic queries over audit + custody), Admin (mutating actions; step-up auth required).

##### `number_one.conversation.create`

- **Summary**: Start a new Number One conversation.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/number_one.conversation.create`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "mode": "analyst",
  "title": "Q3 audit review"
}
// → output
{
  "conversationId": "conv_demo00000000000000000000",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "mode": "analyst",
  "title": "Q3 audit review",
  "startedAt": "2026-05-22T12:00:00.000Z",
  "lastActivityAt": "2026-05-22T12:00:00.000Z",
  "messageCount": 0,
  "factsLearnedCount": 0
}
// note: Start a new conversation.
```

##### `number_one.conversation.list`

- **Summary**: List your conversations (most recent first).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/number_one.conversation.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "conversations": [],
  "nextCursor": null
}
// note: List conversations.
```

##### `number_one.conversation.get`

- **Summary**: Get a conversation's metadata + recent messages.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/number_one.conversation.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "conversationId": "conv_demo00000000000000000000"
}
// → output
{
  "conversation": {
    "conversationId": "conv_demo00000000000000000000",
    "workspaceId": "ws_DEMODEFAULT0000000000",
    "mode": "analyst",
    "startedAt": "2026-05-22T12:00:00.000Z",
    "lastActivityAt": "2026-05-22T12:00:00.000Z",
    "messageCount": 0,
    "factsLearnedCount": 0
  },
  "messages": []
}
// note: Read a conversation.
```

##### `number_one.conversation.delete`

- **Summary**: Delete a conversation. Memory facts attached to it survive but lose conversation context.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/number_one.conversation.delete`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "conversationId": "conv_demo00000000000000000000"
}
// → output
{
  "deleted": true
}
// note: Delete a conversation.
```

##### `number_one.message.send`

- **Summary**: Send a user message in a Number One conversation. Response streams back via SSE.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/number_one.message.send`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "conversationId": "conv_demo00000000000000000000",
  "body": "What was my Trustvice Receipts usage last week?"
}
// → output
{
  "assistantMessageId": "msg_demo00000000000000000000",
  "intent": "read",
  "confirmationRequired": false
}
// note: Send a message.
```

##### `number_one.message.list`

- **Summary**: List messages in a conversation.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/number_one.message.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "conversationId": "conv_demo00000000000000000000"
}
// → output
{
  "messages": [],
  "nextCursor": null
}
// note: List messages.
```

##### `number_one.mode.set`

- **Summary**: Switch a conversation's mode (Calculator / Analyst / Admin).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/number_one.mode.set`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "conversationId": "conv_demo00000000000000000000",
  "mode": "admin"
}
// → output
{
  "conversationId": "conv_demo00000000000000000000",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "mode": "admin",
  "startedAt": "2026-05-22T12:00:00.000Z",
  "lastActivityAt": "2026-05-22T12:00:00.000Z",
  "messageCount": 5,
  "factsLearnedCount": 2
}
// note: Switch to Admin mode (requires step-up auth).
```

##### `number_one.memory.list`

- **Summary**: List memory facts pinned in a workspace.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/number_one.memory.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "facts": [],
  "nextCursor": null
}
// note: List memory facts.
```

##### `number_one.memory.pin`

- **Summary**: Pin a memory fact so Number One reliably recalls it across conversations.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/number_one.memory.pin`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "factId": "fact_demo00000000000000000000"
}
// → output
{
  "factId": "fact_demo00000000000000000000",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "text": "Q3 audit is led by Foo & Co LLP",
  "pinned": true,
  "learnedFrom": "msg_abc",
  "learnedAt": "2026-05-22T12:00:00.000Z",
  "reinforcedAt": null
}
// note: Pin a fact.
```

##### `number_one.memory.unpin`

- **Summary**: Unpin a memory fact.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/number_one.memory.unpin`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "factId": "fact_demo00000000000000000000"
}
// → output
{
  "factId": "fact_demo00000000000000000000",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "text": "Q3 audit is led by Foo & Co LLP",
  "pinned": false,
  "learnedFrom": "msg_abc",
  "learnedAt": "2026-05-22T12:00:00.000Z",
  "reinforcedAt": null
}
// note: Unpin.
```

##### `number_one.memory.erase`

- **Summary**: Permanently erase a memory fact (cannot be recovered).
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/number_one.memory.erase`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "factId": "fact_demo00000000000000000000"
}
// → output
{
  "erased": true
}
// note: Erase a fact.
```

##### `number_one.memory.cap.get`

- **Summary**: Get the memory cap for the workspace's tier (or unlimited if Infinite Memory add-on is active).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/number_one.memory.cap.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "capFacts": 100,
  "usedFacts": 23,
  "infiniteMemoryActive": false
}
// note: Read memory cap.
```

### `entpoind` (29 actions)

8 cryptographic-receipt primitives: agent.call, content.attest, llm.attest, commit.attest, webhook.deliver, monitor.http, dns.watch, tls.watch.

##### `entpoind.monitor.http.add`

- **Summary**: Register a new HTTP monitor (1-minute minimum interval).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `entpoind.monitor.create`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.monitor.http.add`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "url": "https://api.example.com/health",
  "intervalSeconds": 60
}
// → output
{
  "monitorId": "01J9X4P9R7Z2C1A1F2A8VBJYM1",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "url": "https://api.example.com/health",
  "method": "GET",
  "intervalSeconds": 60,
  "expectedStatusCodes": [
    200
  ],
  "enabled": true,
  "createdAt": "2026-05-22T12:00:00.000Z",
  "lastCheckAt": null
}
// note: Register HTTP monitor.
```

##### `entpoind.monitor.http.list`

- **Summary**: List HTTP monitors in a workspace.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `entpoind.monitor.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.monitor.http.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "monitors": [],
  "nextCursor": null
}
// note: List monitors.
```

##### `entpoind.monitor.http.run-now`

- **Summary**: Run a monitor check immediately (bypasses the scheduled interval).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `entpoind.monitor.create`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.monitor.http.run-now`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "monitorId": "01J9X4P9R7Z2C1A1F2A8VBJYM1"
}
// → output
{
  "statusCode": 200,
  "latencyMs": 87,
  "receiptId": "01H8X4P9R7Z2C1A1F2A8VBJYV7"
}
// note: Run a monitor check now.
```

##### `entpoind.monitor.http.remove`

- **Summary**: Delete an HTTP monitor.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `entpoind.monitor.delete`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.monitor.http.remove`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "monitorId": "01J9X4P9R7Z2C1A1F2A8VBJYM1"
}
// → output
{
  "deleted": true
}
// note: Delete monitor.
```

##### `entpoind.watch.dns.add`

- **Summary**: Register a DNS watch (detects record drift; signs every check as a receipt).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `entpoind.watch.create`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.watch.dns.add`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "domain": "example.com",
  "recordType": "A"
}
// → output
{
  "dnsWatchId": "01J9X4P9R7Z2C1A1F2A8VBJYD1",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "domain": "example.com",
  "recordType": "A",
  "intervalSeconds": 3600,
  "enabled": true
}
// note: Register DNS watch.
```

##### `entpoind.watch.dns.list`

- **Summary**: List DNS watches in a workspace.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `entpoind.watch.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.watch.dns.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "watches": [],
  "nextCursor": null
}
// note: List DNS watches.
```

##### `entpoind.watch.dns.remove`

- **Summary**: Delete a DNS watch.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `entpoind.watch.delete`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.watch.dns.remove`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "dnsWatchId": "01J9X4P9R7Z2C1A1F2A8VBJYD1"
}
// → output
{
  "deleted": true
}
// note: Delete DNS watch.
```

##### `entpoind.watch.tls.add`

- **Summary**: Register a TLS certificate watch (detects cert changes; signs every check).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `entpoind.watch.create`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.watch.tls.add`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "host": "example.com"
}
// → output
{
  "tlsWatchId": "01J9X4P9R7Z2C1A1F2A8VBJYT1",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "host": "example.com",
  "port": 443,
  "intervalSeconds": 3600,
  "enabled": true
}
// note: Register TLS watch.
```

##### `entpoind.watch.tls.list`

- **Summary**: List TLS watches in a workspace.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `entpoind.watch.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.watch.tls.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "watches": [],
  "nextCursor": null
}
// note: List TLS watches.
```

##### `entpoind.watch.tls.remove`

- **Summary**: Delete a TLS watch.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `entpoind.watch.delete`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.watch.tls.remove`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "tlsWatchId": "01J9X4P9R7Z2C1A1F2A8VBJYT1"
}
// → output
{
  "deleted": true
}
// note: Delete TLS watch.
```

##### `entpoind.receipt.list`

- **Summary**: List Trustvice receipts for a workspace.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `entpoind.receipt.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.receipt.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "kind": "agent.call"
}
// → output
{
  "receipts": [],
  "nextCursor": null
}
// note: List receipts.
```

##### `entpoind.receipt.get`

- **Summary**: Get a single receipt with full body.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `entpoind.receipt.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.receipt.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "receiptId": "01H8X4P9R7Z2C1A1F2A8VBJYV2"
}
// → output
{
  "receiptId": "01H8X4P9R7Z2C1A1F2A8VBJYV2",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "kind": "agent.call",
  "issuedAt": "2026-05-22T12:00:00.000Z",
  "signature": "...",
  "signatureKeyId": "entpoind-2026-q2-enam",
  "body": {}
}
// note: Read a receipt.
```

##### `entpoind.receipt.verify`

- **Summary**: Verify a receipt's Ed25519 signature against the published public key. Cannot be disabled.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.receipt.verify`

**Example**:

```jsonc
// input
{
  "receipt": {
    "receiptId": "01H8X4P9R7Z2C1A1F2A8VBJYV2",
    "workspaceId": "ws_DEMODEFAULT0000000000",
    "kind": "agent.call",
    "issuedAt": "2026-05-22T12:00:00.000Z",
    "signature": "...",
    "signatureKeyId": "entpoind-2026-q2-enam",
    "body": {}
  }
}
// → output
{
  "ok": true,
  "signedAt": "2026-05-22T12:00:00.000Z",
  "signatureKeyId": "thLmyHDzi6rkbTb0KkPzmA"
}
// note: Verify a receipt.
```

##### `entpoind.usage.current`

- **Summary**: Get current-period Trustvice Receipts usage for a workspace (calls per primitive + budget consumed).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `entpoind.usage.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.usage.current`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "totalCalls": 12345,
  "perPrimitive": {
    "agent.call": 10000,
    "content.attest": 2345
  },
  "monthlyAllowance": 100000,
  "periodEnd": "2026-06-01T00:00:00.000Z"
}
// note: Read current usage.
```

##### `entpoind.usage.historical`

- **Summary**: Get historical Trustvice Receipts usage (per-day breakdown for a date range).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `entpoind.usage.view`
- **Audit kind**: `agent_read`
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.usage.historical`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "since": "2026-05-01T00:00:00.000Z"
}
// → output
{
  "daily": []
}
// note: Read historical usage.
```

##### `entpoind.subscription.get`

- **Summary**: Get workspace Trustvice Receipts subscription state.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `entpoind.subscription.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.subscription.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "enabled": true,
  "tier": "team",
  "abuseStatus": "clean",
  "autoOverageEnabled": true,
  "billingMode": "combined"
}
// note: Read subscription state.
```

##### `entpoind.subscription.cancel`

- **Summary**: Cancel the Trustvice Receipts subscription at the next billing period. Workspace's existing receipts remain accessible.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `billing.change_plan`
- **Audit kind**: `plan.changed`
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.subscription.cancel`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "reason": "Migrating to alternative receipt provider"
}
// → output
{
  "canceled": true,
  "effectiveAt": "2026-06-22T00:00:00.000Z"
}
// note: Cancel Entpoind subscription.
```

##### `entpoind.abuse-status.get`

- **Summary**: Get the current Trustvice Receipts abuse status for a workspace.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `entpoind.abuse.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.abuse-status.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "status": "clean",
  "flaggedAt": null,
  "suspendedAt": null,
  "reason": null,
  "latestAppeal": null
}
// note: Read abuse status.
```

##### `entpoind.abuse-status.appeal`

- **Summary**: Submit an appeal against an abuse-status flag or suspension.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `entpoind.abuse.appeal`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.abuse-status.appeal`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "appealText": "Our agent's traffic spike was a planned load test; here are the details + timestamps + IP CIDRs ..."
}
// → output
{
  "appealId": "app_abc",
  "submittedAt": "2026-05-22T12:00:00.000Z"
}
// note: Submit abuse appeal.
```

##### `entpoind.abuse-status.appeal.list`

- **Summary**: List this workspace's abuse appeals and their decisions.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `entpoind.abuse.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.abuse-status.appeal.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "appeals": [
    {
      "appealId": "app_abc",
      "appealText": "Our agent's traffic spike was a planned load test ...",
      "submittedAt": "2026-05-22T12:00:00.000Z",
      "status": "pending"
    }
  ]
}
// note: Read this workspace's appeals.
```

##### `entpoind.signing-key.get`

- **Summary**: Get the current active Trustvice Receipts signing key id for the workspace's jurisdiction.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `entpoind.subscription.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.signing-key.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "signingKeyId": "entpoind-2026-q2-enam",
  "jurisdiction": "ENAM",
  "issuedAt": "2026-04-01T00:00:00.000Z",
  "expiresAt": "2027-04-01T00:00:00.000Z",
  "publishedAtUrl": "https://api.trustvice.com/.well-known/entpoind-keys.json"
}
// note: Read signing key id.
```

##### `entpoind.signing-key.list`

- **Summary**: List all signing keys (active + historical) usable to verify the workspace's receipts.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `entpoind.subscription.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.signing-key.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "keys": [
    {
      "signingKeyId": "entpoind-2026-q2-enam",
      "jurisdiction": "ENAM",
      "issuedAt": "2026-04-01T00:00:00.000Z",
      "expiresAt": "2027-04-01T00:00:00.000Z",
      "active": true
    }
  ]
}
// note: List signing keys.
```

##### `entpoind.signing-key.rotate-request.list`

- **Summary**: List this workspace's signing-key rotation requests and their outcomes.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `entpoind.subscription.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.signing-key.rotate-request.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "requests": [
    {
      "requestId": "rot_abc",
      "reason": "Q4 scheduled rotation per our internal policy",
      "status": "requested",
      "requestedAt": "2026-05-18T00:00:00.000Z",
      "estimatedRotationAt": "2026-06-01T00:00:00.000Z",
      "fulfilledAt": null
    }
  ]
}
// note: Read this workspace's rotation requests.
```

##### `entpoind.signing-key.public.get`

- **Summary**: Get the public-key JWK for a specific signing key id (for offline verification).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.signing-key.public.get`

**Example**:

```jsonc
// input
{
  "signingKeyId": "entpoind-2026-q2-enam"
}
// → output
{
  "jwk": {
    "kty": "OKP",
    "crv": "Ed25519",
    "x": "..."
  },
  "issuedAt": "2026-04-01T00:00:00.000Z",
  "expiresAt": "2027-04-01T00:00:00.000Z"
}
// note: Read public key JWK.
```

##### `entpoind.status.get`

- **Summary**: Get the Trustvice Receipts subsystem health (per-jurisdiction Worker uptime, per-primitive error rate, last self-attestation receipt).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `entpoind.subscription.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.status.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "jurisdictions": [
    {
      "id": "ENAM",
      "uptimePercent": 99.95,
      "errorRatePercent": 0.02,
      "lastSelfAttestationAt": "2026-05-22T11:00:00.000Z"
    }
  ]
}
// note: Read Entpoind health.
```

##### `entpoind.attestation-feed.get`

- **Summary**: Get the daily Trustvice Receipts self-attestation receipt feed (Trustvice attesting to its own platform integrity).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.attestation-feed.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "attestations": []
}
// note: Read self-attestation feed.
```

##### `entpoind.compliance.regimes.list`

- **Summary**: List every compliance regime the registry models, with what is in force today and what is not yet.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.compliance.regimes.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "asOf": "2026-08-11",
  "regimes": [],
  "obligationKinds": [],
  "evidencePrimitives": []
}
// note: Read the regime catalogue.
```

##### `entpoind.compliance.obligations.get`

- **Summary**: Given a declared position, return the merged duty list across every governing regime — strictest timing wins, and regimes that wanted it looser are recorded.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.compliance.obligations.get`

**Example**:

```jsonc
// input
{
  "operatorRegisteredIn": [
    "eu-ai-act"
  ],
  "audienceRegions": [
    "eu"
  ]
}
// → output
{
  "selection": {
    "regimes": [
      "eu-ai-act"
    ],
    "asOf": null,
    "notYetInForce": [],
    "expired": [],
    "inForceNotYetEnforced": [],
    "basis": "",
    "unsettled": [],
    "dutyFallsOnCustomerOnly": true
  },
  "obligations": [],
  "requiresFirstPartyDelivery": false,
  "advisory": true
}
// note: Ask what an EU-facing operator owes.
```

##### `entpoind.compliance.posture.get`

- **Summary**: Conformity Live: which clauses the workspace's own signed receipts actually discharge, each with the receipt ids behind it.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/entpoind.compliance.posture.get`

**Example**:

```jsonc
// input
{
  "operatorRegisteredIn": [
    "eu-ai-act"
  ],
  "audienceRegions": [
    "eu"
  ]
}
// → output
{
  "evaluatedAt": "2026-09-04T00:00:00.000Z",
  "regimes": [
    "eu-ai-act"
  ],
  "selectionBasis": "",
  "clauses": [],
  "tally": {},
  "coverage": null,
  "evidenceComplete": true,
  "receiptsRead": 0,
  "complianceReceiptsUsed": 0,
  "notes": [],
  "advisory": "Advisory."
}
// note: Ask what the workspace's receipts actually discharge.
```

### `privacy` (8 actions)

GDPR/CCPA DSR submission, status, receipts. Always-on — disabling forbidden by ACTIONS_EXCLUDED_FROM_DISABLE.

##### `privacy.dsr.submit`

- **Summary**: Submit a data-subject request (GDPR / CCPA). Cannot be disabled — statutory right.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/privacy.dsr.submit`

**Example**:

```jsonc
// input
{
  "kind": "access",
  "subjectEmail": "alice@example.com"
}
// → output
{
  "dsrId": "dsr_abc",
  "kind": "access",
  "subjectEmail": "alice@example.com",
  "submittedAt": "2026-05-22T12:00:00.000Z",
  "status": "received",
  "completedAt": null
}
// note: File an Art. 15 access request.
```

##### `privacy.dsr.status`

- **Summary**: Check status of a submitted DSR. Cannot be disabled — statutory right.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/privacy.dsr.status`

**Example**:

```jsonc
// input
{
  "dsrId": "dsr_abc"
}
// → output
{
  "dsrId": "dsr_abc",
  "kind": "access",
  "subjectEmail": "alice@example.com",
  "submittedAt": "2026-05-22T12:00:00.000Z",
  "status": "in-progress",
  "completedAt": null
}
// note: Status check.
```

##### `privacy.dsr.list`

- **Summary**: List all DSRs filed for this account / workspace.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/privacy.dsr.list`

**Example**:

```jsonc
// input
{
  "limit": 25
}
// → output
{
  "dsrs": [],
  "nextCursor": null
}
// note: List your filed DSRs.
```

##### `privacy.export.request`

- **Summary**: Request a personal-data export (GDPR Art. 20 — data portability). Cannot be disabled.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `export.requested`
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/privacy.export.request`

**Example**:

```jsonc
// input
{
  "format": "portable-archive"
}
// → output
{
  "exportId": "exp_pii_abc",
  "estimatedReadyAt": "2026-05-22T13:00:00.000Z",
  "format": "portable-archive"
}
// note: Art. 20 portability export.
```

##### `privacy.export.download`

- **Summary**: Get a signed download URL for a completed personal-data export.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `export.completed`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/privacy.export.download`

**Example**:

```jsonc
// input
{
  "exportId": "exp_pii_abc"
}
// → output
{
  "url": "https://r2.trustvice.com/exports/abc",
  "expiresAt": "2026-05-22T13:30:00.000Z",
  "sha256": "abcd..."
}
// note: Download your export.
```

##### `privacy.receipt.get`

- **Summary**: Get the Ed25519-signed completion receipt for a DSR (verifiable offline).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/privacy.receipt.get`

**Example**:

```jsonc
// input
{
  "dsrId": "dsr_abc"
}
// → output
{
  "receipt": {},
  "signingKeyId": "privacy-2026-q2-enam",
  "publicKeyUrl": "https://api.trustvice.com/.well-known/privacy-receipt-keys.json"
}
// note: Receipt for offline verification.
```

##### `privacy.receipt.verify`

- **Summary**: Verify a DSR receipt's Ed25519 signature + OTS proof against published public keys.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/privacy.receipt.verify`

**Example**:

```jsonc
// input
{
  "receipt": {}
}
// → output
{
  "valid": true,
  "signatureValid": true,
  "otsValid": true,
  "errors": []
}
// note: Verify offline-style.
```

##### `privacy.subject-rights.list`

- **Summary**: List the data-subject rights Trustvice honours (GDPR, CCPA, LGPD) + the legal references.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/privacy.subject-rights.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "rights": [
    {
      "kind": "access",
      "legalRef": "GDPR Art. 15",
      "description": "Right to access your personal data."
    }
  ]
}
// note: Read supported rights.
```

### `support` (6 actions)

Tickets + replies + satisfaction surveys.

##### `support.tickets.list`

- **Summary**: List your support tickets.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/support.tickets.list`

**Example**:

```jsonc
// input
{
  "limit": 25
}
// → output
{
  "tickets": [],
  "nextCursor": null
}
// note: List your tickets.
```

##### `support.tickets.create`

- **Summary**: Open a new support ticket.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/support.tickets.create`

**Example**:

```jsonc
// input
{
  "subject": "Issue with Trustvice receipt verification",
  "body": "Hi — I'm seeing a signature_invalid error when verifying receipts from workspace ws_X. Could you take a look?",
  "priority": "normal"
}
// → output
{
  "ticketId": "tkt_abc",
  "subject": "Issue with Trustvice receipt verification",
  "status": "open",
  "priority": "normal",
  "createdAt": "2026-05-22T12:00:00.000Z",
  "updatedAt": "2026-05-22T12:00:00.000Z",
  "resolvedAt": null
}
// note: Open a new ticket.
```

##### `support.tickets.get`

- **Summary**: Get a ticket's details + reply thread.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/support.tickets.get`

**Example**:

```jsonc
// input
{
  "ticketId": "tkt_abc"
}
// → output
{
  "ticket": {
    "ticketId": "tkt_abc",
    "subject": "Issue",
    "status": "open",
    "priority": "normal",
    "createdAt": "2026-05-22T12:00:00.000Z",
    "updatedAt": "2026-05-22T12:00:00.000Z",
    "resolvedAt": null
  },
  "replies": []
}
// note: Read ticket + thread.
```

##### `support.tickets.reply`

- **Summary**: Post a reply to a ticket.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/support.tickets.reply`

**Example**:

```jsonc
// input
{
  "ticketId": "tkt_abc",
  "body": "Thanks — here's the receipt hash from the failing verify call."
}
// → output
{
  "replyId": "rep_abc",
  "ticketId": "tkt_abc",
  "author": "customer",
  "body": "Thanks — here's the receipt hash from the failing verify call.",
  "createdAt": "2026-05-22T12:05:00.000Z"
}
// note: Reply to a ticket.
```

##### `support.tickets.close`

- **Summary**: Close a ticket (optionally with a reason).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/support.tickets.close`

**Example**:

```jsonc
// input
{
  "ticketId": "tkt_abc"
}
// → output
{
  "ticketId": "tkt_abc",
  "subject": "Issue",
  "status": "closed",
  "priority": "normal",
  "createdAt": "2026-05-22T12:00:00.000Z",
  "updatedAt": "2026-05-22T12:10:00.000Z",
  "resolvedAt": "2026-05-22T12:10:00.000Z"
}
// note: Close a ticket.
```

##### `support.satisfaction.rate`

- **Summary**: Rate the support experience after a ticket closes.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/support.satisfaction.rate`

**Example**:

```jsonc
// input
{
  "ticketId": "tkt_abc",
  "speed": 5,
  "knowledge": 5,
  "friendliness": 5,
  "followThrough": 5,
  "outcome": 5
}
// → output
{
  "recorded": true,
  "rebuildTriggered": false
}
// note: Rate all five dimensions 5/5. Any dimension <= 2 sets rebuildTriggered.
```

### `discovery` (7 actions)

Capabilities + version + schema + plan list. Always-on; no auth required for some sub-actions.

##### `discovery.capabilities.get`

- **Summary**: Get the full action registry catalogue (machine-readable). Same content as `/v1/actions.json`.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/discovery.capabilities.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "actions": [],
  "generatedAt": "2026-05-22T12:00:00.000Z"
}
// note: Discover all actions.
```

##### `discovery.version.get`

- **Summary**: Get the platform version + contracts package version + supported MCP / OpenAPI spec versions.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/discovery.version.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "platform": "trustvice/1.0.0",
  "contracts": "0.1.23",
  "mcpSpecVersion": "2025-06-18",
  "openapiVersion": "3.1.0",
  "asyncapiVersion": "3.0.0"
}
// note: Read all version + spec info.
```

##### `discovery.schema.get`

- **Summary**: Get the JSON Schema for a specific action's input or output.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/discovery.schema.get`

**Example**:

```jsonc
// input
{
  "actionId": "workspace.create",
  "shape": "input"
}
// → output
{
  "schema": {}
}
// note: Get an action's JSON Schema.
```

##### `discovery.locales.list`

- **Summary**: List supported user-facing locales.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/discovery.locales.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "locales": [
    {
      "id": "en",
      "name": "English",
      "nativeName": "English"
    },
    {
      "id": "de",
      "name": "German",
      "nativeName": "Deutsch"
    }
  ]
}
// note: Six supported locales.
```

##### `discovery.plans.list`

- **Summary**: List the Trustvice 360 subscription plans.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/discovery.plans.list`

**Example**:

```jsonc
// input
{
  "product": "all"
}
// → output
{
  "plans": [
    {
      "id": "free",
      "product": "trustvice",
      "name": "Free",
      "priceUsdMinor": 0,
      "features": [
        "1 workspace",
        "1k runs/mo"
      ]
    }
  ]
}
// note: List all plans.
```

##### `discovery.regions.list`

- **Summary**: List the data-residency regions a workspace can be bound to: the seven base regions and the extended AWS locations.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/discovery.regions.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "regions": [
    {
      "id": "cloudflare-d1:weur-1",
      "provider": "cloudflare-d1",
      "label": "Europe Central",
      "countryCode": "EU",
      "euJurisdictionBound": true
    }
  ]
}
// note: List all 33 regions (7 Cloudflare + 26 AWS Aurora).
```

##### `discovery.confirmation.token.verify`

- **Summary**: Verify a confirmation token is well-formed + still valid (cannot be disabled — safety floor).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/discovery.confirmation.token.verify`

**Example**:

```jsonc
// input
{
  "token": "..."
}
// → output
{
  "valid": true,
  "actionId": "workspace.delete.schedule",
  "expiresAt": "2026-05-22T12:01:00.000Z"
}
// note: Verify confirmation token.
```

### `agents` (20 actions)

Agent identity foundation — W3C DID Web Method enrollment/rotation/revocation, A2A delegation, AP2 Verifiable Credential mandates (W3C VC Data Model 2.0 + SD-JWT VC), SPIFFE workload-identity binding + SVID attestation, partner DID federation roots.

##### `agents.delegations.list`

- **Summary**: List the A2A delegations this workspace has issued — the edges of the delegation graph (who delegated what to whom).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/agents.delegations.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "delegations": []
}
// note: Read the delegation edges — the input kill-chain and Muster both need.
```

##### `agents.identity.enroll`

- **Summary**: Enroll a new W3C DID Web agent identity under your principal.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `workspaces.view`
- **Audit kind**: `agent.identity.enrolled`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/agents.identity.enroll`

**Example**:

```jsonc
// input
{
  "displayName": "GitHub Actions release attestor",
  "scopeKind": "workspace",
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "did": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000:github-actions-release-attestor",
  "documentUrl": "https://api.trustvice.com/.well-known/agents/ws_DEMODEFAULT0000000000/github-actions-release-attestor/did.json",
  "enrollmentCredential": "eyJhbGciOiJFZERTQSJ9…",
  "privateKeyRecoveryEnvelope": "v1:AES-256-GCM:…",
  "createdAt": "2026-05-22T12:00:00.000Z"
}
// note: Enroll a workspace-scoped agent DID for CI signing.
```

##### `agents.identity.list`

- **Summary**: List enrolled agent DIDs visible to the principal.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `workspaces.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/agents.identity.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "agents": [],
  "nextCursor": null
}
// note: List workspace-scoped agents.
```

##### `agents.identity.get`

- **Summary**: Get one enrolled agent DID with full document + rotation history.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `workspaces.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/agents.identity.get`

**Example**:

```jsonc
// input
{
  "did": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc"
}
// → output
{
  "record": {
    "did": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc",
    "displayName": "GitHub Actions release attestor",
    "description": null,
    "scopeKind": "workspace",
    "workspaceId": "ws_DEMODEFAULT0000000000",
    "organizationId": null,
    "alg": "EdDSA",
    "activeMethodId": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc#key-1",
    "enrolledAt": "2026-05-22T12:00:00.000Z",
    "deactivatedAt": null,
    "lastSeenAt": null,
    "rotationsCount": 0,
    "lastTrustBundleSignedAt": null
  },
  "document": {},
  "rotationHistory": []
}
// note: Read one agent DID.
```

##### `agents.identity.rotate`

- **Summary**: Rotate the signing key for an agent DID. Old key kept active for a cooldown period.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `workspaces.view`
- **Audit kind**: `agent.identity.rotated`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/agents.identity.rotate`

**Example**:

```jsonc
// input
{
  "did": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc",
  "reason": "scheduled"
}
// → output
{
  "did": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc",
  "newMethodId": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc#key-2",
  "oldMethodRetiresAt": "2026-05-22T13:00:00.000Z",
  "privateKeyRecoveryEnvelope": "v1:AES-256-GCM:…"
}
// note: Quarterly key rotation.
```

##### `agents.identity.revoke`

- **Summary**: Permanently revoke an agent DID. Cannot be undone; the DID id cannot be re-enrolled.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `workspaces.view`
- **Audit kind**: `agent.identity.revoked`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/agents.identity.revoke`

**Example**:

```jsonc
// input
{
  "did": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc",
  "reason": "compromise",
  "irreversibleAcknowledged": true
}
// → output
{
  "did": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc",
  "deactivatedAt": "2026-05-22T12:00:00.000Z",
  "auditEntryId": "aud_DEMO00000000000000000000"
}
// note: Compromise-recovery revoke.
```

##### `agents.identity.did.resolve`

- **Summary**: Resolve any DID (did:web, did:key, did:peer) and return the resolution result envelope.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/agents.identity.did.resolve`

**Example**:

```jsonc
// input
{
  "did": "did:web:trustvice.com:agents:mandate-issuer"
}
// → output
{
  "didDocument": {
    "id": "did:web:trustvice.com:agents:mandate-issuer"
  },
  "didResolutionMetadata": {
    "resolutionSource": "live",
    "resolvedAt": "2026-05-22T12:00:00.000Z"
  },
  "didDocumentMetadata": {}
}
// note: Resolve a DID to its document.
```

##### `agents.passport.verify`

- **Summary**: Verify an Agent Passport presented at an org boundary — offline checks, plus what offline cannot establish.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/agents.passport.verify`

**Example**:

```jsonc
// input
{
  "passport": {
    "agentDid": "did:web:other-org.example:agents:a1",
    "issuerDid": "did:web:other-org.example",
    "mandates": [],
    "issuedAt": "2026-09-03T00:00:00.000Z"
  }
}
// → output
{
  "verification": {
    "agentDid": "did:web:other-org.example:agents:a1",
    "verdict": "failed",
    "checks": [],
    "stalenessSeconds": 86400,
    "assertedCeiling": null,
    "issuerAsserted": [],
    "cannotEstablish": [],
    "notes": []
  },
  "signature": {
    "verified": false,
    "keySource": "none",
    "keyConflict": false,
    "detail": "No verifying key."
  },
  "registry": null,
  "notes": []
}
// note: With no key, the signature is unchecked — and an unchecked signature never reads as a passed one.
```

##### `agents.handshake.notarize`

- **Summary**: Run the A2A attestation ceremony: verify both parties' identity, mandate and SPIFFE, then scope-match the capabilities.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/agents.handshake.notarize`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "handshakeRef": "hs_DEMO0000",
  "initiator": {
    "did": "did:web:example.com:agents:ws:a"
  },
  "responder": {
    "did": "did:web:other.example:agents:b"
  },
  "requestedCapabilities": [
    "billing.invoice.list"
  ]
}
// → output
{
  "attestation": {
    "handshakeRef": "hs_DEMO0000",
    "outcome": "declined",
    "parties": [],
    "capabilities": [],
    "unmatchedCapabilities": [
      "billing.invoice.list"
    ],
    "effectiveCeiling": null,
    "nonRepudiable": false,
    "declineReasons": [],
    "notes": []
  },
  "performed": {
    "initiator": {},
    "responder": {}
  },
  "mint": {
    "kind": "handshake-notary",
    "source": {}
  },
  "notes": []
}
// note: No mandates presented, so neither side licenses anything and the handshake declines.
```

##### `agents.marketplace.rank`

- **Summary**: Rank mandate templates by standing then narrowest scope — never by adoption.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/agents.marketplace.rank`

**Example**:

```jsonc
// input
{
  "entries": [
    {
      "template": {
        "templateId": "narrow",
        "publisher": "did:web:pub",
        "allowedActionIds": [
          "billing.invoice.list"
        ],
        "maxSafetyLevel": "read",
        "maxSpendFractional": 1000
      },
      "record": {
        "deployments": 50,
        "runs": 10000,
        "incidents": 0,
        "mandateViolations": 0,
        "refusals": 40
      }
    }
  ]
}
// → output
{
  "view": {
    "templates": [],
    "notes": []
  },
  "historyFloor": {
    "deployments": 5,
    "runs": 250
  },
  "notes": []
}
// note: Standing, then narrowest scope. Never adoption.
```

##### `agents.identity.delegate`

- **Summary**: Issue an A2A delegation token granting a remote partner DID a scope subset on your behalf.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `workspaces.view`
- **Audit kind**: `agent.delegation.issued`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/agents.identity.delegate`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "fromAgentDid": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc",
  "toRemoteDid": "did:web:partner.example.com:agents:bot",
  "scopes": [
    "read:audit"
  ],
  "validForDays": 7,
  "purposeReason": "Partner integration handoff"
}
// → output
{
  "delegationVcSerialized": "eyJhbGciOiJFZERTQSJ9…",
  "delegationHandle": "delg_demo00000000000000000000",
  "expiresAt": "2026-05-29T12:00:00.000Z"
}
// note: Issue A2A delegation.
```

##### `agents.identity.delegate.revoke`

- **Summary**: Revoke an issued A2A delegation. Flips its bit in the published BitstringStatusList; listRevocable is false for delegations that predate the list.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `workspaces.view`
- **Audit kind**: `agent.delegation.revoked`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/agents.identity.delegate.revoke`

**Example**:

```jsonc
// input
{
  "delegationHandle": "delg_demo00000000000000000000",
  "reason": "Partnership ended"
}
// → output
{
  "revokedAt": "2026-05-22T12:00:00.000Z",
  "listRevocable": true
}
// note: Withdraw a delegation.
```

##### `agents.mandate.issue`

- **Summary**: Issue an AP2 Verifiable Credential mandate authorising an agent up to spend / volume limits.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `workspaces.view`
- **Audit kind**: `agent.mandate.issued`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/agents.mandate.issue`

**Example**:

```jsonc
// input
{
  "label": "Stripe refund bot — Q3",
  "agentDid": "did:web:trustvice.com:agents:refund-bot",
  "allowedActionIds": [
    "billing.subscription.upgrade",
    "entpoind.attest.agent-call"
  ],
  "maxSafetyLevel": "billing_impacting",
  "workspaceIds": [
    "ws_DEMODEFAULT0000000000"
  ],
  "maxSpendUsdFractional": 50000,
  "maxInvocations": 100,
  "validForDays": 30
}
// → output
{
  "mandateHandle": "mandate_DEMO00000000000000000000",
  "vcId": "urn:uuid:11111111-2222-3333-4444-555555555555",
  "sdJwtVcSerialized": "eyJhbGciOiJFZERTQSJ9…~WyJzYWx0Iiw…~",
  "validUntil": "2026-06-21T12:00:00.000Z",
  "issuerDid": "did:web:trustvice.com:agents:mandate-issuer"
}
// note: Issue an AP2 mandate.
```

##### `agents.mandate.list`

- **Summary**: List mandates issued under the principal.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `workspaces.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/agents.mandate.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "mandates": [],
  "nextCursor": null
}
// note: List mandates.
```

##### `agents.mandate.verify`

- **Summary**: Verify a presented mandate VC against an action request. Returns ok or a structured reason.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/agents.mandate.verify`

**Example**:

```jsonc
// input
{
  "presentationSerialized": "eyJhbGciOiJFZERTQSJ9.eyJleGFtcGxlIjp0cnVlfQ.c2lnbmF0dXJlLWV4YW1wbGU",
  "requestedActionId": "billing.subscription.upgrade",
  "audience": "https://api.trustvice.com",
  "nonce": "abc123abc123"
}
// → output
{
  "ok": true,
  "mandateHandle": "mandate_DEMO00000000000000000000",
  "vcId": "urn:uuid:11111111-2222-3333-4444-555555555555",
  "remainingSpendUsdFractional": 25000,
  "remainingInvocations": 50,
  "issuerResolutionSource": "live"
}
// note: Verify a mandate.
```

##### `agents.mandate.revoke`

- **Summary**: Revoke a mandate. Goes into the BitstringStatusList revocation register immediately.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `workspaces.view`
- **Audit kind**: `agent.mandate.revoked`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/agents.mandate.revoke`

**Example**:

```jsonc
// input
{
  "mandateHandle": "mandate_DEMO00000000000000000000"
}
// → output
{
  "revokedAt": "2026-05-22T12:00:00.000Z"
}
// note: Revoke a mandate.
```

##### `agents.spiffe.bind`

- **Summary**: Bind a SPIFFE ID to an agent DID so SVIDs (X.509 or JWT) can attest as that agent.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `workspaces.view`
- **Audit kind**: `agent.spiffe.bound`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/agents.spiffe.bind`

**Example**:

```jsonc
// input
{
  "agentDid": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc",
  "spiffeId": "spiffe://corp.example.com/svc/billing",
  "svidType": "jwt"
}
// → output
{
  "agentDid": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc",
  "spiffeId": "spiffe://corp.example.com/svc/billing",
  "boundAt": "2026-05-22T12:00:00.000Z"
}
// note: Bind SPIFFE workload to agent.
```

##### `agents.spiffe.workload.attest`

- **Summary**: Exchange a SPIFFE SVID for a short-lived DPoP-bound Trustvice session.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/agents.spiffe.workload.attest`

**Example**:

```jsonc
// input
{
  "svid": {
    "type": "jwt",
    "token": "eyJhbGciOiJFZERTQSJ9.eyJleGFtcGxlIjp0cnVlfQ.c2lnbmF0dXJlLWV4YW1wbGU"
  },
  "dpopKey": {
    "kty": "OKP",
    "crv": "Ed25519",
    "x": "<base64url>"
  }
}
// → output
{
  "sessionToken": "tv_sess_demo…",
  "expiresAt": "2026-05-22T12:05:00.000Z",
  "agentDid": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc",
  "effectiveScopes": [
    "read:audit"
  ]
}
// note: Workload exchange.
```

##### `agents.trusted-roots.list`

- **Summary**: List partner organization DIDs the workspace accepts as A2A federation roots.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `workspaces.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/agents.trusted-roots.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "roots": []
}
// note: List trusted A2A roots.
```

##### `agents.trusted-roots.add`

- **Summary**: Add a partner organization DID to the trusted-roots list for this workspace.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `workspaces.view`
- **Audit kind**: `agent.trusted_root.added`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/agents.trusted-roots.add`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "did": "did:web:partner.example.com",
  "organizationName": "Partner Example Corp",
  "maxAcceptedSafetyLevel": "mutation"
}
// → output
{
  "addedAt": "2026-05-22T12:00:00.000Z"
}
// note: Add federated root.
```

### `trustactor` (10 actions)

TrustActor spot-actor roster (witness/council/historian/custodian/conscience/…) + the per-workspace run ledger — post runs, list/diff/replay them, verify the hash-chain.

##### `trustactor.run`

- **Summary**: Post a run to a TrustActor spot actor (witness/council/historian/custodian/conscience/…) — observe + decide + anchor it in the workspace hash-chain.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/trustactor.run`

**Example**:

```jsonc
// input
{
  "version": "v1",
  "actor": "witness",
  "agentDid": "did:web:example.com:agent:billing",
  "input": {
    "task": "refund",
    "amount": 4200
  }
}
// → output
{
  "status": "ok",
  "receipt": {
    "runId": "run_abc"
  }
}
// note: Witness a billing-agent run.
```

##### `trustactor.runs.list`

- **Summary**: List the workspace's TrustActor runs (actor IS the surface: witness | historian | custodian | conscience | …).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/trustactor.runs.list`

**Example**:

```jsonc
// input
{
  "actor": "witness",
  "limit": 20
}
// → output
{
  "runs": [],
  "count": 0
}
// note: Recent witness runs.
```

##### `trustactor.actors.list`

- **Summary**: List the TrustActor roster (optionally for one version) with each actor's min tier.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/trustactor.actors.list`

**Example**:

```jsonc
// input
{
  "version": "v1"
}
// → output
{
  "actors": [
    {
      "id": "witness",
      "version": "v1",
      "minTier": "free"
    }
  ]
}
// note: Discover v1 actors.
```

##### `trustactor.agents.list`

- **Summary**: List the workspace's posting agents (distinct agent DIDs across runs, with counts + last-seen).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/trustactor.agents.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "agents": [],
  "count": 0
}
// note: Who's posting runs.
```

##### `trustactor.runs.verify-chain`

- **Summary**: Verify the integrity of the workspace's run hash-chain from a starting sequence.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/trustactor.runs.verify-chain`

**Example**:

```jsonc
// input
{
  "from": 1
}
// → output
{
  "ok": true
}
// note: Prove the chain is intact.
```

##### `trustactor.runs.diff`

- **Summary**: Compare two TrustActor runs (classification + payload diff).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/trustactor.runs.diff`

**Example**:

```jsonc
// input
{
  "a": "run_abc",
  "b": "run_def"
}
// → output
{
  "ok": true
}
// note: Diff two runs.
```

##### `trustactor.runs.replay`

- **Summary**: Reconstruct + re-verify a single run from its chain entry.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/trustactor.runs.replay`

**Example**:

```jsonc
// input
{
  "runId": "run_abc"
}
// → output
{
  "ok": true,
  "found": true
}
// note: Replay a run.
```

##### `trustactor.liability.blame-graph`

- **Summary**: Apportion fault across a multi-agent failure from a signed causal chain.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/trustactor.liability.blame-graph`

**Example**:

```jsonc
// input
{
  "incidentRef": "inc_1",
  "nodes": [
    {
      "nodeId": "n1",
      "actorDid": "did:web:a.example",
      "action": "issued a refund",
      "actedCorrectly": false,
      "evidenceRefs": [
        "run_1"
      ],
      "causalWeight": 1
    }
  ]
}
// → output
{
  "graph": {
    "incidentRef": "inc_1",
    "computedAt": "2026-09-04T00:00:00.000Z",
    "apportioned": [],
    "unattributed": {
      "share": 0,
      "reasons": []
    },
    "exonerated": [],
    "fullyEvidenced": true,
    "notes": []
  },
  "notes": []
}
// note: One at-fault node, fully evidenced.
```

##### `trustactor.liability.indemnity-feed`

- **Summary**: Build the underwriting evidence feed for one agent — observed experience, stated credibility, and no pricing.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/trustactor.liability.indemnity-feed`

**Example**:

```jsonc
// input
{
  "agentRef": "did:web:a.example",
  "window": {
    "from": "2026-01-01T00:00:00.000Z",
    "to": "2026-09-01T00:00:00.000Z",
    "runs": 5000
  },
  "experience": {
    "incidents": 2,
    "mandateViolations": 1,
    "breakerTrips": 3,
    "oversightAdherence": 0.9
  }
}
// → output
{
  "feed": {
    "agentRef": "did:web:a.example",
    "window": {},
    "credibility": 0.68,
    "credibilityBasis": {
      "nFull": 1082,
      "floor": 30
    },
    "belowFloor": false,
    "entries": [],
    "fault": {
      "totalShare": 0,
      "findings": 0,
      "note": ""
    },
    "priced": false,
    "notes": []
  },
  "notes": []
}
// note: A data source, not a price.
```

##### `trustactor.actor-score`

- **Summary**: Compute an agent's Actor Score from its signed runs, with every deduction naming the run that caused it.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/trustactor.actor-score`

**Example**:

```jsonc
// input
{
  "agentRef": "did:web:a.example",
  "runs": [
    {
      "runId": "run_1",
      "signed": true,
      "safetyLevel": "read",
      "oversightHonoured": true,
      "mandateViolation": false,
      "breakerTripped": false,
      "incident": false
    }
  ]
}
// → output
{
  "score": {
    "agentRef": "did:web:a.example",
    "score": null,
    "band": null,
    "runsScored": 1,
    "runsExcludedUnsigned": 0,
    "tiers": [],
    "unprovenTiers": [
      "read"
    ],
    "faultingRunIds": [],
    "computedAt": "2026-09-04T00:00:00.000Z",
    "notes": []
  },
  "mint": null,
  "notMintableReason": "Not mintable: 1 signed run(s), below the floor…",
  "notes": []
}
// note: One run is not a score.
```

### `nexus` (51 actions)

Nexus reputation/receipts/compliance primitives (oracle, charter, compass, lattice, sentinel, tribunal, keyring, imprint, underwriter, ledger).

##### `nexus.catalog.get`

- **Summary**: Get the Nexus product catalogue (the available primitives + tiers for the workspace).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.catalog.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "products": [
    {
      "product": "oracle",
      "basePath": "/v1/nexus/oracle",
      "mcpEndpoint": "/api/v1/nexus/oracle/mcp",
      "graphqlEndpoint": "/api/v1/nexus/oracle/graphql"
    }
  ]
}
// note: List Nexus primitives.
```

##### `nexus.usage.get`

- **Summary**: Get the workspace's Nexus usage + quota for the current period.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.usage.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "period": "2026-09",
  "tier": "pro",
  "metrics": [
    {
      "metric": "oracle_query",
      "used": 1284,
      "limit": 50000
    },
    {
      "metric": "ledger_append",
      "used": 63,
      "limit": null
    }
  ]
}
// note: Read Nexus usage.
```

##### `nexus.oracle.agent.get`

- **Summary**: Look up the Nexus Oracle reputation for a specific agent (by id / DID).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.oracle.agent.get`

**Example**:

```jsonc
// input
{
  "agentId": "did:web:example.com:agent:support"
}
// → output
{
  "reputation": {
    "agentId": "did:web:example.com:agent:support",
    "samples": 412,
    "reputationScoreBps": 8730,
    "avgModulationBps": -120,
    "avgConfidenceBps": 7400,
    "calibrationSamples": 96,
    "calibrationAccuracyBps": 8100,
    "trend": "improving",
    "firstSeen": "2026-06-02T09:14:00.000Z",
    "lastSeen": "2026-09-01T18:22:00.000Z"
  }
}
// note: Reputation for an agent.
```

##### `nexus.oracle.price`

- **Summary**: Price an agent action by risk, returning modulation, escrow and confidence.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.oracle.use`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.oracle.price`

**Example**:

```jsonc
// input
{
  "actionDescription": "transfer funds to an external account",
  "agentId": "agent_1"
}
// → output
{
  "id": "prc_1",
  "priceCents": 250,
  "modulationBps": 7500,
  "confidenceBps": 8000
}
// note: Price a risky action.
```

##### `nexus.oracle.policy.set`

- **Summary**: Set the workspace's Oracle base price and risk multiplier.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `nexus.oracle.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.oracle.policy.set`

**Example**:

```jsonc
// input
{
  "basePriceCents": 250,
  "riskMultiplierBps": 3000
}
// → output
{
  "policy": {
    "basePriceCents": 250,
    "riskMultiplierBps": 3000
  }
}
// note: Set the pricing policy.
```

##### `nexus.oracle.calibration.feedback`

- **Summary**: Report whether a price Oracle quoted turned out accurate.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.oracle.use`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.oracle.calibration.feedback`

**Example**:

```jsonc
// input
{
  "pricingId": "prc_1",
  "observedOutcome": "accurate"
}
// → output
{
  "id": "cal_1"
}
// note: Close the calibration loop.
```

##### `nexus.oracle.model.pin`

- **Summary**: Pin the Oracle pricing model version for the workspace.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `nexus.oracle.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.oracle.model.pin`

**Example**:

```jsonc
// input
{
  "modelId": "risk-keyword-v1-strict"
}
// → output
{
  "pinnedModelId": "risk-keyword-v1-strict"
}
// note: Pin a model.
```

##### `nexus.oracle.source.add`

- **Summary**: Record an external reputation source for Oracle.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.oracle.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.oracle.source.add`

**Example**:

```jsonc
// input
{
  "name": "Partner reputation",
  "url": "https://example.test/rep"
}
// → output
{
  "id": "src_1"
}
// note: Record a source.
```

##### `nexus.oracle.graphql`

- **Summary**: Query the Oracle read surface (policy, pricings, reputation).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `nexus.oracle.use`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.oracle.graphql`

**Example**:

```jsonc
// input
{
  "query": "{ pricings { id } }"
}
// → output
{
  "data": {
    "pricings": []
  }
}
// note: Query Oracle.
```

##### `nexus.charter.publish`

- **Summary**: Publish a charter version for a publisher.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.charter.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.charter.publish`

**Example**:

```jsonc
// input
{
  "publisher": "acme",
  "rules": {
    "retention": "30d"
  }
}
// → output
{
  "id": "cht_1",
  "version": 1
}
// note: Publish terms.
```

##### `nexus.charter.validate`

- **Summary**: Validate a set of charter rules without publishing them.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `nexus.charter.use`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.charter.validate`

**Example**:

```jsonc
// input
{
  "rules": {
    "retention": "30d"
  }
}
// → output
{
  "valid": true
}
// note: Validate rules.
```

##### `nexus.charter.audit.request`

- **Summary**: Request an audit of a publisher's charter.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.charter.use`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.charter.audit.request`

**Example**:

```jsonc
// input
{
  "publisher": "acme",
  "scope": "terms"
}
// → output
{
  "id": "aud_1",
  "status": "requested"
}
// note: Request an audit.
```

##### `nexus.charter.graphql`

- **Summary**: Query the Charter read surface (charters, audits).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `nexus.charter.use`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.charter.graphql`

**Example**:

```jsonc
// input
{
  "query": "{ charters { id } }"
}
// → output
{
  "data": {
    "charters": []
  }
}
// note: Query Charter.
```

##### `nexus.compass.verify`

- **Summary**: Verify that a proposed action matches the user's stated request.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.compass.use`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.compass.verify`

**Example**:

```jsonc
// input
{
  "userRequest": "book a flight under $500",
  "proposedAction": {
    "kind": "purchase",
    "amount": 480
  }
}
// → output
{
  "id": "ver_1",
  "verdict": "aligned"
}
// note: Verify an intent.
```

##### `nexus.compass.verify.explain`

- **Summary**: Explain a stored Compass verification.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `nexus.compass.use`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.compass.verify.explain`

**Example**:

```jsonc
// input
{
  "verificationId": "ver_1"
}
// → output
{
  "factors": []
}
// note: Explain a verdict.
```

##### `nexus.compass.policy.set`

- **Summary**: Set the Compass review and deny thresholds.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `nexus.compass.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.compass.policy.set`

**Example**:

```jsonc
// input
{
  "reviewThresholdBps": 7000,
  "denyThresholdBps": 8500
}
// → output
{
  "policy": {
    "reviewThresholdBps": 7000
  }
}
// note: Set thresholds.
```

##### `nexus.compass.hitl.escalate`

- **Summary**: Escalate a verification to a human reviewer.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.compass.use`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.compass.hitl.escalate`

**Example**:

```jsonc
// input
{
  "verificationId": "ver_1",
  "reason": "ambiguous intent"
}
// → output
{
  "id": "esc_1"
}
// note: Escalate to a human.
```

##### `nexus.compass.model.pin`

- **Summary**: Pin the Compass matching model version.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `nexus.compass.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.compass.model.pin`

**Example**:

```jsonc
// input
{
  "modelId": "intent-align-v1"
}
// → output
{
  "pinnedModelId": "intent-align-v1"
}
// note: Pin a model.
```

##### `nexus.compass.graphql`

- **Summary**: Query the Compass read surface (verifications, policy, escalations).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `nexus.compass.use`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.compass.graphql`

**Example**:

```jsonc
// input
{
  "query": "{ verifications { id } }"
}
// → output
{
  "data": {
    "verifications": []
  }
}
// note: Query Compass.
```

##### `nexus.ledger.verify`

- **Summary**: Verify an action claim and mint its receipt.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.ledger.use`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.ledger.verify`

**Example**:

```jsonc
// input
{
  "actionClaim": {
    "subject": "did:tv:a",
    "actionId": "act_1"
  }
}
// → output
{
  "verification": {
    "id": "lv_1"
  },
  "receipt": {
    "id": "rcpt_1"
  }
}
// note: Verify a claim.
```

##### `nexus.ledger.verifier.create`

- **Summary**: Register a custom Ledger verifier.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.ledger.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.ledger.verifier.create`

**Example**:

```jsonc
// input
{
  "name": "Invoice checks",
  "definition": {
    "requires": [
      "subject"
    ]
  }
}
// → output
{
  "verifierId": "lvf_1"
}
// note: Add a verifier.
```

##### `nexus.ledger.locker.connect`

- **Summary**: Connect an external receipt locker.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.ledger.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.ledger.locker.connect`

**Example**:

```jsonc
// input
{
  "name": "Archive",
  "endpoint": "https://example.test/locker"
}
// → output
{
  "id": "conn_1"
}
// note: Connect a locker.
```

##### `nexus.ledger.graphql`

- **Summary**: Query the Ledger read surface (receipts).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `nexus.ledger.use`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.ledger.graphql`

**Example**:

```jsonc
// input
{
  "query": "{ receipts { id } }"
}
// → output
{
  "data": {
    "receipts": []
  }
}
// note: Query Ledger.
```

##### `nexus.lattice.delegation.publish`

- **Summary**: Publish a delegation from one agent to another.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.lattice.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.lattice.delegation.publish`

**Example**:

```jsonc
// input
{
  "sourceAgent": "did:tv:a",
  "targetAgent": "did:tv:b",
  "actionClass": "read",
  "expiration": "2027-01-01T00:00:00.000Z"
}
// → output
{
  "id": "del_1"
}
// note: Publish a delegation.
```

##### `nexus.lattice.path.find`

- **Summary**: Find a delegation path between two agents.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `nexus.lattice.use`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.lattice.path.find`

**Example**:

```jsonc
// input
{
  "sourceAgent": "did:tv:a",
  "targetAgent": "did:tv:b"
}
// → output
{
  "found": true,
  "path": [
    "did:tv:a",
    "did:tv:b"
  ]
}
// note: Find a path.
```

##### `nexus.lattice.path.verify`

- **Summary**: Verify that a specific delegation path is valid.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `nexus.lattice.use`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.lattice.path.verify`

**Example**:

```jsonc
// input
{
  "path": [
    "did:tv:a",
    "did:tv:b"
  ]
}
// → output
{
  "valid": true
}
// note: Verify a path.
```

##### `nexus.lattice.federation.node.add`

- **Summary**: Add a federation peer to the delegation graph.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.lattice.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.lattice.federation.node.add`

**Example**:

```jsonc
// input
{
  "name": "Partner",
  "endpoint": "https://example.test/lattice"
}
// → output
{
  "id": "peer_1"
}
// note: Add a peer.
```

##### `nexus.lattice.graphql`

- **Summary**: Query the Lattice read surface (delegations, peers).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `nexus.lattice.use`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.lattice.graphql`

**Example**:

```jsonc
// input
{
  "query": "{ delegations { id } }"
}
// → output
{
  "data": {
    "delegations": []
  }
}
// note: Query Lattice.
```

##### `nexus.sentinel.ingest`

- **Summary**: Submit an agent request for Sentinel inspection.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.sentinel.use`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.sentinel.ingest`

**Example**:

```jsonc
// input
{
  "destination": "https://example.test/api",
  "agentId": "agent_1"
}
// → output
{
  "id": "evt_1",
  "verdict": "clean"
}
// note: Inspect a request.
```

##### `nexus.sentinel.policy.create`

- **Summary**: Create a Sentinel traffic policy.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.sentinel.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.sentinel.policy.create`

**Example**:

```jsonc
// input
{
  "name": "Block exfil",
  "pattern": "example.test"
}
// → output
{
  "id": "spol_1"
}
// note: Create a policy.
```

##### `nexus.sentinel.classifier.create`

- **Summary**: Register a custom Sentinel classifier.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.sentinel.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.sentinel.classifier.create`

**Example**:

```jsonc
// input
{
  "name": "PII",
  "definition": {
    "match": "ssn"
  }
}
// → output
{
  "classifierId": "cls_1"
}
// note: Add a classifier.
```

##### `nexus.sentinel.graphql`

- **Summary**: Query the Sentinel read surface (events, incidents).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `nexus.sentinel.use`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.sentinel.graphql`

**Example**:

```jsonc
// input
{
  "query": "{ events { id } }"
}
// → output
{
  "data": {
    "events": []
  }
}
// note: Query Sentinel.
```

##### `nexus.tribunal.dispute.file`

- **Summary**: File a dispute against another agent.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.tribunal.use`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.tribunal.dispute.file`

**Example**:

```jsonc
// input
{
  "opposingAgent": "did:tv:b",
  "transactionReference": "txn_1",
  "claim": {
    "reason": "undelivered"
  }
}
// → output
{
  "id": "dsp_1"
}
// note: File a dispute.
```

##### `nexus.tribunal.adjudicator.connect`

- **Summary**: Connect an adjudicator pool.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.tribunal.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.tribunal.adjudicator.connect`

**Example**:

```jsonc
// input
{
  "name": "Panel",
  "endpoint": "https://example.test/adjudicators"
}
// → output
{
  "id": "adj_1"
}
// note: Connect a pool.
```

##### `nexus.tribunal.legal-framework.set`

- **Summary**: Set the workspace's governing legal framework.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `nexus.tribunal.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.tribunal.legal-framework.set`

**Example**:

```jsonc
// input
{
  "legalFramework": "ny-arbitration"
}
// → output
{
  "legalFramework": "ny-arbitration"
}
// note: Set the framework.
```

##### `nexus.tribunal.graphql`

- **Summary**: Query the Tribunal read surface (disputes, precedents).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `nexus.tribunal.use`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.tribunal.graphql`

**Example**:

```jsonc
// input
{
  "query": "{ disputes { id } }"
}
// → output
{
  "data": {
    "disputes": []
  }
}
// note: Query Tribunal.
```

##### `nexus.keyring.credential.mint`

- **Summary**: Mint a scoped, time-boxed credential for a target system.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.keyring.use`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.keyring.credential.mint`

**Example**:

```jsonc
// input
{
  "targetSystem": "billing",
  "intendedAction": "read",
  "ttl": 3600
}
// → output
{
  "credentialId": "krc_1"
}
// note: Mint a credential.
```

##### `nexus.keyring.policy.create`

- **Summary**: Create a Keyring issuance policy.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.keyring.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.keyring.policy.create`

**Example**:

```jsonc
// input
{
  "name": "Read-only",
  "kind": "allow"
}
// → output
{
  "id": "kpol_1"
}
// note: Create a policy.
```

##### `nexus.keyring.vault.reference.add`

- **Summary**: Record a POINTER into your own vault. Never the secret itself.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.keyring.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.keyring.vault.reference.add`

**Example**:

```jsonc
// input
{
  "name": "Billing key",
  "ref": "vault://acme/billing"
}
// → output
{
  "masterCredentialId": "kv_1"
}
// note: Record a reference.
```

##### `nexus.keyring.graphql`

- **Summary**: Query the Keyring read surface (credentials, policies).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `nexus.keyring.use`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.keyring.graphql`

**Example**:

```jsonc
// input
{
  "query": "{ credentials { id } }"
}
// → output
{
  "data": {
    "credentials": []
  }
}
// note: Query Keyring.
```

##### `nexus.imprint.stamp.issue`

- **Summary**: Issue a provenance stamp over a payload.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.imprint.use`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.imprint.stamp.issue`

**Example**:

```jsonc
// input
{
  "payload": {
    "text": "hello"
  },
  "license": {
    "policyId": "ipol_1"
  }
}
// → output
{
  "stampId": "stm_1"
}
// note: Issue a stamp.
```

##### `nexus.imprint.stamp.verify`

- **Summary**: Verify a payload against its Imprint stamp.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `nexus.imprint.use`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.imprint.stamp.verify`

**Example**:

```jsonc
// input
{
  "payload": {
    "text": "hello"
  }
}
// → output
{
  "valid": true
}
// note: Verify a stamp.
```

##### `nexus.imprint.policy.create`

- **Summary**: Create an Imprint licensing policy.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.imprint.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.imprint.policy.create`

**Example**:

```jsonc
// input
{
  "name": "Attribution",
  "terms": {
    "reuse": "attribution"
  }
}
// → output
{
  "policyId": "ipol_1"
}
// note: Create a policy.
```

##### `nexus.imprint.runtime.register`

- **Summary**: Register a runtime that may issue Imprint stamps.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.imprint.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.imprint.runtime.register`

**Example**:

```jsonc
// input
{
  "name": "Editor",
  "endpoint": "https://example.test/runtime"
}
// → output
{
  "id": "irt_1"
}
// note: Register a runtime.
```

##### `nexus.imprint.graphql`

- **Summary**: Query the Imprint read surface (stamps, policies).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `nexus.imprint.use`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.imprint.graphql`

**Example**:

```jsonc
// input
{
  "query": "{ stamps { id } }"
}
// → output
{
  "data": {
    "stamps": []
  }
}
// note: Query Imprint.
```

##### `nexus.underwriter.premium.quote`

- **Summary**: Quote a premium for covering an action. A price, not a commitment.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `nexus.underwriter.use`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.underwriter.premium.quote`

**Example**:

```jsonc
// input
{
  "coverageCents": 10000,
  "action": {
    "kind": "transfer"
  }
}
// → output
{
  "premiumCents": 200
}
// note: Quote a premium.
```

##### `nexus.underwriter.coverage.bind`

- **Summary**: Bind coverage against a policy — this creates a warranty.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `nexus.underwriter.use`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.underwriter.coverage.bind`

**Example**:

```jsonc
// input
{
  "policyId": "upol_1",
  "transactionId": "txn_1",
  "coverageCents": 10000
}
// → output
{
  "warrantyId": "wnt_1"
}
// note: Bind coverage.
```

##### `nexus.underwriter.claim.file`

- **Summary**: File a claim against a bound warranty.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.underwriter.use`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.underwriter.claim.file`

**Example**:

```jsonc
// input
{
  "warrantyId": "wnt_1",
  "reason": "undelivered"
}
// → output
{
  "claimId": "clm_1"
}
// note: File a claim.
```

##### `nexus.underwriter.policy.create`

- **Summary**: Create a coverage policy with its rate and ceiling.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.underwriter.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.underwriter.policy.create`

**Example**:

```jsonc
// input
{
  "name": "Standard",
  "baseRateBps": 200,
  "maxCoverageCents": 500000
}
// → output
{
  "policyId": "upol_1"
}
// note: Create a policy.
```

##### `nexus.underwriter.backend.connect`

- **Summary**: Connect a reinsurance backend.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `nexus.underwriter.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.underwriter.backend.connect`

**Example**:

```jsonc
// input
{
  "name": "Reinsurer",
  "endpoint": "https://example.test/reinsurance"
}
// → output
{
  "id": "ubk_1"
}
// note: Connect a backend.
```

##### `nexus.underwriter.graphql`

- **Summary**: Query the Underwriter read surface (warranties, claims).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `nexus.underwriter.use`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/nexus.underwriter.graphql`

**Example**:

```jsonc
// input
{
  "query": "{ claims { id } }"
}
// → output
{
  "data": {
    "claims": []
  }
}
// note: Query Underwriter.
```

### `vector` (19 actions)

Vector agent registry + pricing + public verify reads (registry entries, MCP servers, pricing lookups).

##### `vector.registry.search`

- **Summary**: Search the public Vector agent registry.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/vector.registry.search`

**Example**:

```jsonc
// input
{
  "q": "support agent"
}
// → output
{
  "entries": [
    {
      "id": "ag_demo_1",
      "kind": "agent",
      "name": "Support Agent",
      "description": "Answers tier-1 support questions over the public docs.",
      "endpoint": "https://agents.example.com/support",
      "tags": [
        "support",
        "docs"
      ],
      "createdAt": "2026-05-04T10:00:00.000Z"
    }
  ],
  "count": 1
}
// note: Find registered agents.
```

##### `vector.registry.entry.get`

- **Summary**: Get a single Vector registry entry by id.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/vector.registry.entry.get`

**Example**:

```jsonc
// input
{
  "id": "ag_demo_1"
}
// → output
{
  "entry": {
    "id": "ag_demo_1",
    "kind": "agent",
    "name": "Support Agent",
    "description": "Answers tier-1 support questions over the public docs.",
    "endpoint": "https://agents.example.com/support",
    "tags": [
      "support",
      "docs"
    ],
    "createdAt": "2026-05-04T10:00:00.000Z"
  }
}
// note: Resolve a registry entry.
```

##### `vector.pricing.get`

- **Summary**: Look up Vector public pricing.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/vector.pricing.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "product": "vector",
  "currency": "USD",
  "note": "Display currency varies by region (EUR/GBP/USD); the amount is identical.",
  "tiers": [
    {
      "tier": "vector_free",
      "monthlyUsd": 0
    },
    {
      "tier": "vector_starter",
      "monthlyUsd": 59
    },
    {
      "tier": "vector_pro",
      "monthlyUsd": 179
    },
    {
      "tier": "vector_enterprise",
      "monthlyUsd": null
    }
  ]
}
// note: Read Vector pricing.
```

##### `vector.mcp.servers.list`

- **Summary**: List the MCP servers in the public Vector registry.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/vector.mcp.servers.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "servers": [
    {
      "id": "mcp_docs_1",
      "kind": "mcp_server",
      "name": "Docs MCP",
      "description": "Read-only MCP server over the public documentation.",
      "endpoint": "https://mcp.example.com/docs",
      "tags": [
        "docs",
        "read-only"
      ],
      "createdAt": "2026-05-04T10:00:00.000Z"
    }
  ],
  "count": 1
}
// note: Discover MCP servers.
```

##### `vector.catalog.get`

- **Summary**: Get the workspace's Vector product catalogue.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/vector.catalog.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "products": [
    {
      "product": "registry",
      "basePath": "/v1/vector/registry",
      "mcpEndpoint": "/v1/vector/registry/mcp"
    },
    {
      "product": "mirror",
      "basePath": "/v1/vector/mirror",
      "mcpEndpoint": "/v1/vector/mirror/mcp"
    }
  ]
}
// note: List Vector products.
```

##### `vector.registry.register`

- **Summary**: Register an agent, tool, MCP server or service in the Vector registry.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `vector.registry.register`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/vector.registry.register`

**Example**:

```jsonc
// input
{
  "kind": "agent",
  "name": "Support Agent",
  "description": "Answers tier-1 support questions.",
  "visibility": "private"
}
// → output
{
  "entry": {
    "id": "ag_1",
    "kind": "agent",
    "name": "Support Agent",
    "visibility": "private"
  }
}
// note: Register an agent.
```

##### `vector.persona.create`

- **Summary**: Create a Vector persona — a named attribute + scope set an agent can act under.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `vector.persona.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/vector.persona.create`

**Example**:

```jsonc
// input
{
  "name": "Auditor",
  "attributes": {
    "role": "auditor"
  },
  "scopes": [
    "read"
  ]
}
// → output
{
  "id": "per_1",
  "name": "Auditor"
}
// note: Create a persona.
```

##### `vector.persona.select`

- **Summary**: Resolve a persona by id for the calling agent.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `vector.persona.manage`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/vector.persona.select`

**Example**:

```jsonc
// input
{
  "personaId": "per_1"
}
// → output
{
  "persona": {
    "id": "per_1",
    "name": "Auditor"
  }
}
// note: Select a persona.
```

##### `vector.policy.create`

- **Summary**: Create a Vector egress policy.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `vector.policy.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/vector.policy.create`

**Example**:

```jsonc
// input
{
  "name": "Egress allowlist",
  "effect": "deny_by_default",
  "rules": {
    "allow": [
      "https://example.test"
    ]
  }
}
// → output
{
  "id": "pol_1",
  "name": "Egress allowlist"
}
// note: Create a policy.
```

##### `vector.policy.evaluate`

- **Summary**: Ask whether a destination is permitted by the workspace's Vector policies.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `vector.policy.evaluate`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/vector.policy.evaluate`

**Example**:

```jsonc
// input
{
  "destination": "https://example.test/agent"
}
// → output
{
  "allowed": false,
  "reason": "deny_by_default"
}
// note: Evaluate a destination.
```

##### `vector.vault.credential.create`

- **Summary**: Record a credential REFERENCE in the Vector vault. Never the secret itself.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `vector.vault.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/vector.vault.credential.create`

**Example**:

```jsonc
// input
{
  "name": "Billing API",
  "credType": "api_key"
}
// → output
{
  "id": "cred_1",
  "name": "Billing API"
}
// note: Record a credential reference.
```

##### `vector.conduit.connection.create`

- **Summary**: Create a Vector conduit connection to an upstream provider.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `vector.conduit.connect`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/vector.conduit.connection.create`

**Example**:

```jsonc
// input
{
  "name": "Billing",
  "provider": "http",
  "authMode": "byo",
  "config": {
    "url": "https://example.test"
  }
}
// → output
{
  "id": "con_1",
  "name": "Billing"
}
// note: Create a connection.
```

##### `vector.cartograph.mapping.create`

- **Summary**: Create a Cartograph field mapping between two schemas.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `vector.cartograph.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/vector.cartograph.mapping.create`

**Example**:

```jsonc
// input
{
  "name": "CRM → ledger",
  "sourceSchema": "crm.v1",
  "targetSchema": "ledger.v2",
  "fieldMap": {
    "customer_id": "account"
  }
}
// → output
{
  "id": "map_1",
  "name": "CRM → ledger"
}
// note: Create a mapping.
```

##### `vector.cartograph.translate`

- **Summary**: Translate one record through a Cartograph mapping.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `vector.cartograph.translate`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/vector.cartograph.translate`

**Example**:

```jsonc
// input
{
  "mappingId": "map_1",
  "payload": {
    "account": "A-1"
  }
}
// → output
{
  "translated": {
    "customer_id": "A-1"
  }
}
// note: Translate a record.
```

##### `vector.cartograph.batch`

- **Summary**: Translate many records through a Cartograph mapping in one call.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `vector.cartograph.translate`
- **Audit kind**: `agent_read`
- **Rate class**: `expensive`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/vector.cartograph.batch`

**Example**:

```jsonc
// input
{
  "mappingId": "map_1",
  "records": [
    {
      "account": "A-1"
    },
    {
      "account": "A-2"
    }
  ]
}
// → output
{
  "translated": [
    {
      "customer_id": "A-1"
    },
    {
      "customer_id": "A-2"
    }
  ]
}
// note: Translate a batch.
```

##### `vector.compliance.declare`

- **Summary**: Declare a compliance framework and its constraints for the workspace.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `vector.compliance.declare`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/vector.compliance.declare`

**Example**:

```jsonc
// input
{
  "framework": "gdpr",
  "constraints": {
    "residency": "eu"
  }
}
// → output
{
  "id": "dec_1",
  "framework": "gdpr"
}
// note: Declare GDPR.
```

##### `vector.compliance.check`

- **Summary**: Check a region against a declared compliance framework.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `vector.compliance.check`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/vector.compliance.check`

**Example**:

```jsonc
// input
{
  "framework": "gdpr",
  "region": "eu"
}
// → output
{
  "compliant": true
}
// note: Check a region.
```

##### `vector.routing.route.create`

- **Summary**: Create a Vector route — an intent and the candidates that can serve it.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `vector.routing.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/vector.routing.route.create`

**Example**:

```jsonc
// input
{
  "intent": "summarise",
  "strategy": "lowest_cost",
  "candidates": [
    {
      "target": "https://example.test/a",
      "costUm": 1
    }
  ]
}
// → output
{
  "id": "rt_1",
  "intent": "summarise"
}
// note: Create a route.
```

##### `vector.routing.resolve`

- **Summary**: Resolve an intent to the target Vector selects for it.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `vector.routing.resolve`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/vector.routing.resolve`

**Example**:

```jsonc
// input
{
  "intent": "summarise"
}
// → output
{
  "selected": {
    "target": "https://example.test/a"
  }
}
// note: Resolve an intent.
```

### `pricevice` (11 actions)

Pricevice Pricing Assurance — issue Price Provenance Receipts (price.attest), list/verify PPRs, manage pricing policies, read the Keystone integrity summary, generate Aegis disclosures.

##### `pricevice.attest.price`

- **Summary**: Issue a Price Provenance Receipt (PPR) for a pricing decision — signed, time-anchored, input-committed, policy-conformance-checked.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `pricevice.attest`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/pricevice.attest.price`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "modelLabel": "rate-card-2026Q2",
  "policyId": "01J9X4P9R7Z2C1A1F2A8VBJYP1",
  "inputCommitment": "abcd1234567890abcdef1234567890abcdef1234567890abcdef12345678abcd",
  "kind": "quote",
  "amountMinor": 1250000,
  "currency": "USD",
  "unit": "total",
  "domain": "saas",
  "reference": "Q-2026-0042",
  "buyerRef": "segment:mid-market"
}
// → output
{
  "receipt": {
    "version": "1",
    "receiptId": "01J9X4P9R7Z2C1A1F2A8VBJYV9",
    "issuedAt": "2026-06-10T12:00:00.000Z",
    "type": "price.attest",
    "signatureKeyId": "k1B2c3D4e5F6g7H8i9J0kA",
    "signature": "...",
    "body": {}
  }
}
// note: Attest a quoted price.
```

##### `pricevice.receipt.list`

- **Summary**: List Price Provenance Receipts for a workspace (filter by domain or conformance verdict).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `pricevice.receipts.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/pricevice.receipt.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "domain": "saas"
}
// → output
{
  "receipts": [],
  "nextCursor": null
}
// note: List PPRs.
```

##### `pricevice.receipt.get`

- **Summary**: Get a single Price Provenance Receipt with its full seven-component body.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `pricevice.receipts.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/pricevice.receipt.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "receiptId": "01J9X4P9R7Z2C1A1F2A8VBJYV9"
}
// → output
{
  "receipt": {
    "version": "1",
    "receiptId": "01J9X4P9R7Z2C1A1F2A8VBJYV9",
    "issuedAt": "2026-06-10T12:00:00.000Z",
    "type": "price.attest",
    "signatureKeyId": "k1B2c3D4e5F6g7H8i9J0kA",
    "signature": "...",
    "body": {}
  }
}
// note: Read a PPR.
```

##### `pricevice.receipt.verify`

- **Summary**: Verify a PPR's Ed25519 signature against the published Pricevice public keys. Public — no account required. Cannot be disabled.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/pricevice.receipt.verify`

**Example**:

```jsonc
// input
{
  "receipt": {
    "version": "1",
    "receiptId": "01J9X4P9R7Z2C1A1F2A8VBJYV9",
    "issuedAt": "2026-06-10T12:00:00.000Z",
    "type": "price.attest",
    "signatureKeyId": "k1B2c3D4e5F6g7H8i9J0kA",
    "signature": "...",
    "body": {}
  }
}
// → output
{
  "ok": true,
  "signedAt": "2026-06-10T12:00:00.000Z",
  "signatureKeyId": "k1B2c3D4e5F6g7H8i9J0kA",
  "publishedKeyUrl": "https://api.trustvice.com/.well-known/pricevice-keys.json"
}
// note: Verify a PPR.
```

##### `pricevice.policy.add`

- **Summary**: Create a pricing policy — the declared bounds + Level-0 excluded-attributes list PPRs are conformance-checked against.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `pricevice.policies.create`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/pricevice.policy.add`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "label": "SaaS list-price band 2026",
  "floorMinor": 90000,
  "ceilingMinor": 150000,
  "currency": "USD",
  "excludedAttributes": [
    "nationality",
    "gender"
  ]
}
// → output
{
  "policy": {
    "policyId": "01J9X4P9R7Z2C1A1F2A8VBJYP1",
    "workspaceId": "ws_DEMODEFAULT0000000000",
    "label": "SaaS list-price band 2026",
    "version": 1,
    "floorMinor": 90000,
    "ceilingMinor": 150000,
    "currency": "USD",
    "excludedAttributes": [
      "nationality",
      "gender"
    ],
    "isActive": true,
    "createdAt": "2026-06-10T12:00:00.000Z"
  }
}
// note: Create a policy.
```

##### `pricevice.policy.list`

- **Summary**: List pricing policies in a workspace.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `pricevice.policies.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/pricevice.policy.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "policies": [],
  "nextCursor": null
}
// note: List policies.
```

##### `pricevice.policy.get`

- **Summary**: Get one pricing policy.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `pricevice.policies.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/pricevice.policy.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "policyId": "01J9X4P9R7Z2C1A1F2A8VBJYP1"
}
// → output
{
  "policyId": "01J9X4P9R7Z2C1A1F2A8VBJYP1",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "label": "SaaS list-price band 2026",
  "version": 1,
  "floorMinor": 90000,
  "ceilingMinor": 150000,
  "currency": "USD",
  "excludedAttributes": [],
  "isActive": true,
  "createdAt": "2026-06-10T12:00:00.000Z"
}
// note: Read a policy.
```

##### `pricevice.policy.update`

- **Summary**: Update a pricing policy (bumps the version; receipts pin the version they were checked against — history never rewrites).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `pricevice.policies.edit`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/pricevice.policy.update`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "policyId": "01J9X4P9R7Z2C1A1F2A8VBJYP1",
  "ceilingMinor": 160000
}
// → output
{
  "policyId": "01J9X4P9R7Z2C1A1F2A8VBJYP1",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "label": "SaaS list-price band 2026",
  "version": 2,
  "floorMinor": 90000,
  "ceilingMinor": 160000,
  "currency": "USD",
  "excludedAttributes": [],
  "isActive": true,
  "createdAt": "2026-06-10T12:00:00.000Z"
}
// note: Update a policy.
```

##### `pricevice.policy.remove`

- **Summary**: Deactivate a pricing policy (soft — issued receipts keep their pinned policy version).
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `pricevice.policies.delete`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/pricevice.policy.remove`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "policyId": "01J9X4P9R7Z2C1A1F2A8VBJYP1"
}
// → output
{
  "deactivated": true
}
// note: Deactivate a policy.
```

##### `pricevice.integrity.summary`

- **Summary**: Get the Keystone pricing-integrity summary — totals by conformance verdict + the recent off-policy receipts with proof attached.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `pricevice.integrity.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/pricevice.integrity.summary`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "totals": {
    "receipts": 1240,
    "withinBounds": 1180,
    "offPolicy": 12,
    "unchecked": 48
  },
  "recentOffPolicy": [],
  "byDomain": {
    "saas": 900,
    "services": 340
  }
}
// note: Read the integrity summary.
```

##### `pricevice.disclosure.generate`

- **Summary**: Generate the Aegis personalized-pricing disclosure for a PPR (deterministic from the receipt facts; states exactly what is proven and what is not).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `pricevice.disclosures.generate`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/pricevice.disclosure.generate`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "receiptId": "01J9X4P9R7Z2C1A1F2A8VBJYV9",
  "regime": "eu_omnibus"
}
// → output
{
  "receiptId": "01J9X4P9R7Z2C1A1F2A8VBJYV9",
  "regime": "eu_omnibus",
  "disclosureText": "This price was determined …",
  "generatedAt": "2026-06-10T12:00:00.000Z"
}
// note: Generate a disclosure.
```

### `paradigm` (36 actions)

Paradigm behavioral truth layer — Idiom mediation sessions, Temperament cards + calling strategies, Overture consent-first initiations, Rapport affect scores, Counterfact counterfactual queries, Breaker halt signals + pre-flight checks, Umbra negative-space documents + input checks, Survey empirical API maps.

##### `paradigm.idiom.session.open`

- **Summary**: Open an Idiom mediation session with a counterparty agent (inline requires dual consent; annotation/advisory work single-sided).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `paradigm.idiom.sessions`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.idiom.session.open`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "counterpartyRef": "agent:acme-procurement",
  "mode": "advisory",
  "exchangeType": "negotiation"
}
// → output
{
  "sessionId": "01J9X4P9R7Z2C1A1F2A8VBJYS1",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "mode": "advisory",
  "exchangeType": "negotiation",
  "counterpartyRef": "agent:acme-procurement",
  "status": "active",
  "createdAt": "2026-06-10T12:00:00.000Z"
}
// note: Open an advisory session.
```

##### `paradigm.idiom.message.mediate`

- **Summary**: Submit a message to an Idiom session for mediation/annotation. Substance is never altered; an unverified rendering is never released (fallback = annotated verbatim).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `paradigm.idiom.sessions`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.idiom.message.mediate`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "sessionId": "01J9X4P9R7Z2C1A1F2A8VBJYS1",
  "direction": "inbound",
  "message": "We are not in a position to accept these terms."
}
// → output
{
  "messageId": "01J9X4P9R7Z2C1A1F2A8VBJYM1",
  "direction": "inbound",
  "verbatimOriginal": "We are not in a position to accept these terms.",
  "rendering": null,
  "verificationResult": "fallback_annotation",
  "annotations": [
    "Directness is register-typical for this counterparty frame — read as position, not hostility."
  ],
  "chainHash": "…"
}
// note: Mediate an inbound message.
```

##### `paradigm.idiom.advisory.analyze`

- **Summary**: Advisory (single-side) analysis of a counterparty message: frame features, misread warnings, what it actually signals.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `paradigm.idiom.advisory`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.idiom.advisory.analyze`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "message": "No. The price is the price."
}
// → output
{
  "frameFeatures": {
    "directness": 0.95,
    "hedging": 0.05
  },
  "annotations": [
    "High-directness frame."
  ],
  "misreadWarnings": [
    "Bluntness here is frame-derived; do not read as bad faith."
  ]
}
// note: Analyze a counterparty message.
```

##### `paradigm.idiom.profile.declare`

- **Summary**: Declare your own agent's frame profile (recorded alongside inferred profiles; declared-vs-inferred divergence is itself a signal).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `paradigm.idiom.advisory`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.idiom.profile.declare`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "agentRef": "agent:our-negotiator",
  "dimensions": {
    "directness": 0.4,
    "hedging": 0.7
  }
}
// → output
{
  "profileId": "01J9X4P9R7Z2C1A1F2A8VBJYF1",
  "agentRef": "agent:our-negotiator",
  "level": "declared",
  "version": 1
}
// note: Declare a frame profile.
```

##### `paradigm.idiom.transcript.get`

- **Summary**: Get a session's signed, hash-chained mediation transcript (verbatim originals paired with renderings and annotations).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `paradigm.idiom.sessions`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.idiom.transcript.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "sessionId": "01J9X4P9R7Z2C1A1F2A8VBJYS1"
}
// → output
{
  "sessionId": "01J9X4P9R7Z2C1A1F2A8VBJYS1",
  "messages": []
}
// note: Read a transcript.
```

##### `paradigm.temperament.card.publish`

- **Summary**: Author and publish a temperament card for an API (validated for semantic consistency; publishes as provider_declared — verification upgrades evidence, never the publisher).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `paradigm.temperament.publish`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.temperament.card.publish`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "apiRef": "api.example.com/v2",
  "scope": "whole_api",
  "sections": {
    "ambiguity": {
      "malformed_date": "reject"
    },
    "retry": {
      "reads": "guaranteed",
      "writes": "designed_but_unverified"
    },
    "errorStyle": {
      "verbosity": "structured"
    },
    "determinism": {
      "class": "deterministic"
    },
    "freshness": {},
    "degradation": {},
    "change": {}
  }
}
// → output
{
  "cardId": "01J9X4P9R7Z2C1A1F2A8VBJYC1",
  "apiRef": "api.example.com/v2",
  "status": "published",
  "sections": {},
  "evidence": {},
  "version": 1
}
// note: Publish a card.
```

##### `paradigm.temperament.card.get`

- **Summary**: Get a temperament card (published cards are public registry reads; 'no card published' is itself a queryable state).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `paradigm.temperament.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.temperament.card.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "apiRef": "api.example.com/v2"
}
// → output
{
  "cardId": "01J9X4P9R7Z2C1A1F2A8VBJYC1",
  "apiRef": "api.example.com/v2",
  "status": "published",
  "sections": {},
  "evidence": {},
  "version": 1
}
// note: Read a card by API ref.
```

##### `paradigm.temperament.search`

- **Summary**: Search the temperament-card registry by API ref and behavioral filters (determinism class, status).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `paradigm.temperament.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.temperament.search`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "determinism": "deterministic"
}
// → output
{
  "cards": [],
  "nextCursor": null
}
// note: Search cards.
```

##### `paradigm.temperament.strategy.get`

- **Summary**: Get the compiled calling-strategy directives for a card (retry policy, input strictness, response interpretation, degradation expectation) — unverified cards carry lower trust weights.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `paradigm.temperament.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.temperament.strategy.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "cardId": "01J9X4P9R7Z2C1A1F2A8VBJYC1"
}
// → output
{
  "cardId": "01J9X4P9R7Z2C1A1F2A8VBJYC1",
  "apiRef": "api.example.com/v2",
  "directives": {},
  "compilerVersion": "strategy-c1",
  "trustWeight": 0.5
}
// note: Compile a calling strategy.
```

##### `paradigm.overture.offer.publish`

- **Summary**: Publish an Overture initiation offer (a typed declaration of what you may proactively tell subscribers — delivery still requires their consent).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `paradigm.overture.provider`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.overture.offer.publish`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "type": "risk_warning",
  "label": "Chargeback pattern forming",
  "subjectScope": "subscriber payment telemetry",
  "frequencyBandPerDay": 5
}
// → output
{
  "offerId": "01J9X4P9R7Z2C1A1F2A8VBJY01",
  "type": "risk_warning",
  "label": "Chargeback pattern forming",
  "status": "active"
}
// note: Publish an offer.
```

##### `paradigm.overture.subscribe`

- **Summary**: Subscribe to an initiation offer with consent rules (value threshold, frequency caps, quiet hours). Mints a signed consent receipt.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `paradigm.overture.subscribe`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.overture.subscribe`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "offerId": "01J9X4P9R7Z2C1A1F2A8VBJY01",
  "minPredictedValue": 0.5
}
// → output
{
  "subscriptionId": "01J9X4P9R7Z2C1A1F2A8VBJYU1",
  "offerId": "01J9X4P9R7Z2C1A1F2A8VBJY01",
  "consentReceipt": "…",
  "status": "active"
}
// note: Subscribe with rules.
```

##### `paradigm.overture.initiate`

- **Summary**: Submit an initiation for delivery to subscribers. Consent-first: subscribers without an active subscription are never reached; each delivery is value-predicted against the attention budget.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `paradigm.overture.provider`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.overture.initiate`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "offerId": "01J9X4P9R7Z2C1A1F2A8VBJY01",
  "payload": {
    "pattern": "chargeback_spike",
    "confidence": 0.83
  },
  "urgency": 0.8
}
// → output
{
  "initiationId": "01J9X4P9R7Z2C1A1F2A8VBJYI1",
  "decisions": []
}
// note: Initiate to subscribers.
```

##### `paradigm.overture.inbox.list`

- **Summary**: Read the initiation inbox — delivered initiations with predicted-value disclosure and feedback affordances.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `paradigm.overture.subscribe`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.overture.inbox.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "deliveries": [],
  "nextCursor": null
}
// note: Read the inbox.
```

##### `paradigm.overture.feedback`

- **Summary**: Rate a delivered initiation (useful / not useful / harmful) — the value loop that earns or costs the provider future attention.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `paradigm.overture.subscribe`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.overture.feedback`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "deliveryId": "01J9X4P9R7Z2C1A1F2A8VBJYD1",
  "rating": "useful"
}
// → output
{
  "recorded": true
}
// note: Close the value loop.
```

##### `paradigm.rapport.events.ingest`

- **Summary**: Contribute consented agent-interaction telemetry (calls, retries, doc fetches, abandonment markers). Requires an active consent grant; identity is stripped at the edge.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `paradigm.rapport.contribute`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.rapport.events.ingest`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "grantId": "01J9X4P9R7Z2C1A1F2A8VBJYG1",
  "events": [
    {
      "apiRef": "api.example.com/v2",
      "eventType": "call",
      "outcome": "success",
      "parameterDelta": false
    }
  ]
}
// → output
{
  "accepted": 1,
  "rejected": 0
}
// note: Contribute telemetry.
```

##### `paradigm.rapport.score.get`

- **Summary**: Get the public Rapport Score for an API (k-floored: under-floor APIs honestly return 'insufficient_data', never a weak number).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.rapport.score.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "apiRef": "api.example.com/v2"
}
// → output
{
  "apiRef": "api.example.com/v2",
  "score": null,
  "methodologyVersion": "rapport-m1",
  "publicationStatus": "insufficient_data"
}
// note: Read a public score.
```

##### `paradigm.rapport.analytics.get`

- **Summary**: Provider analytics for your own API: metric cells + attribution findings ranked by impact (which endpoint/error/pattern drives confusion or abandonment).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `paradigm.rapport.analytics`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.rapport.analytics.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "apiRef": "api.example.com/v2"
}
// → output
{
  "cells": [],
  "attribution": []
}
// note: Read provider analytics.
```

##### `paradigm.counterfact.feasibility.check`

- **Summary**: Check what substrate modes are available for a counterfactual query before running it (which mode, what confidence ceiling, what gaps, whether it would be refused).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `paradigm.counterfact.run`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.counterfact.feasibility.check`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "apiRef": "api.example.com/v2",
  "anchorTraceIds": [
    "01J9X4P9R7Z2C1A1F2A8VBJYT1"
  ],
  "interventionType": "no_call"
}
// → output
{
  "availableModes": [
    "recorded_reconstruction"
  ],
  "selectedMode": "recorded_reconstruction",
  "confidenceCeiling": "reconstruction_complete",
  "gapSummary": [],
  "wouldRefuse": false
}
// note: Check feasibility.
```

##### `paradigm.counterfact.query.run`

- **Summary**: Run a counterfactual query against recorded interaction state. Every result carries its mode + confidence grade; un-answerable classes are refused with a structured explanation, never guessed.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `paradigm.counterfact.run`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.counterfact.query.run`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "apiRef": "api.example.com/v2",
  "anchorTraceIds": [
    "01J9X4P9R7Z2C1A1F2A8VBJYT1"
  ],
  "interventionType": "no_call"
}
// → output
{
  "queryId": "01J9X4P9R7Z2C1A1F2A8VBJYQ1",
  "status": "evaluated",
  "result": {},
  "refusal": null
}
// note: Run a counterfactual.
```

##### `paradigm.counterfact.record.get`

- **Summary**: Get the sealed, hash-chained evidentiary record for an evaluated counterfactual (citable in audits and disputes).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `paradigm.counterfact.run`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.counterfact.record.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "queryId": "01J9X4P9R7Z2C1A1F2A8VBJYQ1"
}
// → output
{
  "record": {}
}
// note: Read a sealed record.
```

##### `paradigm.breaker.signal.list`

- **Summary**: Read the public halt-signal log (active and historical) — append-only, complete, offline-verifiable. Public; cannot be disabled.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.breaker.signal.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "status": "active"
}
// → output
{
  "signals": [],
  "nextCursor": null
}
// note: Read the public signal log.
```

##### `paradigm.breaker.check.action`

- **Summary**: Pre-flight halt check: does any active signal's scope match this action descriptor? Returns matched signals + the strictest severity. Absent any signal, the answer is 'proceed' — the system halts on authenticated signal, never on silence.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.breaker.check.action`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "actionClass": "agent_financial_transactions",
  "domain": "payments"
}
// → output
{
  "halted": false,
  "severity": null,
  "matchedSignals": []
}
// note: Pre-flight check.
```

##### `paradigm.breaker.signal.issue`

- **Summary**: Issue a halt signal (provider-class: your own registered surface only; duration is capped by the issuer-class ceiling and every signal expires — unconditionally).
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `paradigm.breaker.issue`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.breaker.signal.issue`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "actionClasses": [
    "agent_purchases"
  ],
  "domains": [
    "api.example.com/v2"
  ],
  "qualifiers": [],
  "severity": "soft_halt",
  "basis": "Correlated mis-execution pattern across fleet; pausing pending review.",
  "durationMinutes": 90,
  "drill": false
}
// → output
{
  "signalId": "01J9X4P9R7Z2C1A1F2A8VBJYH1",
  "issuerClass": "provider",
  "scope": {
    "actionClasses": [
      "agent_purchases"
    ],
    "domains": [
      "api.example.com/v2"
    ],
    "jurisdictions": [],
    "qualifiers": []
  },
  "severity": "soft_halt",
  "drill": false,
  "issuedAt": "2026-06-10T12:00:00.000Z",
  "expiresAt": "2026-06-10T13:30:00.000Z",
  "status": "active"
}
// note: Issue a scoped halt.
```

##### `paradigm.breaker.point.register`

- **Summary**: Register an enforcement point (gateway, runtime or MCP server) that will acknowledge and enforce breaker signals for this workspace.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `paradigm.breaker.enforce`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.breaker.point.register`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "type": "gateway",
  "label": "EU edge gateway",
  "registeredSurface": [
    "api.example.com/v2"
  ],
  "drillParticipation": true
}
// → output
{
  "point": {
    "pointId": "01J9X4P9R7Z2C1A1F2A8VBJYP1",
    "workspaceId": "ws_DEMODEFAULT0000000000",
    "type": "gateway",
    "label": "EU edge gateway",
    "registeredSurface": [
      "api.example.com/v2"
    ],
    "drillParticipation": true,
    "createdAt": "2026-09-02T12:00:00.000Z"
  }
}
// note: Register an enforcement point.
```

##### `paradigm.breaker.point.list`

- **Summary**: List this workspace's registered enforcement points — which surfaces are wired to honour breaker signals.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `paradigm.breaker.enforce`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.breaker.point.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "points": []
}
// note: List enforcement points.
```

##### `paradigm.breaker.acknowledge`

- **Summary**: Report an enforcement point's state for a signal (acknowledged / enforcing / declared non-compliant) — coverage visibility is part of the protocol.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `paradigm.breaker.enforce`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.breaker.acknowledge`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "signalId": "01J9X4P9R7Z2C1A1F2A8VBJYH1",
  "pointId": "01J9X4P9R7Z2C1A1F2A8VBJYP1",
  "state": "enforcing"
}
// → output
{
  "recorded": true
}
// note: Acknowledge enforcement.
```

##### `paradigm.breaker.proposal.open`

- **Summary**: Open a community-class halt proposal (draft signal + evidence) for the affected operator constituency to vote on — advisories never bypass the vote.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `paradigm.breaker.vote`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.breaker.proposal.open`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "draftSignal": {
    "actionClasses": [
      "autonomous_writes"
    ],
    "domains": [
      "api.example.com"
    ]
  },
  "evidence": [
    "Synchronized retry storm observed across 40 fleets."
  ],
  "ballotMinutes": 60
}
// → output
{
  "proposalId": "01J9X4P9R7Z2C1A1F2A8VBJYR1",
  "status": "open",
  "ballotClosesAt": "2026-06-10T13:00:00.000Z"
}
// note: Open a community proposal.
```

##### `paradigm.umbra.document.publish`

- **Summary**: Author and publish an Umbra negative-space document. Vague entries are structurally rejected (triggers + failure signature required; silent-failure entries require detection guidance).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `paradigm.umbra.publish`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.umbra.document.publish`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "apiRef": "api.example.com/v2",
  "versionRange": ">=2.0 <3.0",
  "coverageStatement": "Input classes and call-order couplings examined by the provider team; no probe pass yet.",
  "entries": [
    {
      "type": "silent_failure",
      "specification": "Batch update reports 200 OK while skipping rows over 1MB.",
      "triggers": "POST /batch with any row > 1MB",
      "failureSignature": "partial_effect",
      "severity": "silent_hazardous",
      "detectionGuidance": "Re-read affected rows after batch write and compare row counts."
    }
  ]
}
// → output
{
  "documentId": "01J9X4P9R7Z2C1A1F2A8VBJYW1",
  "apiRef": "api.example.com/v2",
  "status": "published",
  "entryCount": 1
}
// note: Publish negative space.
```

##### `paradigm.umbra.document.get`

- **Summary**: Get an API's published Umbra document with entries (published documents are public registry reads; every document carries its coverage statement).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `paradigm.umbra.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.umbra.document.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "apiRef": "api.example.com/v2"
}
// → output
{
  "document": {},
  "entries": []
}
// note: Read a document.
```

##### `paradigm.umbra.input.check`

- **Summary**: Pre-call check of an input descriptor against an API's known-unhandled classes — plan around documented failure modes instead of colliding with them.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `paradigm.umbra.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.umbra.input.check`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "apiRef": "api.example.com/v2",
  "operation": "POST /batch",
  "inputDescriptor": "rows up to 2MB"
}
// → output
{
  "matches": [],
  "hazardous": false,
  "coverageStatement": "No published document covers this operation — absence of an entry is not absence of a limitation."
}
// note: Check an input pre-call.
```

##### `paradigm.umbra.guards.get`

- **Summary**: Get the compiled integration checks + runtime guards for an Umbra document (effect-verification wrappers for silent failures, input pre-validators, cliff-aware batching).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `paradigm.umbra.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.umbra.guards.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "documentId": "01J9X4P9R7Z2C1A1F2A8VBJYW1"
}
// → output
{
  "integrationChecks": [],
  "runtimeGuards": [],
  "compilerVersion": "guards-c1"
}
// note: Compile guards.
```

##### `paradigm.survey.recommend`

- **Summary**: For task T under constraints C at step S: the ecosystem's revealed preference — usage shares, quality differentials, behavioral annotations, and a mandatory coverage statement. 'More used' is distinguished from 'measurably better'.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `paradigm.survey.query`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.survey.recommend`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "task": "data_extraction",
  "stepRole": "document_parse",
  "constraintProfile": "accuracy_sensitive"
}
// → output
{
  "ranked": [],
  "floorStatus": "insufficient_data",
  "coverageStatement": "Below the contributor floor for this cell — contribute telemetry to deepen the map."
}
// note: Ask the map.
```

##### `paradigm.survey.map.get`

- **Summary**: Read a usage-map cell (per task node and step role): API usage shares with quality differentials, k-floored, with skew flags and the coverage statement.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `paradigm.survey.query`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.survey.map.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "task": "research"
}
// → output
{
  "cells": [],
  "coverageStatement": "…"
}
// note: Browse the map.
```

##### `paradigm.survey.events.contribute`

- **Summary**: Contribute consented task-telemetry events (task context, call sequence roles, outcome markers). Contributors see deeper into the maps their data builds.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `paradigm.survey.contribute`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.survey.events.contribute`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "grantId": "01J9X4P9R7Z2C1A1F2A8VBJYG1",
  "events": [
    {
      "task": "research",
      "stepRole": "web_search",
      "apiRef": "api.example.com/v2",
      "sequencePosition": 0,
      "outcome": "completed",
      "qualitySignal": 0.9
    }
  ]
}
// → output
{
  "accepted": 1,
  "rejected": 0
}
// note: Contribute task telemetry.
```

##### `paradigm.consent.grant`

- **Summary**: Create a Paradigm consent grant (scoped by modules + data class + granularity) — the precondition for ANY telemetry consumption. Mints a signed consent receipt.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `paradigm.consent.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.consent.grant`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "products": [
    "rapport",
    "survey"
  ],
  "dataClass": "interaction_events",
  "granularity": "aggregate_only"
}
// → output
{
  "grantId": "01J9X4P9R7Z2C1A1F2A8VBJYG1",
  "receipt": "…",
  "status": "active"
}
// note: Grant consent.
```

##### `paradigm.consent.revoke`

- **Summary**: Revoke a consent grant — unaggregated contributed events are purged and the contributor is excluded from future cells.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `paradigm.consent.manage`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/paradigm.consent.revoke`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "grantId": "01J9X4P9R7Z2C1A1F2A8VBJYG1"
}
// → output
{
  "revoked": true,
  "purgedEvents": 412
}
// note: Revoke + purge.
```

### `driftvice` (16 actions)

Driftvice semantic drift detection — connect surfaces where company language lives (BYO), resolve a term/metric to its canonical definition with governance + drift status, check a definition or computation against canon, search the derived glossary, query the drift feed, resolve drift (declare canon / merge / split / accept), read coherence, and issue or verify signed canon attestations.

##### `driftvice.surface.connect`

- **Summary**: Connect a surface where company language lives (BYO credentials) — the metered unit. Driftvice reads it with the access you scope.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `driftvice.surfaces.connect`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/driftvice.surface.connect`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "class": "bi_semantic_layer",
  "label": "Looker — growth project",
  "connectionRef": "conn_looker_001",
  "scope": [
    "growth"
  ],
  "syncSchedule": "daily"
}
// → output
{
  "surfaceId": "01J9X4P9R7Z2C1A1F2A8VBJYS1",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "class": "bi_semantic_layer",
  "label": "Looker — growth project",
  "scope": [
    "growth"
  ],
  "writeBackCapable": true,
  "syncState": "never",
  "lastSyncAt": null
}
// note: Connect a BI surface.
```

##### `driftvice.surface.list`

- **Summary**: List the connected surfaces in a workspace with their sync health.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `driftvice.surfaces.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/driftvice.surface.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "surfaces": [],
  "nextCursor": null
}
// note: List surfaces.
```

##### `driftvice.surface.sync`

- **Summary**: Trigger an incremental re-sync + re-extraction of a connected surface.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `driftvice.surfaces.edit`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/driftvice.surface.sync`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "surfaceId": "01J9X4P9R7Z2C1A1F2A8VBJYS1"
}
// → output
{
  "surfaceId": "01J9X4P9R7Z2C1A1F2A8VBJYS1",
  "syncState": "syncing",
  "queuedAt": "2026-06-14T12:00:00.000Z"
}
// note: Re-sync a surface.
```

##### `driftvice.surface.revoke`

- **Summary**: Revoke a connected surface — purges its derived usages per the platform's data-handling terms.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `driftvice.surfaces.revoke`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/driftvice.surface.revoke`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "surfaceId": "01J9X4P9R7Z2C1A1F2A8VBJYS1"
}
// → output
{
  "revoked": true,
  "usagesPurged": 412
}
// note: Revoke + purge.
```

##### `driftvice.glossary.search`

- **Summary**: Semantic search over the DERIVED glossary — a projection of the live language graph, never an authored document.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `driftvice.glossary.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/driftvice.glossary.search`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "query": "active user"
}
// → output
{
  "entries": [],
  "nextCursor": null
}
// note: Search the glossary.
```

##### `driftvice.term.resolve`

- **Summary**: Resolve a term to its canonical definition, approved aliases, and scope rules — with governance + drift status, so an agent knows settled vs drifting before it acts.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `driftvice.glossary.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/driftvice.term.resolve`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "term": "active user"
}
// → output
{
  "resolved": false,
  "canon": null
}
// note: Resolve a term to canon.
```

##### `driftvice.metric.definition`

- **Summary**: Return a metric's canonical computation (normalized + renderings) and whether surfaces currently diverge from it.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `driftvice.glossary.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/driftvice.metric.definition`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "metric": "MRR"
}
// → output
{
  "conceptId": null,
  "canonicalComputation": null,
  "divergingSurfaceCount": 0
}
// note: Get a metric's canon computation.
```

##### `driftvice.term.check`

- **Summary**: Check a definition or computation an agent is about to use against canon — report conformance or the specific drift.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `driftvice.glossary.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/driftvice.term.check`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "term": "active user",
  "definition": "logged in within 30 days"
}
// → output
{
  "conforms": true,
  "driftType": null,
  "explanation": "Matches canon (30-day window, excludes internal accounts)."
}
// note: Check a definition against canon.
```

##### `driftvice.canon.status`

- **Summary**: Get a concept's governance state, owner, coherence, and any linked decisions.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `driftvice.canon.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/driftvice.canon.status`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "conceptId": "01J9X4P9R7Z2C1A1F2A8VBJYC1"
}
// → output
{
  "conceptId": "01J9X4P9R7Z2C1A1F2A8VBJYC1",
  "state": "canonical",
  "ownerRef": "team:growth",
  "openDriftCount": 0,
  "linkedDecisions": [
    "Q3 board deck"
  ]
}
// note: Read canon status.
```

##### `driftvice.drift.list`

- **Summary**: Query the open drift feed — filter by type, severity, surface, domain, owner, or state.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `driftvice.drift.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/driftvice.drift.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "severity": "high"
}
// → output
{
  "drift": [],
  "nextCursor": null
}
// note: List open drift.
```

##### `driftvice.drift.resolve`

- **Summary**: Resolve a drift via an owner decision: declare canon, merge/split concepts, approve/deprecate an alias, adjust scope, or accept the divergence with rationale.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `driftvice.drift.resolve`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/driftvice.drift.resolve`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "driftId": "01J9X4P9R7Z2C1A1F2A8VBJYD1",
  "action": "declare_canon",
  "decisionPayload": {
    "canonicalName": "active user",
    "authoritativeDefinition": "logged in within 30 days, excluding internal accounts"
  }
}
// → output
{
  "reconciliationId": "01J9X4P9R7Z2C1A1F2A8VBJYR1",
  "driftId": "01J9X4P9R7Z2C1A1F2A8VBJYD1",
  "propagationState": "pending"
}
// note: Resolve drift by declaring canon.
```

##### `driftvice.canon.declare`

- **Summary**: Declare canon for a concept — the authoritative definition, approved aliases, scope rules, and (for metrics) the canonical computation. Anchored to the deriving usages.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `driftvice.canon.declare`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/driftvice.canon.declare`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "conceptId": "01J9X4P9R7Z2C1A1F2A8VBJYC1",
  "canonicalName": "active user",
  "authoritativeDefinition": "logged in within 30 days, excluding internal accounts",
  "tier": 1
}
// → output
{
  "canonId": "01J9X4P9R7Z2C1A1F2A8VBJYK1",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "conceptId": "01J9X4P9R7Z2C1A1F2A8VBJYC1",
  "canonicalName": "active user",
  "authoritativeDefinition": "logged in within 30 days, excluding internal accounts",
  "approvedAliases": [],
  "scopeRules": {
    "inclusion": [],
    "exclusion": [
      "internal accounts"
    ]
  },
  "tier": 1,
  "governanceState": "canonical",
  "version": 1,
  "driftStatus": "settled"
}
// note: Declare canon.
```

##### `driftvice.coherence.summary`

- **Summary**: Get language-coherence scores per surface, per domain, and company-wide, with trends — plus ungoverned heavy-usage terms awaiting governance.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `driftvice.glossary.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/driftvice.coherence.summary`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "scope": "company"
}
// → output
{
  "scores": [
    {
      "scope": "company",
      "scopeRef": null,
      "score": 78,
      "trend": "improving"
    }
  ],
  "ungovernedTopTerms": []
}
// note: Read coherence.
```

##### `driftvice.canon.attest`

- **Summary**: Issue a signed canon attestation — a verifiable snapshot of a canonical definition + governance + drift status at this time, so the ground-truth answer can be proven authentic.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `driftvice.canon.attest`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/driftvice.canon.attest`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "canonId": "01J9X4P9R7Z2C1A1F2A8VBJYK1"
}
// → output
{
  "version": "1",
  "attestationId": "01J9X4P9R7Z2C1A1F2A8VBJYA1",
  "type": "canon.attest",
  "issuedAt": "2026-06-14T12:00:00.000Z",
  "signature": "...",
  "signatureKeyId": "driftvice-2026-q2-enam",
  "body": {}
}
// note: Issue a canon attestation.
```

##### `driftvice.canon.verify`

- **Summary**: Verify a canon attestation's Ed25519 signature against the published Driftvice public keys. Public — no account required. Cannot be disabled.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/driftvice.canon.verify`

**Example**:

```jsonc
// input
{
  "attestation": {
    "version": "1",
    "attestationId": "01J9X4P9R7Z2C1A1F2A8VBJYA1",
    "type": "canon.attest",
    "issuedAt": "2026-06-14T12:00:00.000Z",
    "signature": "...",
    "signatureKeyId": "driftvice-2026-q2-enam",
    "body": {}
  }
}
// → output
{
  "ok": true,
  "signedAt": "2026-08-01T12:00:00.000Z",
  "signatureKeyId": "dKeyExampleBase64UrlAA",
  "signerDid": "did:web:trustvice.com",
  "artifact": "canon_attestation",
  "publishedKeyUrl": "https://api.trustvice.com/.well-known/driftvice-keys.json"
}
// note: Verify a canon attestation.
```

##### `driftvice.canon.guard`

- **Summary**: Before acting on a concept, ask whether its live definition has drifted from canon far enough to warn or block. Blocking is deliberately hard to reach.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `driftvice.canon.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/driftvice.canon.guard`

**Example**:

```jsonc
// input
{
  "conceptId": "revenue"
}
// → output
{
  "verdict": {
    "conceptId": "revenue",
    "disposition": "warn",
    "state": "conformant",
    "measured": 12,
    "diverging": 2,
    "divergenceRate": 0.1667,
    "computationDiverging": 0,
    "computationRate": 0,
    "citedUsages": []
  },
  "reportOnly": false,
  "notes": [
    "2 of 12 live usages diverge from canon; none diverge in computation, so this warns and does not block."
  ]
}
// note: A guard that halts real work daily is a guard people disable.
```

### `fabric` (8 actions)

Connector Fabric — the platform-wide ingestion layer. Connect any of the 128 catalog sources (code / docs / warehouse / BI / analytics / CRM / comms / …) once, then query extracted records by kind across all sources and all products, and introspect the subscription matrix (which product consumes which record kinds).

##### `fabric.retrieve.signed`

- **Summary**: Query extracted records AND get a signed-retrieval receipt source built from exactly the rows returned — so a downstream claim can prove what grounded it.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `fabric.records.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/fabric.retrieve.signed`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "kinds": [
    "policy-clause"
  ]
}
// → output
{
  "records": [],
  "nextCursor": null,
  "mint": {
    "kind": "signed-retrieval",
    "source": {
      "retrievalRef": "ret_abc",
      "queryHash": "abc123",
      "retrievalMethod": "filter",
      "embeddingModel": null,
      "sources": [],
      "retrievedAt": "2026-09-04T00:00:00.000Z"
    }
  }
}
// note: Retrieve policy clauses and receive the receipt source for exactly those rows.
```

##### `fabric.sources.catalog`

- **Summary**: List the connectable source catalog (128 sources across 11 surface classes) with their auth method + emitted record kinds.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `fabric.connections.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/fabric.sources.catalog`

**Example**:

```jsonc
// input
{
  "surfaceClass": "warehouse"
}
// → output
{
  "sources": []
}
// note: Browse warehouse sources.
```

##### `fabric.connections.connect`

- **Summary**: Connect a catalog source (BYO credentials) into the fabric. The connection's records broadcast to every subscribing product.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `fabric.connections.connect`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/fabric.connections.connect`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "sourceId": "github",
  "label": "acme/app",
  "scope": [
    "acme/app"
  ],
  "syncSchedule": "event"
}
// → output
{
  "connectionId": "01J9X4P9R7Z2C1A1F2A8VBJYS1",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "sourceId": "github",
  "surfaceClass": "codebase",
  "authMethod": "personal_access_token",
  "label": "acme/app",
  "scope": [
    "acme/app"
  ],
  "state": "pending",
  "syncState": "never",
  "emits": [
    "code-identifier",
    "doc-chunk"
  ],
  "lastSyncAt": null
}
// note: Connect GitHub.
```

##### `fabric.connections.list`

- **Summary**: List the workspace's fabric connections with their sync health.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `fabric.connections.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/fabric.connections.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "connections": [],
  "nextCursor": null
}
// note: List connections.
```

##### `fabric.connections.sync`

- **Summary**: Enqueue an on-demand sync + re-extraction of a fabric connection.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `fabric.connections.edit`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/fabric.connections.sync`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "connectionId": "01J9X4P9R7Z2C1A1F2A8VBJYS1"
}
// → output
{
  "enqueued": true,
  "connectionId": "01J9X4P9R7Z2C1A1F2A8VBJYS1"
}
// note: Sync now.
```

##### `fabric.connections.revoke`

- **Summary**: Revoke a fabric connection — purges its extracted records per the platform's data-handling terms.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `fabric.connections.revoke`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/fabric.connections.revoke`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "connectionId": "01J9X4P9R7Z2C1A1F2A8VBJYS1"
}
// → output
{
  "revoked": true,
  "recordsPurged": 1280
}
// note: Revoke + purge.
```

##### `fabric.records.query`

- **Summary**: Query extracted records by kind / source / subscriber — the universal read every product (and agent) uses to consume the fabric.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `fabric.records.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/fabric.records.query`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "kinds": [
    "policy-clause"
  ]
}
// → output
{
  "records": [],
  "nextCursor": null
}
// note: Read policy clauses across all sources.
```

##### `fabric.subscriptions.matrix`

- **Summary**: Return the fabric subscription matrix — which product consumes which record kinds, and how many products each kind powers.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `fabric.connections.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/fabric.subscriptions.matrix`

**Example**:

```jsonc
// input
{}
// → output
{
  "subscriptions": {},
  "kindReach": {}
}
// note: Introspect the matrix.
```

### `actionflow` (6 actions)

ActionFlow workflow engine — run flows, instantiate templates, inspect executions.

##### `actionflow.flows.list`

- **Summary**: List the workspace's ActionFlow flows.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/actionflow.flows.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "flows": [
    {
      "schemaVersion": "1.0",
      "id": "flow_incident",
      "workspaceId": "ws_example",
      "tenantId": "ws_example",
      "name": "Incident response",
      "description": "Page on-call, open a ticket, post to the channel.",
      "tags": [
        "incident"
      ],
      "source": {
        "kind": "customer_authored"
      },
      "triggers": [
        {
          "kind": "webhook",
          "id": "trg_1"
        }
      ],
      "steps": [
        {
          "id": "page",
          "kind": "http"
        }
      ],
      "version": {
        "semver": "1.0.0",
        "status": "published",
        "publishedAt": "2026-08-01T09:00:00.000Z"
      },
      "authoredBy": "acct_1"
    }
  ]
}
// note: List flows.
```

##### `actionflow.flows.run`

- **Summary**: Run a flow — trigger an execution through the bounded graph engine.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/actionflow.flows.run`

**Example**:

```jsonc
// input
{
  "id": "flow_incident",
  "input": {
    "severity": "high"
  }
}
// → output
{
  "execution": {
    "executionId": "exe_01M1F0000000000000000001",
    "flowId": "flow_incident",
    "flowVersion": "1.0.0",
    "workspaceId": "ws_example",
    "initiatedBy": {
      "kind": "agent",
      "agentId": "did:web:example.com:agent:ops"
    },
    "triggeredBy": {
      "kind": "api"
    },
    "status": "running",
    "stepStates": {
      "page": {
        "status": "succeeded",
        "completedAt": "2026-08-01T09:00:02.000Z"
      }
    }
  }
}
// note: Run the incident flow.
```

##### `actionflow.flows.publish`

- **Summary**: Publish a flow (make the current draft the live version).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/actionflow.flows.publish`

**Example**:

```jsonc
// input
{
  "id": "flow_incident"
}
// → output
{
  "flow": {
    "schemaVersion": "1.0",
    "id": "flow_incident",
    "workspaceId": "ws_example",
    "tenantId": "ws_example",
    "name": "Incident response",
    "description": "Page on-call, open a ticket, post to the channel.",
    "tags": [
      "incident"
    ],
    "source": {
      "kind": "customer_authored"
    },
    "triggers": [
      {
        "kind": "webhook",
        "id": "trg_1"
      }
    ],
    "steps": [
      {
        "id": "page",
        "kind": "http"
      }
    ],
    "version": {
      "semver": "1.0.0",
      "status": "published",
      "publishedAt": "2026-08-01T09:00:00.000Z"
    },
    "authoredBy": "acct_1"
  }
}
// note: Publish a flow.
```

##### `actionflow.templates.list`

- **Summary**: List the ActionFlow starter templates.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/actionflow.templates.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "templates": [
    {
      "id": "tmpl_incident_alert",
      "name": "Incident alert",
      "description": "Page on-call and open a ticket when an alert fires.",
      "tags": [
        "incident",
        "alerting"
      ],
      "stepCount": 4,
      "triggerCount": 1
    }
  ]
}
// note: Browse templates.
```

##### `actionflow.templates.instantiate`

- **Summary**: Instantiate a template into a new draft flow in the workspace.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/actionflow.templates.instantiate`

**Example**:

```jsonc
// input
{
  "id": "tmpl_incident_alert",
  "name": "My incident flow"
}
// → output
{
  "flow": {
    "schemaVersion": "1.0",
    "id": "flow_01M1F0000000000000000002",
    "workspaceId": "ws_example",
    "tenantId": "ws_example",
    "name": "My incident flow",
    "description": "Page on-call and open a ticket when an alert fires.",
    "tags": [
      "incident",
      "alerting"
    ],
    "source": {
      "kind": "template",
      "templateId": "tmpl_incident_alert"
    },
    "triggers": [
      {
        "kind": "webhook",
        "id": "trg_1"
      }
    ],
    "steps": [
      {
        "id": "page",
        "kind": "http"
      }
    ],
    "version": {
      "semver": "0.1.0",
      "status": "draft"
    },
    "authoredBy": "acct_1"
  }
}
// note: Create a flow from a template.
```

##### `actionflow.executions.list`

- **Summary**: List recent ActionFlow executions.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/actionflow.executions.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "executions": [
    {
      "executionId": "exe_01M1F0000000000000000001",
      "flowId": "flow_incident",
      "flowVersion": "1.0.0",
      "workspaceId": "ws_example",
      "initiatedBy": {
        "kind": "agent",
        "agentId": "did:web:example.com:agent:ops"
      },
      "triggeredBy": {
        "kind": "api"
      },
      "status": "running",
      "stepStates": {
        "page": {
          "status": "succeeded",
          "completedAt": "2026-08-01T09:00:02.000Z"
        }
      }
    },
    {
      "executionId": "exe_01M1F0000000000000000002",
      "flowId": "flow_incident",
      "flowVersion": "1.0.0",
      "workspaceId": "ws_example",
      "initiatedBy": {
        "kind": "api"
      },
      "triggeredBy": {
        "kind": "webhook"
      },
      "status": "awaiting_human_review",
      "stepStates": {
        "approve": {
          "status": "succeeded",
          "result": {
            "awaitingReview": true,
            "allowedDecisions": [
              "approve",
              "reject"
            ]
          }
        }
      }
    }
  ]
}
// note: List executions.
```

### `lens` (4 actions)

Compliance-evidence lenses over the audit chain — list, validate, and execute (a signed evidence bundle; a paid action).

##### `lens.list`

- **Summary**: List the available compliance-evidence lenses.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/lens.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "lenses": [
    {
      "id": "lens_audit_activity",
      "name": "Audit Activity Summary",
      "version": "1.0.0",
      "description": "Counts and samples every audit-chain event in the window."
    }
  ]
}
// note: Browse lenses.
```

##### `lens.execute`

- **Summary**: Execute a lens over the audit chain — produces a signed compliance-evidence bundle (a paid action).
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/lens.execute`

**Example**:

```jsonc
// input
{
  "id": "lens_audit_activity",
  "params": {
    "since": "2026-01-01T00:00:00.000Z"
  }
}
// → output
{
  "ok": true,
  "resultId": "60e625a9-0cef-4e9f-ab6c-588e780a5a27",
  "signed": true,
  "bundle": {
    "lensId": "lens_audit_activity",
    "lensName": "Audit Activity Summary",
    "lensVersion": "1.0.0",
    "category": "operational",
    "contentHash": "fa439c11bed190031bc1479d087e5d201ace57d32f56b614133910ac1bdeec27",
    "executedAt": "2026-01-02T00:00:00.000Z",
    "rowsScanned": 128,
    "range": {
      "start": "2026-01-01T00:00:00.000Z",
      "end": "2026-01-02T00:00:00.000Z"
    },
    "sections": [],
    "source": "audit_chain",
    "workspaceId": "ws_example",
    "signature": {
      "alg": "EdDSA",
      "signingKeyId": "43IS9jyB9T6B2q53OQAGng",
      "value": "…"
    }
  }
}
// note: Run a SOC 2 lens.
```

##### `lens.validate`

- **Summary**: Validate a lens definition (dry-run; no evidence bundle, no charge).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/lens.validate`

**Example**:

```jsonc
// input
{
  "definition": {
    "framework": "soc2"
  }
}
// → output
{
  "ok": true
}
// note: Validate a lens.
```

##### `lens.results.list`

- **Summary**: List prior lens-execution results (the evidence-bundle history).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/lens.results.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "results": [
    {
      "id": "60e625a9-0cef-4e9f-ab6c-588e780a5a27",
      "lensId": "lens_audit_activity",
      "lensVersion": "1.0.0",
      "contentHash": "fa439c11bed190031bc1479d087e5d201ace57d32f56b614133910ac1bdeec27",
      "executedAt": "2026-01-02T00:00:00.000Z",
      "signed": true,
      "signingKeyId": "43IS9jyB9T6B2q53OQAGng",
      "status": "sealed"
    }
  ]
}
// note: List evidence bundles.
```

### `notarian` (3 actions)

Notarian signed snapshots + transparency-chain verification (a snapshot is a paid action).

##### `notarian.snapshot.create`

- **Summary**: Create a signed Notarian snapshot of the workspace's audit state (a paid action).
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/notarian.snapshot.create`

**Example**:

```jsonc
// input
{
  "scope": "month-end"
}
// → output
{
  "ok": true,
  "bundle": {
    "bundleId": "eb7f9624-1f91-45d9-a9a4-4f6adf0478ce",
    "workspaceId": "ws_example",
    "jurisdiction": "ENAM",
    "scope": "month-end",
    "rangeStart": "2026-01-01T00:00:00.000Z",
    "rangeEnd": "2026-01-31T23:59:59.999Z",
    "recordCount": 412,
    "merkleRoot": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "firstRecordId": "01M1F0000000000000000000A1",
    "lastRecordId": "01M1F0000000000000000000Z9",
    "snapshotAt": "2026-02-01T00:00:00.000Z",
    "records": [],
    "signingKeyId": "43IS9jyB9T6B2q53OQAGng",
    "ed25519Signature": "…"
  }
}
// note: Seal a signed snapshot.
```

##### `notarian.verify-chain`

- **Summary**: Verify the Notarian transparency chain (free — a transparency guarantee).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/notarian.verify-chain`

**Example**:

```jsonc
// input
{}
// → output
{
  "ok": true,
  "verification": {
    "ok": true,
    "workspaceId": "ws_example",
    "checkedCount": 412,
    "tipHash": "2a1865a1eb374e0590a5af631ad0999d7085075f7f1db581867a9be3574e1890"
  }
}
// note: Prove the chain is intact.
```

##### `notarian.anchors.list`

- **Summary**: List the Notarian anchors (the published chain checkpoints).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/notarian.anchors.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "anchors": [
    {
      "id": "eb7f9624-1f91-45d9-a9a4-4f6adf0478ce",
      "workspaceId": "ws_example",
      "ledgerSha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "snapshottedAt": "2026-02-01T00:00:00.000Z",
      "otsProofId": null,
      "btcBlockHeight": null,
      "status": "pending",
      "source": "manual",
      "label": "month-end",
      "recordCount": 412,
      "rangeStart": "2026-01-01T00:00:00.000Z",
      "rangeEnd": "2026-01-31T23:59:59.999Z",
      "jurisdiction": "ENAM",
      "bundleId": "eb7f9624-1f91-45d9-a9a4-4f6adf0478ce"
    }
  ]
}
// note: List anchors.
```

### `witness` (10 actions)

Witness Fabric — the platform-level 180-framework catalog + the neutral, chain-free adapter-record stream (list/get frameworks, integration patterns, the subscription matrix, and workspace record reads/writes; product-independent).

##### `witness.frameworks.list`

- **Summary**: List the supported agent-framework catalog (~180 frameworks) with status, category, and integration pattern — the platform-wide registry, not product-scoped.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/witness.frameworks.list`

**Example**:

```jsonc
// input
{
  "status": "stable"
}
// → output
{
  "frameworks": [
    {
      "id": "langchain",
      "name": "LangChain",
      "tagline": "The most widely deployed agent framework.",
      "category": "orchestration",
      "runtime": "python",
      "status": "stable",
      "integrationPattern": "sdk",
      "sdkPackage": "@trustvice/witness-langchain",
      "sdkVersion": "1.0.0",
      "integrationDocHref": "/docs/witness/langchain"
    }
  ],
  "counts": {
    "total": 175,
    "stable": 120,
    "beta": 40,
    "comingSoon": 15
  }
}
// note: All stable frameworks.
```

##### `witness.frameworks.get`

- **Summary**: Get one agent framework's catalog entry (support status, integration pattern, SDK package, docs).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/witness.frameworks.get`

**Example**:

```jsonc
// input
{
  "frameworkId": "langchain"
}
// → output
{
  "framework": {
    "id": "langchain",
    "name": "LangChain",
    "tagline": "The most widely deployed agent framework.",
    "category": "orchestration",
    "runtime": "python",
    "status": "stable",
    "integrationPattern": "sdk",
    "sdkPackage": "@trustvice/witness-langchain",
    "sdkVersion": "1.0.0",
    "integrationDocHref": "/docs/witness/langchain"
  }
}
// note: LangChain's catalog entry.
```

##### `witness.patterns.list`

- **Summary**: List the 9 integration patterns an agent runtime can attach through (SDK, webhook, OAuth polling, cloud event, OTel, MCP server, LLM proxy, browser instrument, proprietary).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/witness.patterns.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "patterns": [
    {
      "id": "sdk",
      "label": "SDK",
      "setup": "Install the framework SDK and set TRUSTVICE_API_KEY."
    },
    {
      "id": "proxy",
      "label": "LLM proxy",
      "setup": "Point the framework's base URL at the Trustvice proxy."
    },
    {
      "id": "webhook",
      "label": "Webhook",
      "setup": "Register a Trustvice endpoint as the framework's callback."
    }
  ]
}
// note: The pattern catalog.
```

##### `witness.subscriptions.get`

- **Summary**: Get the Witness-Fabric subscription matrix — which products consume which record event classes from the neutral stream.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/witness.subscriptions.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "subscriptions": [
    {
      "subscriber": "driftvice",
      "events": [
        "invocation",
        "tool_call"
      ],
      "binding": "FABRIC_SUBSCRIBER_DRIFTVICE"
    },
    {
      "subscriber": "nexus",
      "events": [
        "invocation"
      ],
      "binding": "FABRIC_SUBSCRIBER_NEXUS"
    }
  ]
}
// note: The WITNESS_SUBSCRIPTIONS routing matrix.
```

##### `witness.interpose`

- **Summary**: Witness one exchange with an agent you may not operate. Hashes only, unless retention is explicitly requested.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/witness.interpose`

**Example**:

```jsonc
// input
{
  "exchange": {
    "exchangeId": "ex_1",
    "targetRef": "https://agent.example/v1",
    "requestBody": "{}",
    "responseBody": "{}",
    "requestAt": "2026-09-04T00:00:00.000Z",
    "responseAt": "2026-09-04T00:00:00.250Z",
    "outcome": "200"
  }
}
// → output
{
  "receipt": {
    "exchangeId": "ex_1",
    "targetRef": "https://agent.example/v1",
    "requestSha256": "…",
    "responseSha256": "…",
    "latencyMs": 250,
    "outcome": "200",
    "attests": [
      "request_bytes_as_received"
    ],
    "observability": {
      "vantage": "interposed",
      "cannotAttest": [],
      "note": "…"
    }
  },
  "issue": {
    "kind": "interpose-witness",
    "subject": {},
    "claims": {}
  },
  "contentRetained": false,
  "notes": []
}
// note: Hashes only. Nothing stored.
```

##### `witness.interpose.verify`

- **Summary**: Check presented bytes against an interpose receipt's hashes.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/witness.interpose.verify`

**Example**:

```jsonc
// input
{
  "receipt": {
    "requestSha256": "aa",
    "responseSha256": "bb"
  },
  "requestBody": "{}"
}
// → output
{
  "requestMatches": false,
  "responseMatches": null,
  "fullyVerified": false,
  "reason": "A half-checked exchange is not a verified one."
}
// note: Null is not a mismatch.
```

##### `witness.records.list`

- **Summary**: List the workspace's adapter-captured agent records from the neutral Witness-Fabric store (chain-free read — product-independent; no TrustActor enrollment required).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/witness.records.list`

**Example**:

```jsonc
// input
{
  "frameworkId": "crewai",
  "limit": 20
}
// → output
{
  "records": [
    {
      "recordId": "0f5b0a1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a",
      "agentId": "did:web:example.com:agent:support",
      "event": "invocation",
      "occurredAt": "2026-07-19T12:00:00.000Z",
      "storedAt": "2026-07-19T12:00:01.480Z",
      "source": {
        "pattern": "sdk",
        "frameworkId": "crewai",
        "adapterVersion": "1.0.0",
        "ingestMode": "push"
      }
    }
  ],
  "count": 1,
  "nextCursor": {
    "before": "2026-07-19T12:00:01.480Z",
    "beforeId": "0f5b0a1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a"
  }
}
// note: Latest CrewAI records.
```

##### `witness.records.post`

- **Summary**: Post an adapter record directly onto the neutral Witness-Fabric plane (stored chain-free + fanned out to subscribing products; NOT anchored in the TrustActor hash chain — use the ingest lane for evidentiary anchoring).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/witness.records.post`

**Example**:

```jsonc
// input
{
  "record": {
    "agentId": "did:web:example.com:agent:support",
    "event": "invocation",
    "occurredAt": "2026-07-19T12:00:00Z",
    "source": {
      "pattern": "sdk",
      "frameworkId": "langchain",
      "adapterVersion": "1.0.0",
      "ingestMode": "push"
    }
  }
}
// → output
{
  "recordId": "0f5b0a1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a",
  "deduplicated": false,
  "chainAnchored": false,
  "delivery": {
    "broadcast": [
      "driftvice",
      "nexus"
    ],
    "failed": []
  }
}
// note: Neutral-plane record post.
```

##### `witness.records.stats`

- **Summary**: Aggregate stats over the workspace's neutral witness stream (totals + per-framework / per-pattern / per-event counts).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/witness.records.stats`

**Example**:

```jsonc
// input
{}
// → output
{
  "stats": {
    "total": 18420,
    "byFramework": [
      {
        "frameworkId": "langchain",
        "count": 11002
      },
      {
        "frameworkId": "crewai",
        "count": 4180
      }
    ],
    "byPattern": [
      {
        "pattern": "sdk",
        "count": 15200
      },
      {
        "pattern": "proxy",
        "count": 3220
      }
    ],
    "byEvent": [
      {
        "event": "invocation",
        "count": 12010
      },
      {
        "event": "tool_call",
        "count": 6410
      }
    ]
  }
}
// note: Stream aggregates for dashboards.
```

##### `witness.residency.prove`

- **Summary**: Prove where a run's recorded hops stayed, with the ceiling the evidence actually supports.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/witness.residency.prove`

**Example**:

```jsonc
// input
{
  "runId": "run_01J9",
  "declaredRegion": "weur-1"
}
// → output
{
  "proof": {
    "runRef": "run_01J9",
    "declaredRegion": "weur-1",
    "verdict": "no_recorded_departure",
    "hopsRecorded": 4,
    "offRegionHops": [],
    "unknownRegionHops": [
      "rec_2"
    ],
    "supportedClaim": "No recorded hop left weur-1. One hop's region is unknown, so this is not a proof that the run never left.",
    "limits": [
      "Egress is not instrumented; an absent hop in this record is not evidence there was none."
    ]
  },
  "hopsFromRecords": 4,
  "hopsWithNoRegion": 1,
  "egressInstrumented": false,
  "notes": [
    "An unknown region is not an in-region hop."
  ]
}
// note: The ceiling is no_recorded_departure, never "never left".
```

### `tranquility` (28 actions)

Tranquility (TY) — the platform-level maximalist observability suite. Live overview + any-denomination SLOs (ms/ratio/usd/count/burn), the Goal Ledger (cost per RESOLVED outcome + waste decomposition), the Agent module's honest tool/fleet/run/failure analytics over the witness stream, cognition signals (guardrail-pressure, plan blast-radius, charter conformance), and sealing any finding as an offline-verifiable VerifiableArtifact — all with explicit source-unavailable states and embedded coverage, never demo data.

##### `tranquility.overview`

- **Summary**: The workspace's live observability overview — agent-event stats, span stats, and SLO status, pulled live (honest source-unavailable states, never demo data).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.overview`

**Example**:

```jsonc
// input
{}
// → output
{
  "agentEvents": {
    "available": true,
    "total": 18420,
    "byEvent": [
      {
        "event": "invocation",
        "count": 12010
      }
    ]
  },
  "spans": {
    "available": true,
    "series": [
      {
        "bucket": "2026-09-01T00:00:00.000Z",
        "count": 4120
      }
    ]
  },
  "metrics": {
    "available": true,
    "distinctMetrics": 42,
    "top": [
      "http.server.duration",
      "agent.tokens"
    ]
  },
  "logs": {
    "available": true,
    "hasRecent": true
  },
  "slos": {
    "count": 3,
    "items": [
      {
        "sloId": "slo_api_latency",
        "name": "API p95 < 300ms",
        "objectivePct": 99.5,
        "window": "30d",
        "metric": "http.server.duration",
        "createdAt": "2026-07-01T00:00:00.000Z"
      }
    ]
  },
  "generatedAt": "2026-09-01T12:00:00.000Z"
}
// note: Workspace observability at a glance.
```

##### `tranquility.slos.list`

- **Summary**: List the workspace's SLO definitions (latency, error-rate, cost-per-outcome, mandate-burn — one engine, any denomination).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.slos.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "slos": [
    {
      "sloId": "slo_api_latency",
      "name": "API p95 < 300ms",
      "objectivePct": 99.5,
      "window": "30d",
      "metric": "http.server.duration",
      "createdAt": "2026-07-01T00:00:00.000Z"
    }
  ]
}
// note: All SLOs.
```

##### `tranquility.slos.create`

- **Summary**: Define an SLO: an SLI series + comparator + threshold + target attainment %, in any denomination (ms | ratio | usd | count | burn), with optional multi-window burn-rate alerting.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.slos.create`

**Example**:

```jsonc
// input
{
  "name": "resolution cost",
  "sliSeries": "goal.cost_usd",
  "denomination": "usd",
  "comparator": "lte",
  "threshold": 0.85,
  "targetPct": 95
}
// → output
{
  "slo": {
    "sloId": "slo_api_latency",
    "name": "API p95 < 300ms",
    "objectivePct": 99.5,
    "window": "30d",
    "metric": "http.server.duration",
    "createdAt": "2026-07-01T00:00:00.000Z"
  }
}
// note: A dollar-denominated SLO.
```

##### `tranquility.slos.get`

- **Summary**: Get one SLO definition + its recent evaluations (attainment, error budget, burn rate, status, coverage).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.slos.get`

**Example**:

```jsonc
// input
{
  "sloId": "tyslo_x"
}
// → output
{
  "slo": {
    "sloId": "slo_api_latency",
    "name": "API p95 < 300ms",
    "objectivePct": 99.5,
    "window": "30d",
    "metric": "http.server.duration",
    "createdAt": "2026-07-01T00:00:00.000Z"
  },
  "evaluations": [
    {
      "evaluatedAt": "2026-09-01T00:00:00.000Z",
      "achievedPct": 99.71,
      "met": true
    }
  ]
}
// note: SLO detail.
```

##### `tranquility.slos.evaluate`

- **Summary**: Evaluate an SLO now over a pushed SLI series; optionally SEAL the result as a signed, offline-verifiable attestation (?seal → ty-slo-attestation with its coverage embedded).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.slos.evaluate`

**Example**:

```jsonc
// input
{
  "sloId": "tyslo_x",
  "points": [
    {
      "ts": "2026-07-21T00:00:00Z",
      "value": 340
    }
  ],
  "seal": true
}
// → output
{
  "evaluation": {
    "evaluatedAt": "2026-09-01T00:00:00.000Z",
    "achievedPct": 99.71,
    "met": true
  },
  "result": {
    "objectivePct": 99.5,
    "achievedPct": 99.71,
    "errorBudgetRemainingPct": 42
  },
  "artifactId": "art_01M1F0000000000000000009"
}
// note: Evaluate + attest.
```

##### `tranquility.goals.list`

- **Summary**: List goals (business outcomes) with their rolled cost decomposition + outcome stamp.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.goals.list`

**Example**:

```jsonc
// input
{
  "outcome": "resolved"
}
// → output
{
  "goals": [
    {
      "goalId": "goal_01M1F0000000000000000001",
      "label": "Resolve ticket #4417",
      "outcome": "resolved",
      "costTotalUm": 18400,
      "openedAt": "2026-08-01T09:00:00.000Z",
      "closedAt": "2026-08-01T09:12:00.000Z"
    }
  ],
  "count": 1
}
// note: Resolved goals + their cost.
```

##### `tranquility.goals.create`

- **Summary**: Open a goal — a business outcome (ticket / booking / refund / conversation) whose full pursuit cost the Goal Ledger will stitch.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.goals.create`

**Example**:

```jsonc
// input
{
  "externalRef": "ticket-42",
  "kind": "ticket",
  "costCenter": "cc-support"
}
// → output
{
  "goalId": "goal_01M1F0000000000000000001"
}
// note: Open a support-ticket goal.
```

##### `tranquility.goals.events.append`

- **Summary**: Append cost events to a goal (turn / tool.call / retry / blocked / human / delivery); the ledger re-stitches the cost decomposition idempotently.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.goals.events.append`

**Example**:

```jsonc
// input
{
  "goalId": "tygoal_x",
  "events": [
    {
      "eventType": "tool.call",
      "costUm": 1200
    }
  ]
}
// → output
{
  "inserted": true,
  "goal": {
    "goalId": "goal_01M1F0000000000000000001",
    "label": "Resolve ticket #4417",
    "outcome": "resolved",
    "costTotalUm": 18400,
    "openedAt": "2026-08-01T09:00:00.000Z",
    "closedAt": "2026-08-01T09:12:00.000Z"
  }
}
// note: Log a tool call's cost.
```

##### `tranquility.goals.close`

- **Summary**: Stamp a goal's terminal outcome (resolved / abandoned / escalated / failed) — the attribution the Goal Ledger exists for.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.goals.close`

**Example**:

```jsonc
// input
{
  "goalId": "tygoal_x",
  "outcome": "resolved"
}
// → output
{
  "goal": {
    "goalId": "goal_01M1F0000000000000000001",
    "label": "Resolve ticket #4417",
    "outcome": "resolved",
    "costTotalUm": 18400,
    "openedAt": "2026-08-01T09:00:00.000Z",
    "closedAt": "2026-08-01T09:12:00.000Z"
  }
}
// note: Resolve a goal.
```

##### `tranquility.goals.summary`

- **Summary**: Cost per RESOLVED outcome + the waste decomposition (productive vs retry vs loop vs governance-blocked vs human vs delivery) across the workspace or a cost center.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.goals.summary`

**Example**:

```jsonc
// input
{}
// → output
{
  "byOutcome": [
    {
      "outcome": "resolved",
      "count": 412,
      "totalCostUm": 7580000,
      "avgCostUm": 18398
    },
    {
      "outcome": "abandoned",
      "count": 18,
      "totalCostUm": 410000,
      "avgCostUm": 22778
    }
  ],
  "costPerResolvedUm": 18398,
  "waste": {
    "productiveUm": 5100000,
    "retryUm": 1200000,
    "loopUm": 380000,
    "blockedUm": 240000,
    "humanUm": 610000,
    "deliveryUm": 460000
  },
  "totalGoals": 430,
  "productiveEfficiencyPct": 73.2
}
// note: Unit economics summary.
```

##### `tranquility.agent.records`

- **Summary**: Read the workspace's normalized agent events across 180 frameworks (invocation / tool.call / memory.write / sub_agent.spawn / channel.message), filterable by framework/pattern/event/agent.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.agent.records`

**Example**:

```jsonc
// input
{
  "frameworkId": "langchain",
  "event": "tool.call"
}
// → output
{
  "records": [
    {
      "recordId": "0f5b0a1c…",
      "agentId": "did:web:example.com:agent:support",
      "event": "invocation",
      "occurredAt": "2026-09-01T11:59:00.000Z"
    }
  ],
  "count": 1
}
// note: Recent LangChain tool calls.
```

##### `tranquility.agent.frameworks`

- **Summary**: The supported agent-framework catalog this workspace can observe (the 180-framework matrix, live from the witness catalog).
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.agent.frameworks`

**Example**:

```jsonc
// input
{}
// → output
{
  "frameworks": [
    {
      "frameworkId": "langchain",
      "count": 11002
    }
  ],
  "sampledRecords": 18420
}
// note: Framework coverage.
```

##### `tranquility.metrics.query`

- **Summary**: Query the workspace's metric points (OTLP gauge/sum/histogram) over a window, optionally filtered to one metric name — pulled live from the collector, newest-first, keyset-paginated. Honest source-unavailable state, never demo data.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.metrics.query`

**Example**:

```jsonc
// input
{
  "name": "http.server.duration"
}
// → output
{
  "series": [
    {
      "metric": "http.server.duration",
      "points": [
        {
          "t": "2026-09-01T11:00:00.000Z",
          "v": 214.5
        }
      ]
    }
  ]
}
// note: Recent points for one metric.
```

##### `tranquility.metrics.names`

- **Summary**: The metric-name catalogue for the workspace (distinct name + type + unit + point count + last-seen over the window) — what metrics are actually flowing.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.metrics.names`

**Example**:

```jsonc
// input
{}
// → output
{
  "names": [
    "http.server.duration",
    "agent.tokens"
  ],
  "metricCount": 42
}
// note: Which metrics exist.
```

##### `tranquility.logs.search`

- **Summary**: Search the workspace's OTLP log records over a window — filterable by a minimum severity floor (SeverityNumber 1–24) and by trace id (correlate logs to a trace's spans). Newest-first, keyset-paginated, honest source-unavailable state.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.logs.search`

**Example**:

```jsonc
// input
{
  "minSeverity": 17
}
// → output
{
  "logs": [
    {
      "t": "2026-09-01T11:59:12.000Z",
      "level": "error",
      "body": "upstream timeout",
      "attributes": {
        "service": "api-gateway"
      }
    }
  ]
}
// note: Errors and worse.
```

##### `tranquility.agent.tools`

- **Summary**: Per-tool analytics across the witness stream: call counts, success/failure rate over KNOWN-outcome calls only, p50/p95 latency over TIMED calls only (with a timed/untimed coverage split), and top verbatim errors. Nothing is imputed.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.agent.tools`

**Example**:

```jsonc
// input
{
  "frameworkId": "langchain"
}
// → output
{
  "tools": [
    {
      "tool": "search_docs",
      "calls": 3120,
      "failures": 41,
      "p95Ms": 180
    }
  ],
  "sampledRecords": 18420
}
// note: Tool reliability + latency, honestly scoped.
```

##### `tranquility.agent.fleet`

- **Summary**: Per-agent fleet health: event counts by class, first/last seen, tool-failure rate over known-outcome calls, sub-agent spawn activity, and a CALIBRATED heuristic health tag (healthy/degraded/quiet) carrying a confidence + basis — never a bare score.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.agent.fleet`

**Example**:

```jsonc
// input
{}
// → output
{
  "fleet": {
    "agents": 12,
    "active24h": 9,
    "failing": 1
  },
  "sampledRecords": 18420
}
// note: Which agents are healthy, degraded, or quiet.
```

##### `tranquility.agent.failures`

- **Summary**: Cluster failing tool calls by a normalized error signature (ids/numbers/urls/quotes masked) into ranked clusters, each with a count, distinct-agent count, window, and a VERBATIM earliest representative for audit. Only explicit failures are clustered.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.agent.failures`

**Example**:

```jsonc
// input
{}
// → output
{
  "clusters": [
    {
      "signature": "upstream timeout",
      "count": 41,
      "firstSeen": "2026-08-30T02:10:00.000Z",
      "lastSeen": "2026-09-01T11:59:12.000Z"
    }
  ],
  "sampledRecords": 18420
}
// note: Top failure clusters across the fleet.
```

##### `tranquility.agent.runTree`

- **Summary**: Reconstruct one run's step tree as a renderable DAG (sequence + spawn edges) from the witness stream, grouped by externalRefs.runId, with an HONEST unresolved-spawn coverage count and a stated grouping limitation.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.agent.runTree`

**Example**:

```jsonc
// input
{
  "runId": "R1"
}
// → output
{
  "tree": {
    "id": "run:abc",
    "children": [
      {
        "id": "span:1",
        "name": "search_docs",
        "durationMs": 180,
        "children": []
      }
    ]
  },
  "sampledRecords": 18420
}
// note: A single agent run as a DAG.
```

##### `tranquility.cognition.guardrailPressure`

- **Summary**: Clause-level guardrail cartography over pushed governed-chain outcomes: per-clause firing/allow/deny tallies, near-miss (only where a margin is present and a threshold is passed — never inferred), dead-clause detection, and an optional governance-tax summary. Tags carry a calibration note.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.cognition.guardrailPressure`

**Example**:

```jsonc
// input
{
  "evaluations": [
    {
      "clause": "pii.redact",
      "outcome": "deny",
      "at": "2026-07-21T00:00:00Z"
    }
  ]
}
// → output
{
  "pressure": {
    "evaluated": 240,
    "blocked": 3,
    "nearMisses": 18,
    "byClause": [
      {
        "clause": "no_pii_egress",
        "nearMisses": 12
      }
    ]
  }
}
// note: Hot-clause vs dead-policy map.
```

##### `tranquility.cognition.blastRadius`

- **Summary**: Pre-execution plan vitals over a typed action catalogue: reversibility ratio + a calibrated 0..100 blast-radius intensity, computed BEFORE execution. Actions with no metadata are EXCLUDED from the score (never assumed safe) and reported as unknown.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.cognition.blastRadius`

**Example**:

```jsonc
// input
{
  "actionIds": [
    "files.delete",
    "email.send"
  ],
  "actionMeta": {
    "files.delete": {
      "safetyLevel": "destructive",
      "idempotent": false,
      "confirmationRequired": true
    },
    "email.send": {
      "safetyLevel": "mutation",
      "idempotent": false,
      "confirmationRequired": false
    }
  }
}
// → output
{
  "blastRadius": {
    "actions": 4,
    "reversible": 3,
    "irreversible": 1,
    "maxScope": "workspace"
  }
}
// note: Score a plan before it runs.
```

##### `tranquility.cognition.charterConformance`

- **Summary**: Diff an agent's observed behavior against its declared charter (allowed tools / autonomy ceiling / allowed tones) — charter-as-SLO. A pure diff with a COVERAGE statement: an undeclared dimension is unposeable, and a no-charter case returns undefined, never a fabricated 100%.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.cognition.charterConformance`

**Example**:

```jsonc
// input
{
  "observed": {
    "tools": [
      "search",
      "email.send"
    ]
  },
  "declared": {
    "allowedTools": [
      "search"
    ]
  }
}
// → output
{
  "conformance": {
    "declared": 12,
    "observed": 11,
    "conforming": 10,
    "deviations": [
      {
        "clause": "escalate_on_refund",
        "observed": "auto_approved"
      }
    ]
  }
}
// note: Detect off-charter tool use.
```

##### `tranquility.cognition.vocabularyDrift`

- **Summary**: Vocabulary drift — Driftvice pointed at agents. TY NOMINATES candidate named-concepts from the agent stream (multi-word Title-Case + quoted, with verbatim evidence); Driftvice (the canon authority) returns each term's status (governed-settled / governed-drifting / ungoverned). Unresolvable terms are 'unknown', never a fabricated verdict; when Driftvice is unbound the candidates return with canon status unavailable.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.cognition.vocabularyDrift`

**Example**:

```jsonc
// input
{
  "topN": 25
}
// → output
{
  "vocabulary": {
    "terms": [
      {
        "normalized": "active user",
        "occurrences": 42
      }
    ]
  },
  "driftFindings": [
    {
      "term": "active user",
      "status": "governed-drifting"
    }
  ],
  "summary": {
    "candidates": 1,
    "governedDrifting": 1,
    "ungoverned": 0,
    "unresolved": 0
  },
  "canonSource": {
    "available": true
  },
  "sampledRecords": 18420
}
// note: Which named concepts the fleet uses are drifting or ungoverned.
```

##### `tranquility.evidence.usage.seal`

- **Summary**: Seal the cost-per-outcome summary as a signed, offline-verifiable usage/chargeback ledger (ty-usage-ledger).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.evidence.usage.seal`

**Example**:

```jsonc
// input
{
  "costCenter": "cc-support"
}
// → output
{
  "artifactId": "art_01M1F0000000000000000010",
  "summary": {
    "byOutcome": [
      {
        "outcome": "resolved",
        "count": 412,
        "totalCostUm": 7580000,
        "avgCostUm": 18398
      },
      {
        "outcome": "abandoned",
        "count": 18,
        "totalCostUm": 410000,
        "avgCostUm": 22778
      }
    ],
    "costPerResolvedUm": 18398,
    "waste": {
      "productiveUm": 5100000,
      "retryUm": 1200000,
      "loopUm": 380000,
      "blockedUm": 240000,
      "humanUm": 610000,
      "deliveryUm": 460000
    },
    "totalGoals": 430,
    "productiveEfficiencyPct": 73.2
  }
}
// note: Signed chargeback statement.
```

##### `tranquility.evidence.coverage.seal`

- **Summary**: Seal an aggregate figure with its coverage statement as a signed artifact — 'p95 = 340ms over 100% of traffic with zero drop windows, signed' (ty-coverage-statement).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.evidence.coverage.seal`

**Example**:

```jsonc
// input
{
  "metric": "p95",
  "value": 340,
  "unit": "ms"
}
// → output
{
  "artifactId": "art_01M1F0000000000000000011",
  "sealed": {
    "metric": "p95",
    "value": 340,
    "coverage": {
      "samplingPct": 100,
      "complete": true
    }
  }
}
// note: Signed coverage-stated figure.
```

##### `tranquility.artifacts.list`

- **Summary**: List the signed evidence artifacts TY has minted for this workspace (attestations, usage ledgers, coverage statements, sealed alarms) with their verify references.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.artifacts.list`

**Example**:

```jsonc
// input
{
  "subjectKind": "slo"
}
// → output
{
  "artifacts": [
    {
      "artifact_id": "art_01M1F0000000000000000010",
      "kind": "usage_ledger",
      "subject_kind": "usage",
      "subject_id": "all",
      "leaf_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "tops_ref": null,
      "minted_at": "2026-09-01T12:00:00.000Z"
    }
  ],
  "count": 1
}
// note: Signed SLO attestations.
```

##### `tranquility.views.list`

- **Summary**: List saved views / custom monitors for a surface.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.views.list`

**Example**:

```jsonc
// input
{
  "surface": "agent"
}
// → output
{
  "views": [
    {
      "viewId": "view_1",
      "name": "Agent errors",
      "surface": "agent",
      "spec": {}
    }
  ]
}
// note: Agent-surface views.
```

##### `tranquility.views.create`

- **Summary**: Save a view / custom monitor (a signal + selector + panel spec) for reuse on a dashboard surface.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/tranquility.views.create`

**Example**:

```jsonc
// input
{
  "name": "tool heatmap",
  "surface": "agent",
  "spec": {
    "panel": "heatmap"
  }
}
// → output
{
  "viewId": "view_1"
}
// note: Save a monitor.
```

### `placard` (9 actions)

Placard — the AI disclosure instrument a PERSON reads. Compose a structured, CONTENT-ADDRESSED notice (the id is the sha256 of its canonical bytes, so what was shown stays checkable), sign it, resolve and verify it publicly with no account, and keep a delivery ledger that records whether the notice preceded the interaction it was owed for. Composition refuses a notice missing its statutory core, and coverage answers `unknown` rather than collapsing an unreadable answer into `covered`.

##### `placard.compose`

- **Summary**: Compose a content-addressed AI disclosure notice and register it. The returned id IS the sha256 of the canonical bytes, so what was shown stays checkable. Refuses a notice missing its statutory core, and refuses to compose unsigned.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `placard.compose`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/placard.compose`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "subject": "support-assistant",
  "channels": [
    "chat"
  ],
  "texts": [
    {
      "locale": "en",
      "elements": {
        "artificialNature": "You are speaking with an AI assistant, not a person."
      }
    }
  ]
}
// → output
{
  "placardId": "plc_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "subject": "support-assistant",
  "version": 1,
  "channels": [
    "chat"
  ],
  "texts": [
    {
      "locale": "en",
      "elements": {
        "artificialNature": "You are speaking with an AI assistant, not a person."
      }
    }
  ],
  "composedAt": "2026-07-29T10:00:00.000Z",
  "signature": "…",
  "signatureKeyId": "…",
  "canonical": "{}"
}
// note: Compose a one-locale chat notice.
```

##### `placard.list`

- **Summary**: List this workspace's composed placards, newest first.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `placard.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/placard.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "placards": []
}
// note: List placards.
```

##### `placard.coverage.get`

- **Summary**: Is a subject covered on a channel? Answers `covered`, `not-covered`, or `unknown` — and `unknown` never collapses to covered, because an unreadable answer is not a satisfied duty.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `placard.coverage.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/placard.coverage.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "subject": "support-assistant",
  "channel": "chat"
}
// → output
{
  "state": "not-covered",
  "reason": "No placard registered for this subject on this channel."
}
// note: Check coverage before an interaction.
```

##### `placard.delivery.record`

- **Summary**: Record that a placard was delivered. `priorTurns` is REQUIRED, not defaulted — zero means the notice preceded the first interaction, and defaulting it would silently mark every delivery on time.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `placard.delivery.record`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/placard.delivery.record`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "placardId": "plc_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "channel": "chat",
  "subjectRef": "sess_abc",
  "priorTurns": 0
}
// → output
{
  "deliveryId": "plcd_abc",
  "placardId": "plc_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "channel": "chat",
  "subjectRef": "sess_abc",
  "priorTurns": 0,
  "localeServed": null,
  "localeFallback": false
}
// note: Record an on-time delivery.
```

##### `placard.delivery.acknowledge`

- **Summary**: Record that the person acknowledged a delivered notice. Only meaningful on surfaces that can carry an acknowledgement.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `placard.delivery.record`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/placard.delivery.acknowledge`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "deliveryId": "plcd_abc"
}
// → output
{
  "deliveryId": "plcd_abc",
  "acknowledged": true
}
// note: Record an acknowledgement.
```

##### `placard.deliveries.get`

- **Summary**: The delivery and acknowledgement state for one interaction. A late delivery reports as `delivered-late` and is never rounded up to `delivered`.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `placard.delivery.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/placard.deliveries.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "subjectRef": "sess_abc"
}
// → output
{
  "delivery": "unknown",
  "acknowledgement": "unknown",
  "rows": []
}
// note: Read one interaction's disclosure state.
```

##### `placard.resolve`

- **Summary**: PUBLIC. Fetch a placard by id. No account needed — anyone holding the id can read exactly what notice was composed.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/placard.resolve`

**Example**:

```jsonc
// input
{
  "placardId": "plc_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
}
// → output
{
  "placardId": "plc_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "subject": "support-assistant",
  "version": 1,
  "channels": [
    "chat"
  ],
  "texts": [],
  "composedAt": "2026-07-29T10:00:00.000Z",
  "signature": "…",
  "signatureKeyId": "…",
  "canonical": "{}"
}
// note: Resolve a placard with no account.
```

##### `placard.verify`

- **Summary**: PUBLIC. Check a placard's bytes against its id and its signature against the published keys. A genuinely invalid placard is a VERDICT, not an error — the call succeeds and reports `ok: false`.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/placard.verify`

**Example**:

```jsonc
// input
{
  "placardId": "plc_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "canonical": "{}"
}
// → output
{
  "ok": false,
  "reason": "content-address-mismatch"
}
// note: Verify bytes against the content address.
```

##### `placard.keys.get`

- **Summary**: PUBLIC. The JWK Set placards are signed with, for offline verification.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/placard.keys.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "keys": []
}
// note: Read the signing keys.
```

### `cachet` (11 actions)

Cachet — an AGENT's conduct standing, computed from its own runs. Two axes kept separate and never averaged: IDENTITY (what a credential actually proves, on a 7-rung ladder — an operator's claim never raises it) and CONDUCT (declared capabilities versus observed ones, in both directions, plus breaches of the operator's own asserted limits). Signed and publicly resolvable; an unrated standing may not be issued, and revocation withdraws without deleting.

##### `cachet.declare`

- **Summary**: Declare what an agent may do and the hard limits it asserts. Versioned and superseded, never edited — an operator cannot widen a declaration to erase yesterday's finding.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `cachet.declare`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/cachet.declare`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "agentId": "ag_support",
  "capabilities": [
    "read.tickets",
    "send.reply"
  ],
  "limits": [
    "never.refunds"
  ]
}
// → output
{
  "declarationId": "cdec_abc",
  "agentId": "ag_support",
  "version": 1,
  "capabilities": [
    "read.tickets",
    "send.reply"
  ],
  "limits": [
    "never.refunds"
  ],
  "declaredAt": "2026-07-29T10:00:00.000Z"
}
// note: Declare an agent's capabilities and limits.
```

##### `cachet.observe`

- **Summary**: Record a capability an agent was actually seen exercising. Bound to the declaration in force AT THE TIME, so dropping a limit later cannot clear the history.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `cachet.observe`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/cachet.observe`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "agentId": "ag_support",
  "capability": "send.reply",
  "runRef": "run_abc"
}
// → output
{
  "observationId": "cobs_abc",
  "agentId": "ag_support",
  "capability": "send.reply",
  "breachedLimit": null,
  "observedAt": "2026-07-29T10:05:00.000Z"
}
// note: Record one observed run.
```

##### `cachet.evidence.submit`

- **Summary**: Present identity evidence for an agent. `verified` is REQUIRED — defaulting true would promote every presented credential, defaulting false would bury working ones. Failed evidence is retained, not dropped.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `cachet.evidence.submit`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/cachet.evidence.submit`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "agentId": "ag_support",
  "source": "did-web",
  "verified": true
}
// → output
{
  "evidenceId": "cevi_abc",
  "agentId": "ag_support",
  "source": "did-web",
  "verified": true,
  "presentedAt": "2026-07-29T10:00:00.000Z"
}
// note: Present a verified did:web credential.
```

##### `cachet.standing.get`

- **Summary**: The current standing as an UNSIGNED preview, so an operator can see where they stand before publishing. Carries `signed: false` in the payload — it is not a cachet and nobody can verify it.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `cachet.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/cachet.standing.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "agentId": "ag_support"
}
// → output
{
  "signed": false,
  "note": "This is an unsigned preview…",
  "agentId": "ag_support",
  "declared": true,
  "conduct": {
    "grade": "unrated",
    "runsObserved": 2,
    "divergence": {
      "undeclared": [],
      "unexercised": [],
      "breaches": []
    },
    "basis": "Only 2 run(s) observed…"
  },
  "identity": {
    "grade": "self-asserted",
    "accord": "unpublished",
    "claimedGrade": null
  },
  "evidenceWindow": {
    "from": null,
    "to": null
  },
  "issuable": false
}
// note: Preview a standing before publishing.
```

##### `cachet.issue`

- **Summary**: Issue a signed, publicly resolvable standing. REFUSES an unrated conduct grade — a signed badge reads as an endorsement whatever word is inside it. `claimedGrade` is compared against the evidence and never raises the published grade.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `cachet.issue`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/cachet.issue`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "agentId": "ag_support",
  "claimedGrade": "business-verified"
}
// → output
{
  "cachetId": "cac_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "agentId": "ag_support",
  "identity": {
    "grade": "domain-control",
    "accord": "overstated",
    "claimedGrade": "business-verified"
  },
  "conduct": {
    "grade": "consistent",
    "runsObserved": 12,
    "divergence": {
      "undeclared": [],
      "unexercised": [],
      "breaches": []
    },
    "basis": "Across 12 runs…"
  },
  "evidenceWindow": {
    "from": "2026-07-01T00:00:00.000Z",
    "to": "2026-07-28T00:00:00.000Z"
  },
  "issuedAt": "2026-07-29T10:00:00.000Z",
  "signature": "…",
  "signatureKeyId": "…",
  "canonical": "{}"
}
// note: An overstated claim publishes the evidence's grade and attaches the finding.
```

##### `cachet.revoke`

- **Summary**: Withdraw an issued standing. NOT deletion — the cachet still resolves and reports that it was revoked and why, because a live citation must not 404 into 'never existed'. A reason is required.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `cachet.revoke`
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/cachet.revoke`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "cachetId": "cac_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "reason": "The agent's capability set changed materially after issuance."
}
// → output
{
  "cachetId": "cac_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "revoked": true,
  "reason": "The agent's capability set changed materially after issuance."
}
// note: Withdraw a standing without deleting it.
```

##### `cachet.list`

- **Summary**: List issued cachets for this workspace, optionally for one agent.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `cachet.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/cachet.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "cachets": []
}
// note: List issued cachets.
```

##### `cachet.agents.list`

- **Summary**: Every agent Cachet knows about, from either side. An agent that was OBSERVED but never DECLARED appears here — listing only declared agents would hide the finding worth showing first.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `cachet.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/cachet.agents.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "agents": [
    {
      "agentId": "ag_rogue",
      "declared": false,
      "conductGrade": "undeclared-conduct",
      "identityGrade": "self-asserted",
      "runsObserved": 9,
      "issuable": true
    }
  ]
}
// note: An observed-but-undeclared agent surfaces here.
```

##### `cachet.resolve`

- **Summary**: PUBLIC. Fetch a standing by id. A revoked cachet still resolves and says so — deleting it would make a live citation read as 'never existed' rather than 'withdrawn'.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/cachet.resolve`

**Example**:

```jsonc
// input
{
  "cachetId": "cac_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
}
// → output
{
  "cachetId": "cac_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "agentId": "ag_support",
  "identity": {
    "grade": "domain-control",
    "accord": "accurate",
    "claimedGrade": "domain-control"
  },
  "conduct": {
    "grade": "consistent",
    "runsObserved": 12,
    "divergence": {
      "undeclared": [],
      "unexercised": [],
      "breaches": []
    },
    "basis": "…"
  },
  "evidenceWindow": {
    "from": "2026-07-01T00:00:00.000Z",
    "to": "2026-07-28T00:00:00.000Z"
  },
  "evidenceAgeDays": 1,
  "issuedAt": "2026-07-29T10:00:00.000Z",
  "signature": "…",
  "signatureKeyId": "…",
  "canonical": "{}",
  "revoked": false,
  "revokedAt": null,
  "revocationReason": null
}
// note: Resolve a standing with no account.
```

##### `cachet.verify`

- **Summary**: PUBLIC. Check a cachet's bytes against its id and its signature against the published keys — and report whether it has been REVOKED, because cryptographic validity is not currency.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/cachet.verify`

**Example**:

```jsonc
// input
{
  "cachetId": "cac_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "canonical": "{}"
}
// → output
{
  "ok": false,
  "reason": "content-address-mismatch"
}
// note: Verify bytes against the content address.
```

##### `cachet.keys.get`

- **Summary**: PUBLIC. The JWK Set cachets are signed with, for offline verification.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/cachet.keys.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "keys": []
}
// note: Read the signing keys.
```

### `emissary` (10 actions)

Emissary — the machine-readable declaration plane. Publish what your site permits AI crawlers and agents to do (train / infer / quote / index / embed / evaluate) as a signed, content-addressed artifact, serve it as JSON or rendered text, and ledger every fetch with a GRADED attribution — a User-Agent is typed by the client and proves nothing, so a confirmed operator is never conflated with a claimed one. A declaration is a STATEMENT, not an enforcement mechanism.

##### `emissary.publish`

- **Summary**: Publish a signed, content-addressed declaration of what you permit AI crawlers and agents to do. Refuses a declaration that states nothing, declares two stances on one subject, or leaves a conditional without a condition. This is a STATEMENT, not an enforcement mechanism.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `emissary.publish`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/emissary.publish`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "domain": "example.com",
  "directives": [
    {
      "subject": "train",
      "stance": "deny"
    },
    {
      "subject": "index",
      "stance": "allow"
    }
  ],
  "contact": "ai@example.com"
}
// → output
{
  "declarationId": "emd_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "domain": "example.com",
  "version": 1,
  "directives": [
    {
      "subject": "index",
      "stance": "allow"
    },
    {
      "subject": "train",
      "stance": "deny"
    }
  ],
  "contact": "ai@example.com",
  "licence": null,
  "notes": null,
  "publishedAt": "2026-07-29T10:00:00.000Z",
  "signature": "…",
  "signatureKeyId": "…",
  "retired": false,
  "retiredAt": null,
  "canonical": "{}"
}
// note: Deny training, allow indexing.
```

##### `emissary.list`

- **Summary**: List this workspace's declarations, newest first — including retired versions, which still resolve.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `emissary.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/emissary.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "declarations": []
}
// note: List declarations.
```

##### `emissary.current.get`

- **Summary**: The live declaration for a domain. Nothing published is reported as a GAP, never as a permissive default — silence is not permission.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `emissary.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/emissary.current.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "domain": "example.com"
}
// → output
{
  "declarationId": "emd_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "domain": "example.com",
  "version": 1,
  "directives": [],
  "contact": null,
  "licence": null,
  "notes": null,
  "publishedAt": "2026-07-29T10:00:00.000Z",
  "signature": "…",
  "signatureKeyId": "…",
  "retired": false,
  "retiredAt": null,
  "canonical": "{}"
}
// note: Read the live declaration.
```

##### `emissary.fetches.list`

- **Summary**: The raw fetch ledger. Every row carries its attribution grade, and `operator` (CONFIRMED) is separate from `claimedOperator` (what the User-Agent said) — a User-Agent is typed by the client and proves nothing.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `emissary.fetches.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/emissary.fetches.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "fetches": [
    {
      "fetchId": "emf_abc",
      "declarationId": "emd_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "attributionGrade": "self-declared",
      "operator": null,
      "claimedOperator": "OpenAI",
      "contradicted": false,
      "userAgent": "Mozilla/5.0 (compatible; GPTBot/1.2)",
      "reverseDns": null,
      "forwardConfirmed": false,
      "signatureKeyId": null,
      "basis": "The User-Agent claims OpenAI. Nothing verified it…",
      "fetchedAt": "2026-07-29T10:00:00.000Z",
      "variant": "text"
    }
  ]
}
// note: A self-declared fetch: the claim is recorded, the operator is not.
```

##### `emissary.audience.get`

- **Summary**: The graded audience summary. Counts split BY GRADE and never total into one 'N agents fetched your declaration' — that headline is how the category promotes User-Agent strings into facts. An unreadable ledger returns `unknown`, never zero.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `emissary.audience.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/emissary.audience.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "total": 7,
  "byGrade": {
    "unidentified": 1,
    "self-declared": 2,
    "ip-confirmed": 3,
    "signature-verified": 1
  },
  "confirmedOperators": [
    {
      "operator": "OpenAI",
      "fetches": 2
    }
  ],
  "claimedOnlyOperators": [
    {
      "operator": "Perplexity",
      "fetches": 1
    }
  ],
  "contradictions": 1,
  "citable": 4,
  "caveat": "4 of 7 fetches were verified against something the client does not control…"
}
// note: Confirmed and merely-claimed operators never merge.
```

##### `emissary.agents.list`

- **Summary**: The known-agent registry, with the BEST grade each operator could ever reach given what is registered — so an operator with no suffixes and no keys is told why its rows never clear the citable floor.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `emissary.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/emissary.agents.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000"
}
// → output
{
  "agents": [
    {
      "operator": "OpenAI",
      "userAgentMarkers": [
        "GPTBot"
      ],
      "domainSuffixes": [
        "openai.com"
      ],
      "signingKeyIds": [],
      "bestAchievableGrade": "ip-confirmed"
    }
  ]
}
// note: No registered keys means this operator can never reach signature-verified.
```

##### `emissary.agents.register`

- **Summary**: Register or replace a known AI-agent operator. Requires at least one fingerprint — a User-Agent marker, a reverse-DNS suffix, or a signing key — because with none, no fetch could ever be matched to it.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `emissary.agents.manage`
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/emissary.agents.register`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "operator": "Anthropic",
  "userAgentMarkers": [
    "ClaudeBot"
  ],
  "domainSuffixes": [
    "anthropic.com"
  ]
}
// → output
{
  "agentKey": "ema_anthropic_ws_DEMODEFAULT0000000000",
  "operator": "Anthropic",
  "userAgentMarkers": [
    "ClaudeBot"
  ],
  "domainSuffixes": [
    "anthropic.com"
  ],
  "signingKeys": 0
}
// note: Register an operator so its fetches can reach ip-confirmed.
```

##### `emissary.resolve`

- **Summary**: PUBLIC. Fetch a declaration by id, as JSON or as the rendered text form. Every fetch is ledgered with a graded attribution. A declaration nobody can fetch without credentials would tell no crawler anything.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/emissary.resolve`

**Example**:

```jsonc
// input
{
  "declarationId": "emd_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
}
// → output
{
  "declarationId": "emd_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "domain": "example.com",
  "version": 1,
  "directives": [
    {
      "subject": "train",
      "stance": "deny"
    }
  ],
  "contact": null,
  "licence": null,
  "notes": null,
  "publishedAt": "2026-07-29T10:00:00.000Z",
  "signature": "…",
  "signatureKeyId": "…",
  "retired": false,
  "retiredAt": null,
  "canonical": "{}"
}
// note: Resolve a declaration with no account.
```

##### `emissary.verify`

- **Summary**: PUBLIC. Check a declaration's bytes against its id and its signature against the published keys — and report whether it has been RETIRED, because validity is not currency.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/emissary.verify`

**Example**:

```jsonc
// input
{
  "declarationId": "emd_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "canonical": "{}"
}
// → output
{
  "ok": false,
  "reason": "content-address-mismatch"
}
// note: Verify bytes against the content address.
```

##### `emissary.keys.get`

- **Summary**: PUBLIC. The JWK Set declarations are signed with, for offline verification.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/emissary.keys.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "keys": []
}
// note: Read the signing keys.
```

### `c2pa` (2 actions)

Content provenance (C2PA). `sign` mints a COSE_Sign1 manifest over a content hash and returns embeddable bytes; `verify` checks one against the published signer keys. Verification needs no signing key and answers even where signing is unprovisioned; a failed verification is a 200 with `ok: false`, never a transport error.

##### `c2pa.sign`

- **Summary**: Sign a content hash into a C2PA manifest — COSE_Sign1 over the deterministic-CBOR claim, returned as embeddable bytes.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/c2pa.sign`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "contentSha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "mimeType": "image/png",
  "title": "Q3 results chart"
}
// → output
{
  "manifest": {
    "label": "c2pa:ws_DEMODEFAULT0000000000:e3b0c442",
    "vendor": "trustvice",
    "format": "c2pa:manifest@2.1",
    "claim": {},
    "claimSignature": {
      "algorithm": "EdDSA",
      "keyId": "c2pa-2026-q3-enam",
      "signatureValue": "0oRDoQEnoQRQ...",
      "signingTime": "2026-05-22T12:00:00.000Z",
      "signerDid": "did:web:trustvice.com"
    }
  },
  "manifestCborBase64Url": "0oRDoQEnoQRQ...",
  "signedAt": "2026-05-22T12:00:00.000Z",
  "persisted": true,
  "manifestUrl": "/v1/c2pa/manifest/ws_DEMODEFAULT0000000000/c2pa:ws_DEMODEFAULT0000000000:e3b0c442"
}
// note: Sign a content hash. Needs a provisioned regional signing key — absent, the worker answers an honest 503 rather than an unsigned manifest.
```

##### `c2pa.verify`

- **Summary**: Verify a C2PA manifest against the published signer keys, and optionally assert it covers the content you have.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/c2pa.verify`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "manifestCborBase64Url": "0oRDoQEnoQRQ..."
}
// → output
{
  "ok": true,
  "activeManifestLabel": "c2pa:ws_DEMODEFAULT0000000000:e3b0c442",
  "signedAt": "2026-05-22T12:00:00.000Z",
  "signerDid": "did:web:trustvice.com",
  "contentHashMatches": true,
  "lineageDepth": 0
}
// note: Verify a manifest. Needs no signing key — this answers in regions where signing is unprovisioned.
```

### `receipts` (4 actions)

Verifiable artifacts — the signed-evidence substrate. `issue` mints a receipt of a given `kind` (Proof-of-Erasure, Provable Residency, AI-BOM, …), `get`/`list` read them back, and `verify` checks one against the published keys plus Merkle inclusion. `kind` is OPEN: bring your own `subject` + `claims` for a kind with no builder. Verification needs no signing key and answers where issuing is unprovisioned; a failed verification is a 200 with `ok: false`, never a transport error.

##### `receipts.issue`

- **Summary**: Mint a signed verifiable artifact — a receipt an auditor can check without trusting us, anchored into the Merkle batch.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/receipts.issue`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "kind": "proof-of-erasure",
  "source": {
    "subjectRef": "user_9f2a",
    "erasedAt": "2026-05-22T12:00:00.000Z"
  }
}
// → output
{
  "artifactId": "01J9Z6M2K7QW8X0YB3C4D5E6F7",
  "bundle": {},
  "leafHash": "a3f1c8e2…",
  "topsRef": null,
  "signatureKeyId": "entpoind-2026-q3-enam"
}
// note: Mint a Proof-of-Erasure. Needs a provisioned regional signing key — absent, the worker answers an honest 503 rather than an unsigned receipt. `topsRef` is null until the anchor batch runs.
```

##### `receipts.get`

- **Summary**: Read one verifiable artifact by id, including its anchor reference once the batch has run.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/receipts.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "artifactId": "01J9Z6M2K7QW8X0YB3C4D5E6F7"
}
// → output
{
  "artifact": {},
  "kind": "proof-of-erasure",
  "issuedAt": "2026-05-22T12:00:00.000Z",
  "leafHash": "a3f1c8e2…",
  "topsRef": "tops_01J9…"
}
// note: An artifact belonging to another workspace answers 404, not 403 — the id space is not an enumeration oracle.
```

##### `receipts.list`

- **Summary**: List this workspace's verifiable artifacts, newest first, optionally filtered to one kind.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/receipts.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "kind": "proof-of-erasure",
  "limit": 50
}
// → output
{
  "artifacts": [
    {
      "artifactId": "01J9Z6M2K7QW8X0YB3C4D5E6F7",
      "kind": "proof-of-erasure",
      "subjectHash": "9c1d…",
      "issuedAt": "2026-05-22T12:00:00.000Z",
      "leafHash": "a3f1c8e2…",
      "topsRef": "tops_01J9…"
    }
  ]
}
// note: The list is a projection — it carries no claims and no signature. Fetch the artifact to verify one.
```

##### `receipts.verify`

- **Summary**: Verify a signed artifact against the published keys — signature, and Merkle inclusion when you supply the anchored bundle.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/receipts.verify`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "artifact": {}
}
// → output
{
  "ok": true
}
// note: Pure public-key work — this answers in a region where issuing is unprovisioned, and needs no signing key of ours.
```

### `memory` (7 actions)

Portable verifiable agent memory (Portmind). `put`/`get`/`list`/`remove` a key-value memory scoped to ONE agent DID, and `snapshot` it into a Merkle root a portable export verifies against. Reading or writing your OWN namespace needs no mandate; touching ANOTHER agent's needs one, and there is no mandate-admin action here on purpose — an endpoint that creates authority must not be reachable by the authority it creates. `remove` is a tombstone: a WRITE, and the snapshot still reflects that the key is gone.

##### `memory.put`

- **Summary**: Write one memory entry. Requires a mandate unless writing your own namespace.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `portmind.memory_written`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/memory.put`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "agentDid": "did:web:example.com:agents:ws:a1",
  "key": "user.name",
  "value": "Ada"
}
// → output
{
  "entry": {
    "agentRef": "did:web:example.com:agents:ws:a1",
    "key": "user.name",
    "value": "Ada",
    "contentSha256": "aa11",
    "tags": [],
    "version": 1,
    "createdAt": "2026-09-04T00:00:00.000Z",
    "updatedAt": "2026-09-04T00:00:00.000Z"
  }
}
// note: Write to your own namespace — no mandate needed.
```

##### `memory.get`

- **Summary**: Read one memory entry by key.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/memory.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "agentDid": "did:web:example.com:agents:ws:a1",
  "key": "user.name"
}
// → output
{
  "entry": {
    "agentRef": "did:web:example.com:agents:ws:a1",
    "key": "user.name",
    "value": "Ada",
    "contentSha256": "aa11",
    "tags": [],
    "version": 1,
    "createdAt": "2026-09-04T00:00:00.000Z",
    "updatedAt": "2026-09-04T00:00:00.000Z"
  }
}
// note: Read one key.
```

##### `memory.list`

- **Summary**: List live memory entries for an agent, key-ordered.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/memory.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "agentDid": "did:web:example.com:agents:ws:a1",
  "limit": 100
}
// → output
{
  "entries": []
}
// note: List an agent's live memory.
```

##### `memory.remove`

- **Summary**: Tombstone one memory entry. A deletion is a WRITE and needs write authority.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `portmind.memory_removed`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/memory.remove`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "agentDid": "did:web:example.com:agents:ws:a1",
  "key": "user.name"
}
// → output
{
  "removed": true,
  "agentRef": "did:web:example.com:agents:ws:a1",
  "key": "user.name"
}
// note: Tombstone one key; the snapshot still reflects that it is gone.
```

##### `memory.snapshot`

- **Summary**: Merkle snapshot of an agent's live memory — the root a portable export verifies against.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/memory.snapshot`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "agentDid": "did:web:example.com:agents:ws:a1"
}
// → output
{
  "snapshot": {
    "agentRef": "did:web:example.com:agents:ws:a1",
    "snapshotRef": "snap_abc",
    "entryCount": 0,
    "merkleRoot": "root",
    "earliestEntryAt": null,
    "latestEntryAt": null,
    "snapshotAt": "2026-09-04T00:00:00.000Z"
  },
  "mint": {
    "kind": "memory-attestation",
    "source": {}
  }
}
// note: Snapshot for a verifiable export.
```

##### `memory.export`

- **Summary**: Export an agent's live memory as a portable, tamper-evident bundle.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/memory.export`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "agentDid": "did:web:example.com:agents:ws:a1"
}
// → output
{
  "bundle": {
    "agentRef": "did:web:example.com:agents:ws:a1",
    "entries": [],
    "claimedRoot": "root",
    "exportedAt": "2026-09-04T00:00:00.000Z",
    "exportedBy": "ws_DEMODEFAULT0000000000",
    "origin": "unattested",
    "anchorRef": null
  },
  "attestationPath": "POST /v1/portmind/snapshot → mint the `memory-attestation` receipt at entpoind → ship it beside this bundle.",
  "notes": []
}
// note: A portable export. Unattested until a receipt travels with it.
```

##### `memory.import.verify`

- **Summary**: Verify a portable memory bundle that arrived from anywhere — integrity now, completeness only against a root committed to beforehand.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill
- **REST endpoint**: `POST /v1/actions/memory.import.verify`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_DEMODEFAULT0000000000",
  "bundle": {
    "agentRef": "agent_a",
    "entries": [
      {
        "key": "goal",
        "contentSha256": "ab"
      }
    ],
    "claimedRoot": "root",
    "exportedAt": "2026-09-04T00:00:00.000Z",
    "exportedBy": "other-vendor",
    "origin": "unattested"
  }
}
// → output
{
  "verification": {
    "agentRef": "agent_a",
    "integrity": "root_mismatch",
    "completeness": "unknown",
    "recomputedRoot": "computed",
    "entryCount": 1,
    "origin": "unattested",
    "safeToTrustAsComplete": false,
    "notes": []
  }
}
// note: Integrity is checkable here; completeness is not, without a prior root.
```


---

**Total**: 523 actions across 36 domains.

Generated 2026-11-08T20:41:05.782Z from contracts 0.91.0.