# Agined + Attestor — Agentic Control Surface

> Auto-generated from `@agined/contracts@0.32.289-agined.1` on 2026-11-10T21:32:07.834Z.
> 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 Agined + Attestor. It is consumed by:

- AI coding assistants (Claude Code, Cursor, GitHub Copilot, OpenAI Codex) — for retrieval-augmented code generation against the Agined API.
- AI chat surfaces (ChatGPT, Claude, Gemini, Perplexity) — for context priming when an end-user grants the connector access.
- The Agined 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.agined.com` — REST surface (OAuth 2.1 + PKCE + DPoP, PAT, workspace API keys, and mTLS client certificates where the workspace has trusted your CA).
- **MCP server**: `https://mcp.a2pi.app/mcp` — streamable HTTP transport. Tool list mirrors this catalogue.
- **A2A discovery**: `https://agined.com/.well-known/agent-card.json` — the capability card where an agent answers here, and a directory of where the per-tenant cards are where one does not.
- **AGENTS.md (this file)**: `https://agined.com/.well-known/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 (`Agined-Workspace-Id`) and an `X-Idempotency-Key`.

## Cross-workspace delegation

Not offered. An actor acts in the workspace its credential chain resolved; a caller-supplied workspace that differs is refused with 403 `wrong_workspace` rather than gated by a ceremony.

## Intent claims

Served. `POST /api/v1/intents/claim` with `{ actionId, input, workspaceId? }` under the credential the call will use returns a signed, one-shot, 60-second claim binding that action id, the SHA-256 of the canonical input and the actor. Present it base64url-encoded in `X-Agined-Intent`. Actions whose `intent_claim_required` is true refuse a call without one (403 `intent_claim_required`); every action verifies a presented claim and refuses a mismatch (403 `intent_mismatch`). Specification: `intent-claims.ts` in `@agined/contracts`.

## 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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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 endpoint**: `POST /api/v1/actions/account.session.current`

**Example**:

```jsonc
// input
{}
// → output
{
  "sessionId": "sess_abc",
  "accountId": "acct_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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/account.profile.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "accountId": "acct_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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/account.profile.update`

**Example**:

```jsonc
// input
{
  "displayName": "Ada Lovelace"
}
// → output
{
  "accountId": "acct_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, a2a, nlweb
- **REST endpoint**: `POST /api/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**: The email change currently in flight for this account, if any, and which address still has to confirm 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/account.email.change.pending`

**Example**:

```jsonc
// input
{}
// → output
{
  "pending": {
    "newEmail": "new@example.com",
    "requestedAt": "2026-08-26T12:00:00.000Z",
    "expiresAt": "2026-08-27T12:00:00.000Z",
    "awaitingOldAddress": true,
    "awaitingNewAddress": false
  }
}
// note: The new address confirmed; the old one has not.
```

##### `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, a2a, nlweb
- **REST endpoint**: `POST /api/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 endpoint**: `POST /api/v1/actions/account.passkey.register-challenge`

**Example**:

```jsonc
// input
{
  "nickname": "YubiKey 5C"
}
// → output
{
  "challenge": "abc...",
  "rp": {
    "id": "agined.com",
    "name": "Agined"
  },
  "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 endpoint**: `POST /api/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,
  "authenticatorAttachment": "cross-platform"
}
// 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, a2a, nlweb
- **REST endpoint**: `POST /api/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
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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 theme and timezone.
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/account.display-preferences.set`

**Example**:

```jsonc
// input
{
  "theme": "dark"
}
// → output
{
  "theme": "dark",
  "timezone": null
}
// note: Switch to the dark theme.
```

##### `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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/account.notifications.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "marketingEmails": false,
  "securityAlerts": true,
  "billingAlerts": true,
  "productUpdates": false,
  "agentSessionStarted": true,
  "agentSessionAnomaly": true,
  "shadowSessionStarted": true,
  "shadowDailyDigest": false,
  "invitationAlerts": true,
  "quotaWarnings": true,
  "privacyRightsAlerts": 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/account.notifications.update`

**Example**:

```jsonc
// input
{
  "agentSessionAnomaly": true
}
// → output
{
  "marketingEmails": false,
  "securityAlerts": true,
  "billingAlerts": true,
  "productUpdates": false,
  "agentSessionStarted": true,
  "agentSessionAnomaly": true,
  "shadowSessionStarted": true,
  "shadowDailyDigest": false,
  "invitationAlerts": true,
  "quotaWarnings": true,
  "privacyRightsAlerts": 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, a2a, nlweb
- **REST endpoint**: `POST /api/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: `mandate`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `key.issued`
- **Rate class**: `default`
- **Surfaces**: rest
- **REST endpoint**: `POST /api/v1/actions/account.token.issue`

**Example**:

```jsonc
// input
{
  "label": "CI pipeline",
  "scopes": [
    "read:workspace",
    "write:tools"
  ],
  "expiresInDays": 90
}
// → output
{
  "token": {
    "id": "av_pat_a1b2c3d4e5",
    "prefix": "av_pat_abc",
    "label": "CI pipeline",
    "scopes": [
      "read:workspace",
      "write:tools"
    ],
    "createdAt": "2026-05-22T12:00:00.000Z",
    "expiresAt": "2026-08-20T12:00:00.000Z",
    "lastUsedAt": null,
    "revokedAt": null,
    "ipCidrBinding": null,
    "last4": "9f2c"
  },
  "cleartext": "av_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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/account.token.revoke`

**Example**:

```jsonc
// input
{
  "tokenId": "av_pat_a1b2c3d4e5"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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 after a grace window (30 days by default). Organizations you solely own are scheduled with it; ones with other members are reported back instead. Requires WebAuthn step-up.
- **Safety**: `destructive` (confirmation policy: `mandate`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/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,
  "organizationsScheduled": [
    {
      "organizationId": "org_solo",
      "name": "Jake's Workspace"
    }
  ],
  "organizationsBlocked": [
    {
      "organizationId": "org_team",
      "name": "Acme Corp",
      "otherMemberCount": 4
    }
  ]
}
// note: Start account deletion with grace period; the shared org needs an ownership transfer first.
```

### `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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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": "acct_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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/org.member.remove`

**Example**:

```jsonc
// input
{
  "accountId": "acct_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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/org.member.role.change`

**Example**:

```jsonc
// input
{
  "accountId": "acct_demo00000000000000000000",
  "role": "admin"
}
// → output
{
  "accountId": "acct_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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/org.transfer-ownership`

**Example**:

```jsonc
// input
{
  "newOwnerAccountId": "acct_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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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: `mandate`)
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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: `mandate`)
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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: `mandate`)
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/org.sso.scim-tokens.mint`

**Example**:

```jsonc
// input
{
  "connectionId": "ssoc_abc"
}
// → output
{
  "id": "scimt_1",
  "connectionId": "ssoc_abc",
  "token": "scim_…",
  "scimBaseUrl": "https://auth.agined.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, a2a, nlweb
- **REST endpoint**: `POST /api/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 a paid plan).

##### `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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/workspace.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → output
{
  "id": "ws_demo_default",
  "name": "Default workspace",
  "organizationId": "org_demo00000000000000000000",
  "jurisdiction": "ENAM"
}
// 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/workspace.create`

**Example**:

```jsonc
// input
{
  "name": "EU production",
  "regionId": "cloudflare-d1:weur",
  "euJurisdictionBound": true
}
// → output
{
  "id": "ws_new0000000000",
  "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, Tools 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/workspace.update`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "toolsAutoOverageEnabled": true,
  "toolsAutoOverageCapMultiplier": 3
}
// → output
{
  "id": "ws_demo_default",
  "name": "Default",
  "organizationId": "org_demo",
  "jurisdiction": "WEUR"
}
// note: Enable Tools auto-overage with a 3× cap.
```

##### `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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/workspace.rename`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "name": "EU production v2"
}
// → output
{
  "id": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/workspace.delete.schedule`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "reason": "Migrated to new workspace; cleanup in progress"
}
// → output
{
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/workspace.delete.cancel`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → output
{
  "id": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/workspace.region.binding-proof`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/workspace.member.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → output
{
  "members": [
    {
      "accountId": "acct_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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/workspace.member.add`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "accountId": "acct_002demo000000000000000000",
  "role": "member"
}
// → output
{
  "accountId": "acct_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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/workspace.member.role.change`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "accountId": "acct_002demo000000000000000000",
  "role": "admin"
}
// → output
{
  "accountId": "acct_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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/workspace.member.remove`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "accountId": "acct_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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/workspace.transfer-ownership`

**Example**:

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

##### `workspace.attestor.enable`

- **Summary**: Enable Attestor on a workspace (requires an org-level Attestor 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/workspace.attestor.enable`

**Example**:

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

##### `workspace.attestor.disable`

- **Summary**: Disable Attestor 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/workspace.attestor.disable`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → output
{
  "id": "ws_demo_default",
  "name": "Default",
  "organizationId": "org_demo",
  "jurisdiction": "WEUR"
}
// note: Turn off Attestor 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/workspace.regions.list`

**Example**:

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

### `billing` (34 actions)

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

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

- **Summary**: Get the org's current 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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/billing.invoices.download`

**Example**:

```jsonc
// input
{
  "invoiceId": "in_abc"
}
// → output
{
  "url": "https://billing.example.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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/billing.payment-method.get`

**Example**:

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

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

- **Summary**: Get a signed URL to the hosted payment-method update page. The update happens there, not in Agined.
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/billing.payment-method.update-url`

**Example**:

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

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

- **Summary**: List available top-up packs (runs, Number One queries, Tools 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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/billing.packs.purchase`

**Example**:

```jsonc
// input
{
  "packId": "runs_1k",
  "workspaceId": "ws_demo_default"
}
// → output
{
  "checkoutUrl": "https://billing.example.com/c/pay/cs_test_REDACTED",
  "sessionId": "cs_test_REDACTED"
}
// note: Buy a 1k-run pack — complete payment at checkoutUrl; the credit lands via webhook.
```

##### `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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/billing.auto-topup.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/billing.auto-topup.configure`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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": [
    "tools"
  ],
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/billing.cost-centers.update`

**Example**:

```jsonc
// input
{
  "costCenterId": "cc_DEMO00000000000000000000",
  "monthlyCapUsdMinor": 50000
}
// → output
{
  "id": "cc_DEMO00000000000000000000",
  "organizationId": "org_demo00000000000000000000",
  "name": "Engineering",
  "taggableProducts": [
    "tools"
  ],
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/billing.cost-centers.delete`

**Example**:

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

##### `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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/billing.notarian.subscribe`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/billing.notarian.unsubscribe`

**Example**:

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

##### `billing.retention-extension.unsubscribe`

- **Summary**: Cancel the paid retention extension. Coverage continues until the paid-through date.
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/billing.retention-extension.unsubscribe`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → output
{
  "unsubscribed": true,
  "effectiveAt": "2026-09-22T00:00:00.000Z"
}
// note: Cancel the retention extension; coverage runs to the paid-through date.
```

##### `billing.multi-workspace.subscribe`

- **Summary**: Subscribe the organization to the multi-workspace add-on, allowing more than one workspace.
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/billing.multi-workspace.subscribe`

**Example**:

```jsonc
// input
{}
// → output
{
  "subscribed": true
}
// note: Buy the multi-workspace add-on.
```

##### `billing.multi-workspace.unsubscribe`

- **Summary**: Cancel the multi-workspace add-on at the end of the current 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/billing.multi-workspace.unsubscribe`

**Example**:

```jsonc
// input
{}
// → output
{
  "unsubscribed": true,
  "effectiveAt": "2026-09-22T00:00:00.000Z"
}
// note: Cancel the multi-workspace add-on.
```

##### `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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/billing.infinite-memory.subscribe`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/billing.infinite-memory.unsubscribe`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/billing.retention-extension.subscribe`

**Example**:

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

##### `billing.attestor.tier.set`

- **Summary**: Set the Attestor 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/billing.attestor.tier.set`

**Example**:

```jsonc
// input
{
  "tier": "scale"
}
// → output
{
  "subscriptionId": "sub_atst_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 Attestor tier.
```

##### `billing.attestor.tier.get`

- **Summary**: Get the current Attestor 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/billing.attestor.tier.get`

**Example**:

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

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

- **Summary**: Purchase an Attestor 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/billing.attestor.top-up.purchase`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "packId": "attestor_100k"
}
// → output
{
  "topUpId": "tu_atst_abc",
  "workspaceId": "ws_demo_default",
  "packKind": "attestor-calls",
  "unitCount": 100000,
  "priceUsdMinor": 1900,
  "purchasedAt": "2026-05-22T12:00:00.000Z",
  "unitsRemaining": 100000,
  "forfeitedAt": null
}
// note: Buy 100k Attestor calls.
```

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

- **Summary**: Configure auto-overage for an Attestor-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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/billing.attestor.auto-overage.set`

**Example**:

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

##### `billing.attestor.billing-mode.set`

- **Summary**: Set the Attestor billing mode (combined vs separate 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/billing.attestor.billing-mode.set`

**Example**:

```jsonc
// input
{
  "mode": "separate"
}
// → output
{
  "mode": "separate"
}
// note: Separate subscriptions for Agined + Attestor.
```

##### `billing.attestor.usage.current`

- **Summary**: Get current Attestor 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/billing.attestor.usage.current`

**Example**:

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

##### `billing.ledger-bundles.subscribe`

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

**Example**:

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

##### `billing.ledger-bundles.unsubscribe`

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

**Example**:

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

### `keys` (13 actions)

Personal access tokens (`av_pat_*`) + workspace API keys (`av_*` control plane, `atst_*` Attestor 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/keys.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/keys.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "keyId": "av_workspace_abc20charsforexampleid"
}
// → output
{
  "id": "av_workspace_abc20charsforexampleid",
  "workspaceId": "ws_demo_default",
  "product": "agined",
  "label": "Prod key",
  "prefix": "av_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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/keys.issue`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "product": "agined",
  "label": "Prod ingest key",
  "scopes": [
    "ingest:write"
  ],
  "expiry": "1y"
}
// → output
{
  "key": {
    "id": "av_workspace_abc20charsforexampleid",
    "workspaceId": "ws_demo_default",
    "product": "agined",
    "label": "Prod ingest key",
    "prefix": "av_abc",
    "scopes": [
      "ingest:write"
    ],
    "createdAt": "2026-05-22T12:00:00.000Z",
    "lastUsedAt": null,
    "expiresAt": "2027-05-22T12:00:00.000Z",
    "revokedAt": null
  },
  "cleartext": "av_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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/keys.revoke`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "keyId": "av_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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/keys.rotate`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "keyId": "av_workspace_abc20charsforexampleid"
}
// → output
{
  "revokedKeyId": "av_workspace_abc20charsforexampleid",
  "newKey": {
    "id": "av_workspace_def20charsforexampleid",
    "workspaceId": "ws_demo_default",
    "product": "agined",
    "label": "Prod ingest key",
    "prefix": "av_def",
    "scopes": [
      "ingest:write"
    ],
    "createdAt": "2026-05-22T12:00:00.000Z",
    "lastUsedAt": null,
    "expiresAt": null,
    "revokedAt": null
  },
  "cleartext": "av_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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/keys.scopes.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "scopes": [
    {
      "id": "ingest:write",
      "product": "agined",
      "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/keys.usage.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "keyId": "av_workspace_abc20charsforexampleid"
}
// → output
{
  "totalCalls": 12345,
  "uniqueIpCidrs": 3,
  "lastUsedAt": "2026-05-22T12:00:00.000Z",
  "perEndpointBreakdown": [
    {
      "path": "/api/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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/keys.last-used.get`

**Example**:

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

##### `keys.attestor.list`

- **Summary**: Convenience: list only the Attestor-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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/keys.attestor.list`

**Example**:

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

##### `keys.attestor.issue`

- **Summary**: Issue an Attestor-product workspace key (atst_*). 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/keys.attestor.issue`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "label": "Attestor attestation key",
  "scopes": [
    "attestor:agent-call:write",
    "attestor:content-attest:write"
  ],
  "expiry": "90d"
}
// → output
{
  "key": {
    "id": "atst_workspace_abc20charsforexampleid",
    "workspaceId": "ws_demo_default",
    "product": "attestor",
    "label": "Attestor attestation key",
    "prefix": "atst_abc",
    "scopes": [
      "attestor:agent-call:write",
      "attestor:content-attest:write"
    ],
    "createdAt": "2026-05-22T12:00:00.000Z",
    "lastUsedAt": null,
    "expiresAt": "2026-08-20T12:00:00.000Z",
    "revokedAt": null
  },
  "cleartext": "atst_abc_REDACTED_EXAMPLE_ONLY"
}
// note: Mint an Attestor key.
```

##### `keys.ingest-secret.list`

- **Summary**: List this workspace's ingest secrets (metadata only — never the secret value).
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/keys.ingest-secret.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → output
{
  "secrets": [
    {
      "id": "wis_abc123",
      "workspaceId": "ws_demo_default",
      "platformId": "webhook:vapi",
      "createdAt": "2026-09-03T12:00:00.000Z",
      "revokedAt": null
    }
  ]
}
// note: See which platforms can deliver.
```

##### `keys.ingest-secret.issue`

- **Summary**: Issue an ingest secret for a platform. Any active secret for that platform is revoked. 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/keys.ingest-secret.issue`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "platformId": "webhook:vapi"
}
// → output
{
  "secret": {
    "id": "wis_def456",
    "workspaceId": "ws_demo_default",
    "platformId": "webhook:vapi",
    "createdAt": "2026-09-03T12:00:00.000Z",
    "revokedAt": null
  },
  "cleartext": "wis_REDACTED_EXAMPLE_ONLY",
  "revokedSecretId": null
}
// note: Generate the secret a Vapi webhook signs with.
```

##### `keys.ingest-secret.revoke`

- **Summary**: Revoke an ingest secret without issuing a replacement. Deliveries for that platform then fail closed.
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/keys.ingest-secret.revoke`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "secretId": "wis_def456",
  "reason": "Rotating after a partner offboarding."
}
// → output
{
  "revoked": true,
  "secretId": "wis_def456",
  "revokedAt": "2026-09-03T12:00:00.000Z"
}
// note: Stop accepting deliveries for a platform.
```

### `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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/webhooks.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/webhooks.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "webhookId": "wh_DEMO00000000000000000000"
}
// → output
{
  "id": "wh_DEMO00000000000000000000",
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/webhooks.create`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "url": "https://example.com/webhook",
  "label": "Prod hook",
  "events": [
    "alert.fired",
    "export.ready"
  ]
}
// → output
{
  "webhook": {
    "id": "wh_DEMO00000000000000000000",
    "workspaceId": "ws_demo_default",
    "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/webhooks.update`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "webhookId": "wh_DEMO00000000000000000000",
  "events": [
    "alert.fired"
  ]
}
// → output
{
  "id": "wh_DEMO00000000000000000000",
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/webhooks.delete`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/webhooks.enable`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "webhookId": "wh_DEMO00000000000000000000",
  "enabled": false
}
// → output
{
  "id": "wh_DEMO00000000000000000000",
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/webhooks.test-fire`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/webhooks.events.replay`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/webhooks.signing-secret.rotate`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/webhooks.deliveries.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/webhooks.deliveries.retry`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/alerts.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/alerts.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "alertId": "alert_DEMO00000000000000000000"
}
// → output
{
  "id": "alert_DEMO00000000000000000000",
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/alerts.create`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "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_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/alerts.update`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "alertId": "alert_DEMO00000000000000000000",
  "label": "Renamed"
}
// → output
{
  "id": "alert_DEMO00000000000000000000",
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/alerts.delete`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/alerts.enable`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "alertId": "alert_DEMO00000000000000000000"
}
// → output
{
  "id": "alert_DEMO00000000000000000000",
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/alerts.disable`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "alertId": "alert_DEMO00000000000000000000"
}
// → output
{
  "id": "alert_DEMO00000000000000000000",
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/alerts.test-fire`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/alerts.history.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/exports.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/exports.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "exportId": "exp_abc"
}
// → output
{
  "exportId": "exp_abc",
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/exports.request`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/exports.download`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "exportId": "exp_abc"
}
// → output
{
  "url": "https://r2.agined.com/exports/abc",
  "expiresAt": "2026-05-22T13:00:00.000Z",
  "sha256": "abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab"
}
// 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/exports.verify`

**Example**:

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

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

- **Summary**: Request a portable Attestor-receipt bundle — JSON manifest + receipt files + public key JWK + verify README. Verifiable with @attestor/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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/exports.attestor.receipt-bundle.request`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "primitiveFilter": [
    "agent.call",
    "content.attest"
  ]
}
// → output
{
  "exportId": "exp_atst_abc",
  "estimatedReadyAt": "2026-05-22T12:15:00.000Z"
}
// note: Bundle Attestor 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/exports.eu-ai-act.article-12.request`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/exports.audit-log.request`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/exports.delete`

**Example**:

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

### `retention` (12 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/retention.policy.get`

**Example**:

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

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

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

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "retentionDays": 730
}
// → output
{
  "workspaceId": "ws_demo_default",
  "retentionDays": 730,
  "isCustom": true,
  "appliedAt": "2026-05-22T12:00:00.000Z",
  "appliedBy": "extension"
}
// 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/retention.histogram.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/retention.next-purge.preview`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/retention.purge-history.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/retention.extension.subscribe`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "extendedToDays": 1095
}
// → output
{
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/retention.extension.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → output
null
// note: Workspace has no extension subscription.
```

##### `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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/retention.extension.update`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "extendedToDays": 1825
}
// → output
{
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/retention.extension.cancel`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → output
{
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/retention.policy.suggested-tier.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/retention.audit.list`

**Example**:

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

### `audit` (19 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/audit.workspace.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/audit.workspace.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "entryId": "aud_9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f"
}
// → output
{
  "id": "aud_9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/audit.workspace.search`

**Example**:

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

##### `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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/audit.workspace.share`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "entryId": "aud_9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "ttlHours": 24,
  "note": "Q3 audit — Foo & Co LLP"
}
// → output
{
  "shareUrl": "https://agined.com/audit/share/abc",
  "expiresAt": "2026-05-23T12:00:00.000Z",
  "shareId": "9f2c1a7b3e4d5f60"
}
// note: Share with auditor.
```

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

- **Summary**: List the audit share links minted for this workspace, with their expiry and revocation state.
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/audit.workspace.shares.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "includeInactive": false
}
// → output
{
  "shares": [
    {
      "shareId": "9f2c1a7b3e4d5f60",
      "tokenPrefix": "abc12345",
      "entryId": "aud_9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
      "note": "Q3 audit — Foo & Co LLP",
      "createdAt": "2026-05-22T12:00:00.000Z",
      "createdBy": "acct_demo",
      "expiresAt": "2026-05-23T12:00:00.000Z",
      "revokedAt": null,
      "active": true
    }
  ]
}
// note: See what is still shared.
```

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

- **Summary**: Revoke an audit share link immediately, before its expiry.
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/audit.workspace.share.revoke`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "shareId": "9f2c1a7b3e4d5f60"
}
// → output
{
  "shareId": "9f2c1a7b3e4d5f60",
  "revoked": true,
  "revokedAt": "2026-05-22T18:00:00.000Z"
}
// note: Kill a leaked share.
```

##### `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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/audit.custody.list`

**Example**:

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

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

- **Summary**: Get a custody entry by id (hash-chained via prevHash→entryHash; per-entry signature is optional — the Ed25519 seal covers a range, not each entry).
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/audit.custody.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "entryId": "cust_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}
// → output
{
  "id": "cust_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "workspaceId": "ws_demo_default",
  "seq": 42,
  "sourceAuditId": "aud_9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "action": "workspace.settings.update",
  "actorDid": "did:web:agined.com:accounts:acc_demo00000000000000000000",
  "payload": {
    "field": "retentionDays",
    "from": 30,
    "to": 90
  },
  "rowHash": "1111567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "recordedAt": "2026-05-22T12:00:00.000Z",
  "timestamp": "2026-05-22T12:00:00.000Z",
  "prevHash": "0000000000000000000000000000000000000000000000000000000000000000",
  "entryHash": "abcd567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "signature": "...",
  "signingKeyId": "tools-2026-q2-enam"
}
// note: Fetch a custody entry.
```

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

- **Summary**: List Tops feed entries (hash-chained per entry; authenticity is the periodically Ed25519-signed + OTS Bitcoin-anchored SEAL ROOT — per-entry signature is null until its seal exists).
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/audit.tops.list`

**Example**:

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

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

- **Summary**: Verify the hash chain of this workspace's 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/audit.tops.verify`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "fromEntryId": "1024",
  "toEntryId": "2048"
}
// → output
{
  "chainValid": true,
  "signaturesValid": true,
  "otsValid": true,
  "errors": [],
  "entriesChecked": 1284,
  "truncated": false
}
// note: Verify a Tops range end-to-end.
```

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

- **Summary**: List Agined-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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/audit.shadow-sessions.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → output
{
  "sessions": [],
  "nextCursor": null
}
// note: List Agined-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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/audit.shadow-sessions.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "sessionId": "shadow_abc"
}
// → output
{
  "session": {
    "sessionId": "shadow_abc",
    "workspaceId": "ws_demo_default",
    "accountId": "acct_demo00000000000000000000",
    "operatorDid": "did:web:agined.com:operators:ops_demo",
    "origin": "support-console",
    "costCenterId": null,
    "createdAt": "2026-05-22T12:00:00.000Z",
    "expiresAt": "2026-05-22T14:00:00.000Z",
    "lastUsedAt": "2026-05-22T12:31:00.000Z",
    "revokedAt": null,
    "revokeReason": null,
    "ipAddress": "203.0.113.7",
    "userAgent": "Mozilla/5.0"
  },
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/audit.aggregate`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/audit.export.scoped`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/audit.outside-access.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/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: `mandate`)
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/audit.stream.configure`

**Example**:

```jsonc
// input
{
  "kind": "splunk_hec",
  "displayName": "SOC Splunk",
  "endpoint": "https://http-inputs.splunkcloud.com",
  "token": "hec-…"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/audit.stream.delete`

**Example**:

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

### `tops` (15 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/tops.config.get`

**Example**:

```jsonc
// input
{
  "scope": "workspace",
  "scopeId": "ws_demo_default"
}
// → output
{
  "scope": "workspace",
  "scopeId": "ws_demo_default",
  "enabled": true,
  "kinds": [
    "admin_read",
    "key_issue"
  ],
  "environments": [
    "production"
  ],
  "samplingPercent": 100,
  "detailLevel": "safe",
  "updatedAt": "2026-05-22T12:00:00.000Z",
  "updatedBy": "acct_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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/tops.config.set`

**Example**:

```jsonc
// input
{
  "scope": "workspace",
  "scopeId": "ws_demo_default",
  "enabled": true,
  "kinds": [
    "admin_read",
    "key_issue"
  ],
  "environments": [
    "production"
  ],
  "samplingPercent": 100,
  "detailLevel": "extended"
}
// → output
{
  "scope": "workspace",
  "scopeId": "ws_demo_default",
  "enabled": true,
  "kinds": [
    "admin_read",
    "key_issue"
  ],
  "environments": [
    "production"
  ],
  "samplingPercent": 100,
  "detailLevel": "extended",
  "updatedAt": "2026-05-22T12:00:00.000Z",
  "updatedBy": "acct_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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/tops.config.delete`

**Example**:

```jsonc
// input
{
  "scope": "workspace",
  "scopeId": "ws_demo_default"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/tops.config.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/tops.config.cascade.resolve`

**Example**:

```jsonc
// input
{
  "organizationId": "org_demo00000000000000000000",
  "workspaceId": "ws_demo_default"
}
// → output
{
  "effectiveConfig": {
    "scope": "workspace",
    "scopeId": "ws_demo_default",
    "enabled": true,
    "kinds": [
      "admin_read"
    ],
    "environments": [
      "production"
    ],
    "samplingPercent": 100,
    "detailLevel": "safe",
    "updatedAt": "2026-05-22T12:00:00.000Z",
    "updatedBy": "acct_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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/tops.config.preset.apply`

**Example**:

```jsonc
// input
{
  "scope": "workspace",
  "scopeId": "ws_demo_default",
  "presetId": "recommended"
}
// → output
{
  "scope": "workspace",
  "scopeId": "ws_demo_default",
  "enabled": true,
  "kinds": [
    "ingest",
    "export",
    "key_issue",
    "admin_read",
    "spot_decide"
  ],
  "environments": [
    "production"
  ],
  "samplingPercent": 100,
  "detailLevel": "safe",
  "updatedAt": "2026-05-22T12:00:00.000Z",
  "updatedBy": "acct_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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/tops.config.presets.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "presets": [
    {
      "id": "minimal",
      "label": "Minimal",
      "description": "Smallest footprint; just the essentials.",
      "config": {
        "enabled": true,
        "kinds": [
          "ingest",
          "export"
        ],
        "environments": [
          "production"
        ],
        "samplingPercent": 10,
        "detailLevel": "safe"
      },
      "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/tops.config.testbed.run`

**Example**:

```jsonc
// input
{
  "organizationId": "org_demo00000000000000000000",
  "workspaceId": "ws_demo_default",
  "actorId": "actor_demo00000000000000000000",
  "syntheticEvent": {
    "kind": "admin_read"
  }
}
// → output
{
  "resolved": {
    "scope": "workspace",
    "scopeId": "ws_demo_default",
    "enabled": true,
    "kinds": [
      "admin_read"
    ],
    "environments": [
      "production"
    ],
    "samplingPercent": 100,
    "detailLevel": "safe",
    "updatedAt": "2026-05-22T12:00:00.000Z",
    "updatedBy": "acct_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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/tops.config.change-history.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "changes": [
    {
      "id": "0f4a2b1c-0000-4000-8000-000000000000",
      "scope": "workspace",
      "scopeId": "ws_demo_default",
      "changedAt": "2026-05-22T12:00:00.000Z",
      "change": {
        "op": "set",
        "before": {
          "enabled": true,
          "kinds": [
            "admin_read"
          ],
          "environments": [
            "production"
          ],
          "samplingPercent": 100,
          "detailLevel": "safe"
        },
        "after": {
          "enabled": true,
          "kinds": [
            "admin_read"
          ],
          "environments": [
            "production"
          ],
          "samplingPercent": 100,
          "detailLevel": "forensic"
        },
        "detailLevel": "forensic",
        "by": "acct_demo00000000000000000000"
      }
    }
  ],
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/tops.config.sparkline.get`

**Example**:

```jsonc
// input
{
  "scope": "workspace",
  "scopeId": "ws_demo_default"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/tops.config.audit-cross-links.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/tops.config.cooldown-status.get`

**Example**:

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

##### `tops.specimen.get`

- **Summary**: Read this workspace's public trust page settings. `null` when nothing has ever been published.
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/tops.specimen.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "page": null
}
// note: Nothing published.
```

##### `tops.specimen.set`

- **Summary**: Claim or rename the workspace's public handle, and turn the page on or off.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `settings.edit_capabilities`
- **Audit kind**: `agent_invocation`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/tops.specimen.set`

**Example**:

```jsonc
// input
{
  "handle": "acme",
  "enabled": false
}
// → output
{
  "page": {
    "handle": "acme",
    "enabled": false,
    "createdAt": "2026-09-03T00:00:00.000Z",
    "updatedAt": "2026-09-03T00:00:00.000Z"
  }
}
// note: Claim the handle without publishing yet.
```

##### `tops.specimen.delete`

- **Summary**: Take the public page down and RELEASE the handle for anyone else to claim.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `settings.edit_capabilities`
- **Audit kind**: `agent_invocation`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/tops.specimen.delete`

**Example**:

```jsonc
// input
{}
// → output
{
  "deleted": true
}
// note: Unpublish.
```

### `referrals` (12 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/referrals.code.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "code": "DEMO12",
  "shareUrl": "https://agined.com/?ref=DEMO12",
  "qrCodeDataUrl": "data:image/png;base64,...",
  "shareMessage": null
}
// 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/referrals.code.regenerate`

**Example**:

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

##### `referrals.share-message.set`

- **Summary**: Set the message shared alongside your referral link.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/referrals.share-message.set`

**Example**:

```jsonc
// input
{
  "message": "I use Agined to run my agents — sign up with my link."
}
// → output
{
  "message": "I use Agined to run my agents — sign up with my link."
}
// note: Replace your share message.
```

##### `referrals.share.record`

- **Summary**: Record that you shared your referral link, and where.
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/referrals.share.record`

**Example**:

```jsonc
// input
{
  "channel": "slack"
}
// → output
{
  "recorded": true,
  "channel": "slack"
}
// note: Record a share to Slack.
```

##### `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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/referrals.funnel.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "sent": 50,
  "clicked": 30,
  "joined": 12,
  "redeemed": 8,
  "joinRate": 0.4,
  "redeemRate": 0.6667,
  "channelBreakdown": [
    {
      "channel": "slack",
      "sent": 30,
      "clicked": 20
    }
  ]
}
// 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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/referrals.ledger.list`

**Example**:

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

### `number_one` (18 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/number_one.conversation.create`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "mode": "analyst",
  "title": "Q3 audit review"
}
// → output
{
  "conversationId": "conv_demo0000000000A",
  "workspaceId": "ws_demo_default",
  "mode": "analyst",
  "title": "Q3 audit review",
  "startedAt": "2026-05-22T12:00:00.000Z",
  "lastActivityAt": "2026-05-22T12:00:00.000Z",
  "messageCount": 0,
  "preview": ""
}
// 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/number_one.conversation.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/number_one.conversation.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "conversationId": "conv_demo0000000000A"
}
// → output
{
  "conversation": {
    "conversationId": "conv_demo0000000000A",
    "workspaceId": "ws_demo_default",
    "mode": "analyst",
    "title": "Q3 audit review",
    "startedAt": "2026-05-22T12:00:00.000Z",
    "lastActivityAt": "2026-05-22T12:00:00.000Z",
    "messageCount": 0,
    "preview": ""
  },
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/number_one.conversation.delete`

**Example**:

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

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

- **Summary**: Send a user message in a Number One conversation. Returns the full buffered assistant turn.
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/number_one.message.send`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "conversationId": "conv_demo0000000000A",
  "body": "What was my Tools usage last week?"
}
// → output
{
  "sessionId": "conv_demo0000000000A",
  "assistantMessageId": "no_mem_demo0000000000A",
  "decision": "calculator",
  "assistantBody": "Your workspace ran 42 checks last week.",
  "contentOrigin": "computed",
  "quotaCostUnits": 1,
  "memory": {
    "usedBytes": 529,
    "capBytes": 52428800,
    "infinite": false,
    "capExceeded": 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/number_one.message.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "conversationId": "conv_demo0000000000A"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/number_one.mode.set`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "conversationId": "conv_demo0000000000A",
  "mode": "admin"
}
// → output
{
  "conversationId": "conv_demo0000000000A",
  "workspaceId": "ws_demo_default",
  "mode": "admin",
  "title": "Q3 audit review",
  "startedAt": "2026-05-22T12:00:00.000Z",
  "lastActivityAt": "2026-05-22T12:00:00.000Z",
  "messageCount": 5,
  "preview": "Done — 3 monitors active."
}
// 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/number_one.memory.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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. Pass factId to re-pin an existing fact, or text (optionally with conversationId provenance) to create + pin a new one.
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/number_one.memory.pin`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "factId": "fact_demo0000000000A"
}
// → output
{
  "factId": "fact_demo0000000000A",
  "workspaceId": "ws_demo_default",
  "text": "Q3 audit is led by Foo & Co LLP",
  "pinned": true,
  "learnedFrom": "user",
  "learnedAt": "2026-05-22T12:00:00.000Z",
  "reinforcedAt": "2026-05-23T09:00:00.000Z",
  "conversationId": null
}
// note: Re-pin an existing 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/number_one.memory.unpin`

**Example**:

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

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

- **Summary**: Permanently erase a memory-ledger turn's content (ADR-014 marker — the redaction cannot be undone). memoryId is a message id from message.list; pinned facts are managed via memory.unpin instead.
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/number_one.memory.erase`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "memoryId": "no_mem_demo0000000000A"
}
// → output
{
  "erased": true
}
// note: Erase a remembered turn's content.
```

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

- **Summary**: Get the workspace's memory usage + cap. The ledger is byte-capped (Z-07); capBytes is -1 when the 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/number_one.memory.cap.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → output
{
  "usedBytes": 529,
  "capBytes": 52428800,
  "infinite": false
}
// note: Read memory usage + cap.
```

##### `number_one.llm-billing.get`

- **Summary**: Read whether this workspace's Number One calls run on Agined's LLM key (metered) or on its own provider key (BYOK, not metered).
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/number_one.llm-billing.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → output
{
  "mode": "agined_billed",
  "keyAvailable": false,
  "metered": true
}
// note: Read the billing posture.
```

##### `number_one.llm-billing.set`

- **Summary**: Choose whether this workspace's Number One calls run on Agined's LLM key (metered) or on its own provider key (BYOK, not metered).
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `billing.change_plan`
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/number_one.llm-billing.set`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "mode": "byok"
}
// → output
{
  "mode": "byok",
  "keyAvailable": true,
  "metered": false
}
// note: Run on our own key.
```

##### `number_one.analyst.get`

- **Summary**: Read whether Analyst mode is enabled for this 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/number_one.analyst.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → output
{
  "enabled": true
}
// note: Is Analyst on?
```

##### `number_one.analyst.set`

- **Summary**: Turn Analyst mode on or off for everyone in this workspace.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `settings.edit_capabilities`
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/number_one.analyst.set`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "enabled": false
}
// → output
{
  "enabled": false
}
// note: Disable Analyst for the workspace.
```

##### `number_one.assistant-posture.get`

- **Summary**: Read which posture the assistant runs in for this workspace — membrane-protected, in-boundary or off — and which model provider its calls go to.
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/number_one.assistant-posture.get`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → output
{
  "posture": "membrane-protected",
  "provider": null,
  "membraneKeyConfigured": true,
  "inBoundaryConfigured": false
}
// note: Read the assistant posture.
```

##### `number_one.assistant-posture.set`

- **Summary**: Choose the assistant's posture for this workspace, and which model provider its calls go to.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `settings.edit_capabilities`
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/number_one.assistant-posture.set`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "posture": "off"
}
// → output
{
  "posture": "off",
  "provider": null,
  "membraneKeyConfigured": true,
  "inBoundaryConfigured": false
}
// note: Disable the assistant workspace-wide.
```

### `attestor` (30 actions)

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

##### `attestor.attest.agent-call`

- **Summary**: Issue an Attestor receipt for an agent.call primitive (outbound API call by a customer's agent).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `attestor.attest.agent-call`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/attestor.attest.agent-call`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "destination": "https://api.stripe.com/v1/charges",
  "method": "POST",
  "requestBodySha256": "abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd",
  "responseBodySha256": "abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890abce",
  "responseStatus": 200,
  "durationMs": 387,
  "agentId": "billing-bot",
  "purpose": "refund_processing"
}
// → output
{
  "receiptId": "01H8X4P9R7Z2C1A1F2A8VBJYV2",
  "workspaceId": "ws_demo_default",
  "kind": "agent.call",
  "issuedAt": "2026-05-22T12:00:00.000Z",
  "signature": "...",
  "signatureKeyId": "attestor-2026-q2-enam",
  "body": {}
}
// note: Attest an agent call.
```

##### `attestor.attest.content`

- **Summary**: Attest a content blob (text, image hash, document). Returns a signed receipt.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `attestor.attest.content`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/attestor.attest.content`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "contentSha256": "abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd",
  "contentType": "text/plain",
  "purpose": "marketing_copy_approval"
}
// → output
{
  "receiptId": "01H8X4P9R7Z2C1A1F2A8VBJYV3",
  "workspaceId": "ws_demo_default",
  "kind": "content.attest",
  "issuedAt": "2026-05-22T12:00:00.000Z",
  "signature": "...",
  "signatureKeyId": "attestor-2026-q2-enam",
  "body": {}
}
// note: Attest content.
```

##### `attestor.attest.llm`

- **Summary**: Attest an LLM inference (model + prompt hash + response hash + provider).
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `attestor.attest.llm`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/attestor.attest.llm`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "modelId": "claude-opus-4.7",
  "providerId": "anthropic",
  "promptSha256": "abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd",
  "responseSha256": "abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890abce",
  "latencyMs": 1500,
  "promptTokens": 1200,
  "completionTokens": 850
}
// → output
{
  "receiptId": "01H8X4P9R7Z2C1A1F2A8VBJYV4",
  "workspaceId": "ws_demo_default",
  "kind": "llm.attest",
  "issuedAt": "2026-05-22T12:00:00.000Z",
  "signature": "...",
  "signatureKeyId": "attestor-2026-q2-enam",
  "body": {}
}
// note: Attest LLM call.
```

##### `attestor.attest.commit`

- **Summary**: Attest a Git commit (commit hash + author + repo URL). Pairs with the @attestor/attest-commit GitHub Action.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `attestor.attest.commit`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/attestor.attest.commit`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "commitSha": "abc1234567890abcdef1234567890abcdef1234567",
  "repoUrl": "https://github.com/example/repo",
  "author": "alice@example.com",
  "message": "Refactor billing service"
}
// → output
{
  "receiptId": "01H8X4P9R7Z2C1A1F2A8VBJYV5",
  "workspaceId": "ws_demo_default",
  "kind": "commit.attest",
  "issuedAt": "2026-05-22T12:00:00.000Z",
  "signature": "...",
  "signatureKeyId": "attestor-2026-q2-enam",
  "body": {}
}
// note: Attest a Git commit.
```

##### `attestor.deliver.webhook`

- **Summary**: Issue a receipt for an outbound webhook delivery attempt.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `attestor.deliver.webhook`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/attestor.deliver.webhook`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "webhookId": "wh_abc",
  "destination": "https://example.com/webhook",
  "payloadSha256": "abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd",
  "statusCode": 200,
  "attemptNumber": 1
}
// → output
{
  "receiptId": "01H8X4P9R7Z2C1A1F2A8VBJYV6",
  "workspaceId": "ws_demo_default",
  "kind": "webhook.deliver",
  "issuedAt": "2026-05-22T12:00:00.000Z",
  "signature": "...",
  "signatureKeyId": "attestor-2026-q2-enam",
  "body": {}
}
// note: Attest webhook delivery.
```

##### `attestor.monitor.http.add`

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

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "url": "https://api.example.com/health",
  "intervalSeconds": 60
}
// → output
{
  "monitorId": "mon_demo00000000000000000000",
  "workspaceId": "ws_demo_default",
  "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.
```

##### `attestor.monitor.http.list`

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

**Example**:

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

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

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

**Example**:

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

##### `attestor.monitor.http.remove`

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

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "monitorId": "mon_demo00000000000000000000"
}
// → output
{
  "deleted": true
}
// note: Delete monitor.
```

##### `attestor.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**: `attestor.dns.create`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/attestor.watch.dns.add`

**Example**:

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

##### `attestor.watch.dns.list`

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

**Example**:

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

##### `attestor.watch.dns.remove`

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

**Example**:

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

##### `attestor.watch.tls.add`

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

**Example**:

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

##### `attestor.watch.tls.list`

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

**Example**:

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

##### `attestor.watch.tls.remove`

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

**Example**:

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

##### `attestor.receipt.list`

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

**Example**:

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

##### `attestor.receipt.get`

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

**Example**:

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

##### `attestor.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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/attestor.receipt.verify`

**Example**:

```jsonc
// input
{
  "receipt": {
    "receiptId": "01H8X4P9R7Z2C1A1F2A8VBJYV2",
    "workspaceId": "ws_demo_default",
    "kind": "agent.call",
    "issuedAt": "2026-05-22T12:00:00.000Z",
    "signature": "...",
    "signatureKeyId": "attestor-2026-q2-enam",
    "body": {}
  }
}
// → output
{
  "valid": true,
  "signatureValid": true,
  "publishedKeyUrl": "https://agined.com/.well-known/attestor-keys.json",
  "errors": []
}
// note: Verify a receipt.
```

##### `attestor.usage.current`

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

**Example**:

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

##### `attestor.usage.historical`

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

**Example**:

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

##### `attestor.subscription.get`

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

**Example**:

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

##### `attestor.subscription.cancel`

- **Summary**: Cancel the Attestor 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/attestor.subscription.cancel`

**Example**:

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

##### `attestor.abuse-status.get`

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

**Example**:

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

##### `attestor.abuse-status.appeal`

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

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "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.
```

##### `attestor.signing-key.get`

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

**Example**:

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

##### `attestor.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**: `attestor.subscription.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/attestor.signing-key.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → output
{
  "keys": [
    {
      "signingKeyId": "attestor-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.
```

##### `attestor.signing-key.rotate-request`

- **Summary**: Request signing-key rotation (Enterprise tier dedicated keys only). Agined ops fulfils via key ceremony.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `attestor.subscription.view`
- **Audit kind**: `admin.action`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/attestor.signing-key.rotate-request`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "reason": "Q4 scheduled rotation per our internal policy"
}
// → output
{
  "requestId": "rot_abc",
  "estimatedRotationAt": "2026-06-01T00:00:00.000Z"
}
// note: Request key rotation.
```

##### `attestor.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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/attestor.signing-key.public.get`

**Example**:

```jsonc
// input
{
  "signingKeyId": "attestor-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.
```

##### `attestor.status.get`

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

**Example**:

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

##### `attestor.attestation-feed.get`

- **Summary**: Get the daily Attestor self-attestation receipt feed (Agined 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/attestor.attestation-feed.get`

**Example**:

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

### `starfleet` (7 actions)

Starfleet spot-actor roster (witness/council/historian/custodian/conscience/…) + the per-workspace run ledger — post runs, list/diff/replay them, verify the hash-chain.

##### `starfleet.run`

- **Summary**: Post a run to a Starfleet 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/starfleet.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.
```

##### `starfleet.runs.list`

- **Summary**: List the workspace's Starfleet 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/starfleet.runs.list`

**Example**:

```jsonc
// input
{
  "actor": "witness",
  "limit": 20
}
// → output
{
  "runs": [],
  "count": 0
}
// note: Recent witness runs.
```

##### `starfleet.actors.list`

- **Summary**: List the Starfleet 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/starfleet.actors.list`

**Example**:

```jsonc
// input
{
  "version": "v1"
}
// → output
{
  "actors": [
    {
      "id": "witness",
      "version": "v1",
      "minTier": "free"
    }
  ]
}
// note: Discover v1 actors.
```

##### `starfleet.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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/starfleet.agents.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "agents": [],
  "count": 0
}
// note: Who's posting runs.
```

##### `starfleet.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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/starfleet.runs.verify-chain`

**Example**:

```jsonc
// input
{
  "from": 1
}
// → output
{
  "ok": true
}
// note: Prove the chain is intact.
```

##### `starfleet.runs.diff`

- **Summary**: Compare two Starfleet 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/starfleet.runs.diff`

**Example**:

```jsonc
// input
{
  "a": "run_abc",
  "b": "run_def"
}
// → output
{
  "ok": true
}
// note: Diff two runs.
```

##### `starfleet.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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/starfleet.runs.replay`

**Example**:

```jsonc
// input
{
  "runId": "run_abc"
}
// → output
{
  "ok": true,
  "found": true
}
// note: Replay a run.
```

### `ledger-bundles` (3 actions)

LedgerBundles signed snapshots + transparency-chain verification (a snapshot is a paid action).

##### `ledger-bundles.snapshot.create`

- **Summary**: Create a signed LedgerBundles 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/ledger-bundles.snapshot.create`

**Example**:

```jsonc
// input
{
  "scope": "month-end"
}
// → output
{}
// note: Seal a signed snapshot.
```

##### `ledger-bundles.verify-chain`

- **Summary**: Verify the LedgerBundles 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/ledger-bundles.verify-chain`

**Example**:

```jsonc
// input
{}
// → output
{}
// note: Prove the chain is intact.
```

##### `ledger-bundles.anchors.list`

- **Summary**: List the LedgerBundles 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/ledger-bundles.anchors.list`

**Example**:

```jsonc
// input
{}
// → output
{}
// note: List anchors.
```

### `privacy` (6 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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/privacy.export.download`

**Example**:

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

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

- **Summary**: List the data-subject rights Agined 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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/support.tickets.create`

**Example**:

```jsonc
// input
{
  "subject": "Issue with Tools receipt verification",
  "body": "Hi — I'm seeing a signature_invalid error when verifying receipts from workspace ws_X. Could you take a look?",
  "priority": "medium"
}
// → output
{
  "ticketId": "tkt_abc",
  "subject": "Issue with Tools receipt verification",
  "status": "open",
  "priority": "medium",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/support.tickets.get`

**Example**:

```jsonc
// input
{
  "ticketId": "tkt_abc"
}
// → output
{
  "ticket": {
    "ticketId": "tkt_abc",
    "subject": "Issue",
    "status": "open",
    "priority": "medium",
    "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/support.tickets.reply`

**Example**:

```jsonc
// input
{
  "ticketId": "tkt_abc",
  "body": "Thanks — here's the receipt hash …"
}
// → output
{
  "replyId": "rep_abc",
  "ticketId": "tkt_abc",
  "author": "customer",
  "body": "Thanks — here's the receipt hash …",
  "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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/support.tickets.close`

**Example**:

```jsonc
// input
{
  "ticketId": "tkt_abc"
}
// → output
{
  "ticketId": "tkt_abc",
  "subject": "Issue",
  "status": "closed",
  "priority": "medium",
  "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 — five dimensions, 1–5 each (ADR-034). A 2-or-below on any dimension triggers the feedback loop.
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/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 support 5/5 across the board.
```

### `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 `/api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/discovery.version.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "platform": "agined/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, a2a, nlweb
- **REST endpoint**: `POST /api/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, a2a, nlweb
- **REST endpoint**: `POST /api/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 available Agined + Tools 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/discovery.plans.list`

**Example**:

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

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

- **Summary**: List the 32 data-residency regions a workspace can be bound to.
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/discovery.regions.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "regions": [
    {
      "id": "cloudflare-d1:weur",
      "provider": "cloudflare-d1",
      "label": "Western Europe",
      "countryCode": "DE",
      "euJurisdictionBound": true
    }
  ]
}
// note: List all 32 regions (6 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, a2a, nlweb
- **REST endpoint**: `POST /api/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.identity.enroll`

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

**Example**:

```jsonc
// input
{
  "displayName": "GitHub Actions release attestor",
  "scopeKind": "workspace",
  "workspaceId": "ws_demo_default"
}
// → output
{
  "did": "did:web:agined.com:agents:ws_demo_default:abc",
  "documentUrl": "https://agined.com/.well-known/agents/ws_demo_default/abc/did.json",
  "enrollmentCredential": null,
  "privateKeyRecoveryEnvelope": null,
  "createdAt": "2026-05-22T12:00:00.000Z"
}
// note: Enroll a workspace-scoped agent DID for CI signing. One-time secrets are minted by rotate, not enroll.
```

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

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

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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**: `agents.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/agents.identity.get`

**Example**:

```jsonc
// input
{
  "did": "did:web:agined.com:agents:ws_demo_default:abc"
}
// → output
{
  "record": {
    "did": "did:web:agined.com:agents:ws_demo_default:abc",
    "displayName": "GitHub Actions release attestor",
    "description": null,
    "scopeKind": "workspace",
    "workspaceId": "ws_demo_default",
    "organizationId": null,
    "alg": "EdDSA",
    "activeMethodId": "did:web:agined.com:agents:ws_demo_default: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**: `agents.create`
- **Audit kind**: `agent.identity.rotated`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/agents.identity.rotate`

**Example**:

```jsonc
// input
{
  "did": "did:web:agined.com:agents:ws_demo_default:abc",
  "reason": "scheduled"
}
// → output
{
  "did": "did:web:agined.com:agents:ws_demo_default:abc",
  "newMethodId": "did:web:agined.com:agents:ws_demo_default: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**: `agents.delete`
- **Audit kind**: `agent.identity.revoked`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/agents.identity.revoke`

**Example**:

```jsonc
// input
{
  "did": "did:web:agined.com:agents:ws_demo_default:abc",
  "reason": "compromise",
  "irreversibleAcknowledged": true
}
// → output
{
  "did": "did:web:agined.com:agents:ws_demo_default:abc",
  "deactivatedAt": "2026-05-22T12:00:00.000Z"
}
// 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/agents.identity.did.resolve`

**Example**:

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

##### `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**: `agents.create`
- **Audit kind**: `agent.delegation.issued`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/agents.identity.delegate`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "fromAgentDid": "did:web:agined.com:agents:ws_demo_default: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 A2A delegation. Flips its bit in the published BitstringStatusList.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `agents.delete`
- **Audit kind**: `agent.delegation.revoked`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/agents.identity.delegate.revoke`

**Example**:

```jsonc
// input
{
  "delegationHandle": "delg_demo00000000000000000000",
  "reason": "Partner integration ended"
}
// → output
{
  "revokedAt": "2026-05-22T12:00:00.000Z",
  "listRevocable": true
}
// note: Revoke an A2A delegation.
```

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

- **Summary**: Verify a presented A2A delegation credential. 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/agents.identity.delegate.verify`

**Example**:

```jsonc
// input
{
  "presentationSerialized": "eyJhbGciOiJFZERTQSJ9…",
  "requestedScope": "read:audit"
}
// → output
{
  "ok": true,
  "delegationHandle": "delg_demo00000000000000000000",
  "vcId": "urn:uuid:0000",
  "fromAgentDid": "did:web:agined.com:agents:ws_demo_default:abc",
  "toRemoteDid": "did:web:partner.example.com:agents:bot",
  "scopes": [
    "read:audit"
  ],
  "expiresAt": "2026-05-29T12:00:00.000Z",
  "revocationChecked": true
}
// note: Verify a presented A2A delegation.
```

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

- **Summary**: Resolve who an agent acts on behalf of, from verified identity rather than operator configuration.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `agents.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/agents.identity.authority.get`

**Example**:

```jsonc
// input
{
  "agentDid": "did:web:agined.com:agents:ws_demo_default:abc"
}
// → output
{
  "agentDid": "did:web:agined.com:agents:ws_demo_default:abc",
  "confidence": "verified",
  "grade": "tenant-attested",
  "principal": "did:web:agined.com:workspaces:ws_demo_default",
  "source": "ap2-mandate",
  "basis": "A mandate signed by the workspace principal names this agent.",
  "reliedOn": [
    "Art. 50(1)",
    "Art. 50(1) — on-whose-behalf element"
  ],
  "competingPrincipals": [],
  "evidence": [
    {
      "source": "ap2-mandate",
      "principal": "did:web:agined.com:workspaces:ws_demo_default",
      "verified": true
    }
  ]
}
// note: Resolve the on-whose-behalf value.
```

##### `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**: `agents.create`
- **Audit kind**: `agent.mandate.issued`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/agents.mandate.issue`

**Example**:

```jsonc
// input
{
  "label": "Stripe refund bot — Q3",
  "agentDid": "did:web:agined.com:agents:ws_demo_default:refund-bot",
  "allowedActionIds": [
    "billing.subscription.upgrade",
    "tools.attest.agent-call"
  ],
  "maxSafetyLevel": "billing_impacting",
  "workspaceIds": [
    "ws_demo_default"
  ],
  "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:agined.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**: `agents.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/agents.mandate.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/agents.mandate.verify`

**Example**:

```jsonc
// input
{
  "presentationSerialized": "eyJhbGciOiJFZERTQSJ9…",
  "requestedActionId": "billing.subscription.upgrade",
  "audience": "https://api.agined.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, and every A2A delegation the agent issued under it (the kill chain). Goes into the BitstringStatusList revocation register immediately.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `agents.delete`
- **Audit kind**: `agent.mandate.revoked`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/agents.mandate.revoke`

**Example**:

```jsonc
// input
{
  "mandateHandle": "mandate_DEMO00000000000000000000"
}
// → output
{
  "revokedAt": "2026-05-22T12:00:00.000Z",
  "cascade": {
    "delegationsRevoked": [
      "delg_abc"
    ],
    "notWalked": [],
    "depth": 1,
    "complete": true,
    "keysStillLive": 2
  }
}
// note: Revoking the mandate also withdrew one delegation the agent had issued — and named the two API keys it minted, which are STILL LIVE and must be revoked directly.
```

##### `agents.spiffe.bind`

- **Summary**: Bind a SPIFFE ID to an agent DID so its JWT-SVIDs can attest as that agent.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: `agents.create`
- **Audit kind**: `agent.spiffe.bound`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/agents.spiffe.bind`

**Example**:

```jsonc
// input
{
  "agentDid": "did:web:agined.com:agents:ws_demo_default:abc",
  "spiffeId": "spiffe://corp.example.com/svc/billing",
  "svidType": "jwt"
}
// → output
{
  "agentDid": "did:web:agined.com:agents:ws_demo_default:abc",
  "spiffeId": "spiffe://corp.example.com/svc/billing",
  "boundAt": "2026-05-22T12:00:00.000Z"
}
// note: Bind SPIFFE workload to agent.
```

##### `agents.spiffe.unbind`

- **Summary**: Unbind a SPIFFE ID from its agent DID so its SVIDs stop attesting as that agent.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `agents.create`
- **Audit kind**: `agent.spiffe.unbound`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/agents.spiffe.unbind`

**Example**:

```jsonc
// input
{
  "spiffeId": "spiffe://corp.example.com/svc/billing"
}
// → output
{
  "spiffeId": "spiffe://corp.example.com/svc/billing",
  "unboundAt": "2026-08-23T12:00:00.000Z"
}
// note: Stop a decommissioned workload attesting as this agent.
```

##### `agents.spiffe.workload.attest`

- **Summary**: Exchange a SPIFFE SVID for a short-lived DPoP-bound Agined session.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent.spiffe.workload_attested`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/agents.spiffe.workload.attest`

**Example**:

```jsonc
// input
{
  "svid": {
    "type": "jwt",
    "token": "eyJhbGciOiJFZERTQSJ9…"
  },
  "dpopKey": {
    "kty": "OKP",
    "crv": "Ed25519",
    "x": "<base64url>"
  }
}
// → output
{
  "sessionToken": "av_sess_demo…",
  "expiresAt": "2026-05-22T12:05:00.000Z",
  "agentDid": "did:web:agined.com:agents:ws_demo_default: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**: `agents.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/agents.trusted-roots.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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**: `agents.create`
- **Audit kind**: `agent.trusted_root.added`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/agents.trusted-roots.add`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "did": "did:web:partner.example.com",
  "organizationName": "Partner Example Corp",
  "maxAcceptedSafetyLevel": "mutation"
}
// → output
{
  "addedAt": "2026-05-22T12:00:00.000Z"
}
// note: Add federated root.
```

##### `agents.trusted-roots.remove`

- **Summary**: Remove a partner organization DID from the trusted-roots list for this workspace.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `agents.create`
- **Audit kind**: `agent.trusted_root.removed`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/agents.trusted-roots.remove`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "did": "did:web:partner.example.com"
}
// → output
{
  "did": "did:web:partner.example.com",
  "removedAt": "2026-08-23T12:00:00.000Z"
}
// note: Stop trusting a federated root.
```

### `nexus` (3 actions)

Actions in the `nexus` domain: catalog.get, usage.get, oracle.agent.get.

##### `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 endpoint**: `POST /api/v1/actions/nexus.catalog.get`

**Example**:

```jsonc
// input
{}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/nexus.usage.get`

**Example**:

```jsonc
// input
{}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/nexus.oracle.agent.get`

**Example**:

```jsonc
// input
{
  "agentId": "did:web:example.com:agent:support"
}
// → output
{}
// note: Reputation for an agent.
```

### `vector` (5 actions)

Actions in the `vector` domain: registry.search, registry.entry.get, pricing.get, mcp.servers.list, catalog.get.

##### `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 endpoint**: `POST /api/v1/actions/vector.registry.search`

**Example**:

```jsonc
// input
{
  "q": "support agent"
}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/vector.registry.entry.get`

**Example**:

```jsonc
// input
{
  "id": "ag_demo_1"
}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/vector.pricing.get`

**Example**:

```jsonc
// input
{}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/vector.mcp.servers.list`

**Example**:

```jsonc
// input
{}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/vector.catalog.get`

**Example**:

```jsonc
// input
{}
// → output
{}
// note: List Vector products.
```

### `fabric` (12 actions)

Connector Fabric — the platform-wide ingestion layer. Connect any of the 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 the fabric and seal the result as a signed-retrieval receipt — the query hash plus every returned record's content hash, so a grounded claim can be proved after the fact.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: `records.view`
- **Audit kind**: `agent_invocation`
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/fabric.retrieve.signed`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "kinds": [
    "policy-clause"
  ]
}
// → output
{
  "records": [],
  "nextCursor": null,
  "retrieval": {
    "retrievalRef": "ret_…",
    "queryHash": "…",
    "sources": [],
    "retrievedAt": "2026-09-03T00:00:00.000Z",
    "sealed": true,
    "artifactId": "art_01J…",
    "unsealedReason": null
  }
}
// note: Ground a claim on policy clauses, provably.
```

##### `fabric.memory.snapshot`

- **Summary**: Snapshot the fabric's records as a signed memory-attestation receipt — entry count, Merkle root over every entry's content hash, and the provenance window — so an export can be verified without trusting the exporter.
- **Safety**: `billing_impacting` (confirmation policy: `mandate`)
- **Idempotent**: no
- **Permissions**: `records.view`
- **Audit kind**: `agent_invocation`
- **Rate class**: `billing`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/fabric.memory.snapshot`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → output
{
  "snapshot": {
    "agentRef": "did:key:z6Mk…",
    "snapshotRef": "mem_…",
    "entryCount": 42,
    "merkleRoot": "…",
    "earliestEntryAt": "2026-08-01T00:00:00.000Z",
    "latestEntryAt": "2026-09-04T00:00:00.000Z",
    "snapshotAt": "2026-09-04T00:00:00.000Z",
    "sealed": true,
    "artifactId": "art_01J…",
    "unsealedReason": null
  }
}
// note: Make an agent's memory portable and independently checkable.
```

##### `fabric.sources.catalog`

- **Summary**: List the connectable source catalog — each source's category, purpose, auth method, and the engine classes it contributes.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `integrations.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/fabric.sources.catalog`

**Example**:

```jsonc
// input
{
  "category": "devtools"
}
// → output
{
  "sources": []
}
// note: Browse developer-tool 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**: `integrations.connect`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/fabric.connections.connect`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "sourceId": "jira",
  "label": "Acme Jira",
  "scope": [
    "ACME"
  ],
  "syncSchedule": "daily"
}
// → output
{
  "connectionId": "01J9X4P9R7Z2C1A1F2A8VBJYS1",
  "workspaceId": "ws_demo_default",
  "sourceId": "jira",
  "category": "devtools",
  "authMethod": "oauth2",
  "label": "Acme Jira",
  "scope": [
    "ACME"
  ],
  "state": "pending",
  "syncState": "never",
  "emits": [
    "ticket"
  ],
  "lastSyncAt": null,
  "connectionRef": null,
  "credentialRef": null,
  "syncSchedule": "daily",
  "createdAt": "2026-05-22T12:00:00.000Z"
}
// note: Connect Jira — an OAuth source stays pending until its oauth/start → callback completes.
```

##### `fabric.connections.list`

- **Summary**: List the workspace's fabric connections with their sync health.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `integrations.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/fabric.connections.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → 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**: `integrations.connect`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/fabric.connections.sync`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "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**: `integrations.disconnect`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/fabric.connections.revoke`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "connectionId": "01J9X4P9R7Z2C1A1F2A8VBJYS1"
}
// → output
{
  "revoked": true,
  "recordsPurged": 1280
}
// note: Revoke + purge.
```

##### `fabric.webhooks.list`

- **Summary**: List the workspace's inbound webhook endpoints, with which sources can push and whether each scheme binds the body.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: `integrations.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/fabric.webhooks.list`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default"
}
// → output
{
  "endpoints": [],
  "supportedSources": []
}
// note: What can push, and what has.
```

##### `fabric.webhooks.open`

- **Summary**: Open an inbound webhook endpoint for a connection — returns the signing secret ONCE.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: `integrations.connect`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/fabric.webhooks.open`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "connectionId": "01J9X4P9R7Z2C1A1F2A8VBJYS1"
}
// → output
{
  "endpointId": "01J9X4P9R7Z2C1A1F2A8VBJYS2",
  "sourceId": "github",
  "deliveryPath": "/api/v1/fabric/deliveries/01J9X4P9R7Z2C1A1F2A8VBJYS2",
  "signatureHeader": "x-hub-signature-256",
  "secret": "shown-once"
}
// note: Open an endpoint for a GitHub connection.
```

##### `fabric.webhooks.revoke`

- **Summary**: Revoke an inbound webhook endpoint — deliveries to it stop immediately.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: `integrations.disconnect`
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/fabric.webhooks.revoke`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "endpointId": "01J9X4P9R7Z2C1A1F2A8VBJYS2"
}
// → output
{
  "revoked": true,
  "endpointId": "01J9X4P9R7Z2C1A1F2A8VBJYS2"
}
// note: Stop accepting pushes.
```

##### `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**: `records.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/fabric.records.query`

**Example**:

```jsonc
// input
{
  "workspaceId": "ws_demo_default",
  "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**: `integrations.view`
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/fabric.subscriptions.matrix`

**Example**:

```jsonc
// input
{}
// → output
{
  "subscriptions": {},
  "kindReach": {}
}
// note: Introspect the matrix.
```

### `actionflow` (7 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/actionflow.flows.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "flows": []
}
// 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/actionflow.flows.run`

**Example**:

```jsonc
// input
{
  "id": "flow_incident",
  "input": {
    "severity": "high"
  }
}
// → output
{
  "execution": {
    "executionId": "exec_…",
    "flowId": "flow_incident",
    "workspaceId": "ws_…",
    "initiatedBy": {},
    "triggeredBy": {},
    "status": "succeeded",
    "stepStates": {},
    "mode": "real",
    "startedAt": "2026-08-10T00:00:00Z",
    "waiting": false
  }
}
// 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/actionflow.flows.publish`

**Example**:

```jsonc
// input
{
  "id": "flow_incident"
}
// → output
{
  "flow": {
    "schemaVersion": "1.0",
    "id": "flow_incident",
    "workspaceId": "ws_…",
    "name": "Incident flow",
    "tags": [],
    "source": {},
    "triggers": [],
    "steps": [],
    "version": {
      "semver": "0.1.0",
      "status": "published"
    },
    "createdAt": "2026-08-10T00:00:00Z",
    "updatedAt": "2026-08-10T00:00:00Z"
  }
}
// note: Publish a flow.
```

##### `actionflow.flows.deprecate`

- **Summary**: Retire a published flow. It stops running on its triggers; its execution history is kept.
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/actionflow.flows.deprecate`

**Example**:

```jsonc
// input
{
  "id": "flow_incident"
}
// → output
{
  "flow": {
    "schemaVersion": "1.0",
    "id": "flow_incident",
    "workspaceId": "ws_…",
    "name": "Incident flow",
    "tags": [],
    "source": {},
    "triggers": [],
    "steps": [],
    "version": {
      "semver": "1.0.0",
      "status": "deprecated",
      "deprecatedAt": "2026-08-24T12:00:00Z"
    },
    "createdAt": "2026-08-10T00:00:00Z",
    "updatedAt": "2026-08-24T12:00:00Z"
  }
}
// note: Retire a published 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/actionflow.templates.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "templates": [
    {
      "id": "tmpl_incident_alert",
      "name": "Sentinel incident → alert",
      "description": "When Sentinel opens a high-severity incident, emit an alert webhook.",
      "tags": [
        "security",
        "alerting"
      ]
    }
  ]
}
// 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/actionflow.templates.instantiate`

**Example**:

```jsonc
// input
{
  "id": "tmpl_incident_alert",
  "name": "My incident flow"
}
// → output
{
  "flow": {
    "schemaVersion": "1.0",
    "id": "flow_…",
    "workspaceId": "ws_…",
    "name": "My incident flow",
    "tags": [
      "security",
      "alerting"
    ],
    "source": {},
    "triggers": [],
    "steps": [],
    "version": {
      "semver": "0.1.0",
      "status": "draft"
    },
    "createdAt": "2026-08-10T00:00:00Z",
    "updatedAt": "2026-08-10T00:00:00Z"
  }
}
// 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/actionflow.executions.list`

**Example**:

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

### `lens` (14 actions)

Actions in the `lens` domain: list, execute, validate, results.list, custom.list, custom.get, custom.create, custom.update.

##### `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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/lens.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "lenses": []
}
// 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/lens.execute`

**Example**:

```jsonc
// input
{
  "id": "lens_gdpr_art30",
  "params": {
    "since": "2026-01-01T00:00:00.000Z"
  }
}
// → output
{
  "ok": true,
  "resultId": "lres_…",
  "signed": true,
  "bundle": {}
}
// note: Run a GDPR 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/lens.validate`

**Example**:

```jsonc
// input
{
  "definition": {
    "framework": "gdpr"
  }
}
// → 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/lens.results.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "results": []
}
// note: List evidence bundles.
```

##### `lens.custom.list`

- **Summary**: List the custom lenses this workspace has authored.
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/lens.custom.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "lenses": []
}
// note: Browse the workspace's own lenses.
```

##### `lens.custom.get`

- **Summary**: Read one custom lens definition.
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/lens.custom.get`

**Example**:

```jsonc
// input
{
  "id": "lensc_…"
}
// → output
{
  "id": "lensc_…",
  "updatedAt": "2026-08-24T12:00:00.000Z",
  "definition": {}
}
// note: Read one.
```

##### `lens.custom.create`

- **Summary**: Author a custom lens. The runtime sanitises the definition and refuses an invalid one with the specific errors.
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/lens.custom.create`

**Example**:

```jsonc
// input
{
  "definition": {}
}
// → output
{
  "ok": true,
  "id": "lensc_…",
  "definition": {}
}
// note: Author a lens.
```

##### `lens.custom.update`

- **Summary**: Replace a custom lens definition.
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/lens.custom.update`

**Example**:

```jsonc
// input
{
  "id": "lensc_…",
  "definition": {}
}
// → output
{
  "ok": true,
  "id": "lensc_…",
  "definition": {}
}
// note: Revise a lens.
```

##### `lens.custom.delete`

- **Summary**: Delete a custom lens. Its past results keep the definition hash they were produced under.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/lens.custom.delete`

**Example**:

```jsonc
// input
{
  "id": "lensc_…"
}
// → output
{
  "ok": true
}
// note: Remove a lens the workspace authored.
```

##### `lens.marketplace.list`

- **Summary**: Browse the lens marketplace, with what this workspace has published and installed.
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/lens.marketplace.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "listings": [],
  "published": [],
  "installs": []
}
// note: What is available, and what I have.
```

##### `lens.marketplace.publish`

- **Summary**: Publish one of the workspace's own custom lenses at its pinned version. Enterprise only.
- **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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/lens.marketplace.publish`

**Example**:

```jsonc
// input
{
  "lensId": "clens_…",
  "summary": "Counts sign-ins on the audit chain."
}
// → output
{
  "listing": {
    "id": "llist_…",
    "publisherWorkspaceId": "ws_1",
    "sourceLensId": "clens_…",
    "name": "Sign-in review",
    "summary": "Counts sign-ins on the audit chain.",
    "version": "1.0.0",
    "publishedAt": "2026-09-02T00:00:00.000Z",
    "unpublishedAt": null
  }
}
// note: Share a lens.
```

##### `lens.marketplace.unpublish`

- **Summary**: Withdraw a listing. It leaves the catalogue; workspaces that already installed it keep the lens.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/lens.marketplace.unpublish`

**Example**:

```jsonc
// input
{
  "listingId": "llist_…"
}
// → output
{
  "unpublished": true,
  "listingId": "llist_…"
}
// note: Stop offering it.
```

##### `lens.marketplace.install`

- **Summary**: Install a listing into this workspace as a custom lens, pinned to the published version.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/lens.marketplace.install`

**Example**:

```jsonc
// input
{
  "listingId": "llist_…"
}
// → output
{
  "install": {
    "id": "linst_…",
    "listingId": "llist_…",
    "version": "1.0.0",
    "installedLensId": "clens_…",
    "installedAt": "2026-09-02T00:00:00.000Z"
  },
  "alreadyInstalled": false
}
// note: Take a shared lens.
```

##### `lens.marketplace.uninstall`

- **Summary**: Remove an installed lens and its install receipt together — the inverse of install.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `default`
- **Surfaces**: rest, mcp, chatgpt_app, gemini, perplexity, claude_cowork, claude_skill, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/lens.marketplace.uninstall`

**Example**:

```jsonc
// input
{
  "listingId": "llist_…"
}
// → output
{
  "uninstalled": true,
  "listingId": "llist_…"
}
// note: Give a shared lens back.
```

### `notarian` (3 actions)

Actions in the `notarian` domain: snapshot.create, verify-chain, anchors.list.

##### `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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/notarian.snapshot.create`

**Example**:

```jsonc
// input
{
  "scope": "month-end"
}
// → output
{
  "ok": true,
  "bundle": {}
}
// 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/notarian.verify-chain`

**Example**:

```jsonc
// input
{}
// → output
{
  "ok": true,
  "verification": {
    "ok": true,
    "checkedCount": 0,
    "tipHash": null
  }
}
// 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/notarian.anchors.list`

**Example**:

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

### `receipts` (32 actions)

Actions in the `receipts` domain: list, get, verify, issue, canon.list, canon.declare, canon.rely, canon.withdraw.

##### `receipts.list`

- **Summary**: List this workspace's signed evidence receipts, newest first.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.list`

**Example**:

```jsonc
// input
{
  "kind": "proof-of-erasure",
  "limit": 10
}
// → output
{
  "artifacts": []
}
// note: The erasure receipts, newest first.
```

##### `receipts.get`

- **Summary**: Fetch one receipt's signed envelope by artifact id.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.get`

**Example**:

```jsonc
// input
{
  "artifactId": "art_01J…"
}
// → output
{
  "artifact": {},
  "kind": "oversight",
  "issuedAt": "2026-08-28T00:00:00.000Z"
}
// note: Fetch the envelope to verify offline.
```

##### `receipts.verify`

- **Summary**: Verify a receipt — signature, and Merkle inclusion when an anchor is present. Free.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.verify`

**Example**:

```jsonc
// input
{
  "artifact": {}
}
// → output
{
  "ok": true,
  "anchored": false
}
// note: Verify a signed envelope.
```

##### `receipts.issue`

- **Summary**: Mint a signed evidence receipt of the given kind (a paid action).
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `billing`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.issue`

**Example**:

```jsonc
// input
{
  "kind": "oversight",
  "source": {}
}
// → output
{
  "bundle": {
    "artifact": {}
  }
}
// note: Seal an oversight receipt.
```

##### `receipts.canon.list`

- **Summary**: List this workspace's legal canon — the statute versions it tracks — and the live reliances pinned to them.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.canon.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "canon": [],
  "reliances": []
}
// note: The corpus and what relies on it.
```

##### `receipts.canon.declare`

- **Summary**: Declare a statute version in this workspace's canon. Superseding the current version computes drift over every live reliance and seals a `regulatory-canon-drift` receipt.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `billing`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.canon.declare`

**Example**:

```jsonc
// input
{
  "instrument": "EU AI Act",
  "articleRef": "Art. 73(2)",
  "version": "2024-consolidated",
  "effectiveFrom": "2024-08-01T00:00:00.000Z",
  "textSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
// → output
{
  "canon": {},
  "superseded": null,
  "drift": null,
  "receipt": null,
  "receiptError": null
}
// note: First version of a citation — no supersession, no drift check.
```

##### `receipts.canon.rely`

- **Summary**: Record that a live object — a mandate or a named obligation — relies on a canon version. This is what drift-check reads.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.canon.rely`

**Example**:

```jsonc
// input
{
  "subjectKind": "mandate",
  "subjectRef": "mnd_01J…",
  "canonId": "canon_01J…"
}
// → output
{
  "reliance": {
    "relianceId": "rel_01J…",
    "subjectKind": "mandate",
    "subjectRef": "mnd_01J…",
    "canonId": "canon_01J…",
    "pinnedVersion": "2.0",
    "declaredAt": "2026-09-19T00:00:00.000Z",
    "verified": true
  }
}
// note: Pin a live mandate to the current canon. A revoked or unknown mandate is refused.
```

##### `receipts.canon.withdraw`

- **Summary**: Withdraw a reliance. The row is kept — what a mandate relied on when it ran is an audit question a deleted row cannot answer.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.canon.withdraw`

**Example**:

```jsonc
// input
{
  "relianceId": "rel_01J…"
}
// → output
{
  "withdrawn": "rel_01J…"
}
// note: End a reliance.
```

##### `receipts.canon.drift-check`

- **Summary**: Recompute canon drift across the corpus (or one citation) and seal the result as a `regulatory-canon-drift` receipt — including an empty set, which is itself a finding.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `billing`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.canon.drift-check`

**Example**:

```jsonc
// input
{}
// → output
{
  "checkedAt": "2026-09-13T00:00:00.000Z",
  "findings": [],
  "violations": 0,
  "receipt": {},
  "receiptError": null
}
// note: A corpus-wide sweep; the sealed receipt is the check, whatever it finds.
```

##### `receipts.canon.seed`

- **Summary**: Seed the starter canon — the four reporting-window corpora klaxon enforces (EU AI Act Art. 73(2-4), Colorado SB 24-205 § 6-1-1702(5)) — as transcribed-basis rows marked legalReviewed:false. Idempotent per citation.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.canon.seed`

**Example**:

```jsonc
// input
{}
// → output
{
  "seeded": [
    "EU AI Act Art. 73(2)",
    "EU AI Act Art. 73(3)",
    "EU AI Act Art. 73(4)",
    "Colorado SB 24-205 § 6-1-1702(5)"
  ],
  "skipped": [],
  "legalReviewed": false
}
// note: Writes the four starter rows. A citation the workspace already tracks is reported under `skipped`, never overwritten.
```

##### `receipts.conformity.frameworks`

- **Summary**: List the regulatory frameworks a conformity posture can be computed against, and what evidence discharges each clause.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.conformity.frameworks`

**Example**:

```jsonc
// input
{}
// → output
{
  "frameworks": []
}
// note: What can be assessed.
```

##### `receipts.conformity.assess`

- **Summary**: Compute this workspace's conformity posture from its signed evidence, clause by clause. Optionally seal it as a signed attestation.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `billing`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.conformity.assess`

**Example**:

```jsonc
// input
{
  "framework": "eu-ai-act"
}
// → output
{
  "assessment": {
    "frameworkId": "eu-ai-act",
    "frameworkTitle": "EU AI Act (Regulation (EU) 2024/1689)",
    "clauses": [],
    "met": 0,
    "applicable": 4,
    "total": 4,
    "computedAt": "2026-09-03T00:00:00.000Z",
    "windowStart": "2026-06-05T00:00:00.000Z"
  },
  "minted": null
}
// note: Compute the posture without sealing it.
```

##### `receipts.klaxon.assess`

- **Summary**: Group observed incident signals into incidents, compute each one's severity and statutory reporting deadline, and optionally seal the reportable ones.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `billing`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.klaxon.assess`

**Example**:

```jsonc
// input
{
  "jurisdiction": "eu",
  "signals": [
    {
      "kind": "personal-injury",
      "at": "2026-09-01T00:00:00.000Z",
      "evidenceRef": "art_01J…"
    }
  ]
}
// → output
{
  "incidents": [],
  "minted": []
}
// note: Detect and clock without sealing.
```

##### `receipts.dossier.generate`

- **Summary**: Assemble the EU AI Act Annex IV technical file from this workspace's signed evidence, every section bound to the receipts substantiating it. Optionally seal it.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `billing`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.dossier.generate`

**Example**:

```jsonc
// input
{
  "dossierRef": "TF-2026-01"
}
// → output
{
  "dossier": {
    "dossierRef": "TF-2026-01",
    "sections": [],
    "substantiatedCount": 0,
    "coverableCount": 7,
    "totalSections": 9,
    "generatedFromRuns": 0,
    "generatedAt": "2026-09-03T00:00:00.000Z",
    "windowStart": "2026-06-05T00:00:00.000Z"
  },
  "minted": null
}
// note: Assemble the technical file without sealing it.
```

##### `receipts.dossier.sections`

- **Summary**: List the Annex IV sections a technical file must contain, and what evidence substantiates each.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.dossier.sections`

**Example**:

```jsonc
// input
{}
// → output
{
  "sections": []
}
// note: What a technical file must contain.
```

##### `receipts.actor-score.compute`

- **Summary**: Score each agent in this workspace on its real audit record — mandate violations, autonomy breaches, oversight failures and breaker trips, as rates over runs. Optionally seal the confident ones.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `billing`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.actor-score.compute`

**Example**:

```jsonc
// input
{}
// → output
{
  "scores": [],
  "weights": {},
  "windowStart": "2026-06-05T00:00:00.000Z",
  "computedAt": "2026-09-03T00:00:00.000Z",
  "minted": []
}
// note: Score without sealing.
```

##### `receipts.agent-passport.issue`

- **Summary**: Issue a passport for one agent — its live mandates, their autonomy ceilings and its actor score — assembled from the mandate store and the audit chain. Optionally sealed.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `billing`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.agent-passport.issue`

**Example**:

```jsonc
// input
{
  "agentDid": "did:web:agined.com:agent:releasebot",
  "issuedFor": "acme-procurement"
}
// → output
{
  "passport": {
    "agentRef": "did:web:…",
    "agentDid": "did:web:…",
    "displayName": "releasebot",
    "mandates": [],
    "actorScore": null,
    "issuedFor": "acme-procurement",
    "expiresAt": "2026-12-01T00:00:00.000Z",
    "issuedAt": "2026-09-04T00:00:00.000Z"
  },
  "highestCeiling": null,
  "minted": null
}
// note: Issue without sealing.
```

##### `receipts.agent-passport.revoke`

- **Summary**: Revoke a passport this workspace issued, so a counterparty checking its status sees it is dead.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.agent-passport.revoke`

**Example**:

```jsonc
// input
{
  "artifactId": "art_01J…",
  "reason": "agent decommissioned"
}
// → output
{
  "revoked": true,
  "artifactId": "art_01J…",
  "revokedAt": "2026-09-04T00:00:00.000Z"
}
// note: Kill a passport early.
```

##### `receipts.exhibit.assemble`

- **Summary**: Assemble the evidence bundle for one run — its receipts, custody entry and C2PA manifests — naming any source that came back empty. Optionally sealed.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `billing`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.exhibit.assemble`

**Example**:

```jsonc
// input
{
  "runRef": "run_01J…"
}
// → output
{
  "exhibit": {
    "runRef": "run_01J…",
    "topsSliceRef": "",
    "otsAnchorRef": null,
    "receiptRefs": [],
    "custodyRef": "",
    "c2paRefs": [],
    "assembledAt": "2026-09-04T00:00:00.000Z",
    "missing": [],
    "unavailable": [
      "custodyRef"
    ]
  },
  "chainSliceProvenance": "not-supplied",
  "minted": null
}
// note: Assemble without sealing.
```

##### `receipts.handshake.notarise`

- **Summary**: Notarise a capability handshake between two agents — what was offered, under what scope, and whether it was accepted or declined.
- **Safety**: `billing_impacting` (confirmation policy: `always`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `billing`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.handshake.notarise`

**Example**:

```jsonc
// input
{
  "handshakeRef": "hs_01J…",
  "offer": {
    "initiatorDid": "did:web:a.example",
    "responderDid": "did:web:b.example",
    "capabilities": [
      "read:catalogue"
    ],
    "mandateScope": "procurement"
  },
  "outcome": "declined"
}
// → output
{
  "handshake": {
    "handshakeRef": "hs_01J…",
    "initiatorDid": "did:web:a.example",
    "responderDid": "did:web:b.example",
    "capabilities": [
      "read:catalogue"
    ],
    "mandateScope": "procurement",
    "agreementHash": "…",
    "outcome": "declined",
    "notarizedAt": "2026-09-04T00:00:00.000Z"
  },
  "minted": null
}
// note: Record a refusal — the half a naive notary drops.
```

##### `receipts.blame.apportion`

- **Summary**: Apportion fault across a multi-agent failure — weighted by how each agent's contribution was governed, with the unattributed share reported rather than distributed.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.blame.apportion`

**Example**:

```jsonc
// input
{
  "incidentRef": "inc_01J…",
  "contributions": [
    {
      "agentRef": "agent:a",
      "culpability": "outside-mandate",
      "causalSteps": 2
    }
  ],
  "unattributedSteps": 1
}
// → output
{
  "blame": {
    "incidentRef": "inc_01J…",
    "shares": [],
    "unattributed": 0.11,
    "totalWeight": 9,
    "weights": {}
  },
  "unattributedStepsDeclared": true
}
// note: Apportion, with a declared gap.
```

##### `receipts.indemnity.feed`

- **Summary**: The per-workspace risk picture an insurer prices from — worst band and its count, the full distribution, measured coverage, incidents by severity and apportioned fault.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.indemnity.feed`

**Example**:

```jsonc
// input
{
  "agentsKnown": 50
}
// → output
{
  "feed": {
    "worstBand": "at-risk",
    "worstBandCount": 1,
    "distribution": {
      "exemplary": 49,
      "sound": 0,
      "watch": 0,
      "at-risk": 1
    },
    "meanScore": 94,
    "agentsKnown": 50,
    "agentsScored": 50,
    "agentsProvisional": 0,
    "coverage": 1,
    "incidents": {
      "low": 0,
      "medium": 0,
      "high": 0,
      "serious": 0,
      "total": 0
    },
    "apportionedFault": 0,
    "periodStart": "2026-06-06T00:00:00.000Z",
    "periodEnd": "2026-09-04T00:00:00.000Z"
  }
}
// note: Forty-nine exemplary agents and one at-risk headlines at-risk.
```

##### `receipts.mandate-template.instantiate`

- **Summary**: Check a requested grant against a published mandate template. Narrowing is allowed; widening is refused and says which bound it crossed.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.mandate-template.instantiate`

**Example**:

```jsonc
// input
{
  "template": {
    "templateId": "tpl_support",
    "autonomyCeiling": "mutation",
    "actions": [
      "tickets.read",
      "tickets.reply"
    ],
    "maxInvocations": 1000
  },
  "requested": {
    "autonomyCeiling": "read",
    "actions": [
      "tickets.read"
    ],
    "maxInvocations": 100
  }
}
// → output
{
  "ok": true,
  "granted": {
    "autonomyCeiling": "read",
    "actions": [
      "tickets.read"
    ],
    "maxInvocations": 100
  }
}
// note: A narrowing instantiation.
```

##### `receipts.mandate-template.record`

- **Summary**: A template's outcome track record — adoptions, the WORST band any measured adopter reached, and whether there is enough history for it to mean anything.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.mandate-template.record`

**Example**:

```jsonc
// input
{
  "templateId": "tpl_support",
  "outcomes": []
}
// → output
{
  "record": {
    "templateId": "tpl_support",
    "adoptions": 0,
    "measuredAdoptions": 0,
    "worstBand": null,
    "incidents": 0,
    "unproven": true
  }
}
// note: A template nobody has run does not present as safe.
```

##### `receipts.counterwitness.seal`

- **Summary**: Seal one telemetry batch into the workspace's witness chain — committing to the previous seal, the span ids and the count.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.counterwitness.seal`

**Example**:

```jsonc
// input
{
  "spanIds": [
    "span_a",
    "span_b"
  ],
  "sequence": 1,
  "prevHash": "GENESIS"
}
// → output
{
  "seal": {
    "sequence": 1,
    "hash": "…",
    "prevHash": "GENESIS",
    "spanCount": 2,
    "sealedAt": "2026-09-04T00:00:00.000Z"
  }
}
// note: Open a chain.
```

##### `receipts.counterwitness.verify`

- **Summary**: Walk a chain of telemetry seals and report where it breaks — a deleted batch, a thinned one, or a forged relink.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.counterwitness.verify`

**Example**:

```jsonc
// input
{
  "seals": [],
  "spansBySequence": {}
}
// → output
{
  "verdict": {
    "ok": false,
    "sealsChecked": 0,
    "brokeAt": 0,
    "reason": "No seals — an empty chain proves nothing."
  }
}
// note: An empty chain is not valid — returning ok would make a wiped store indistinguishable from an intact one.
```

##### `receipts.interpose.witness`

- **Summary**: Record one exchange that passed through the witness — the bytes on each side, the status, the timing, and which sides it could not read in full.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.interpose.witness`

**Example**:

```jsonc
// input
{
  "exchangeRef": "ex_01J…",
  "upstream": "https://someone-elses-agent.example/api",
  "request": {
    "observed": "complete",
    "bytes": 128,
    "sha256": "…",
    "contentType": "application/json"
  },
  "response": {
    "observed": "streamed",
    "contentType": "text/event-stream"
  }
}
// → output
{
  "record": {
    "exchangeRef": "ex_01J…",
    "upstream": "https://someone-elses-agent.example/api",
    "request": {
      "observed": "complete"
    },
    "response": {
      "observed": "streamed"
    },
    "status": 200,
    "durationMs": 250,
    "fullyObserved": false,
    "gaps": [
      "response:streamed"
    ],
    "startedAt": "2026-09-04T00:00:00.000Z",
    "endedAt": "2026-09-04T00:00:00.250Z"
  }
}
// note: A streamed response is a gap, not a silence.
```

##### `receipts.interpose.vouch`

- **Summary**: Ask whether a witness record vouches for these bytes. A side the witness did not fully see answers `unverifiable`, never `mismatch`.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.interpose.vouch`

**Example**:

```jsonc
// input
{
  "record": {},
  "claimed": {}
}
// → output
{
  "verdict": {
    "request": "unverifiable",
    "response": "unverifiable"
  }
}
// note: No claim is unverifiable, not a mismatch.
```

##### `receipts.agent-ca.validate`

- **Summary**: Validate an agent certificate chain against a set of trusted roots — rejecting an unknown root outright rather than reporting 'valid, unknown issuer'.
- **Safety**: `read` (confirmation policy: `none`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_read`
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.agent-ca.validate`

**Example**:

```jsonc
// input
{
  "chain": [
    {
      "subjectDid": "did:web:acme.example:agents:bot",
      "issuerDid": "did:web:agined.com",
      "safetyLevel": "mutation",
      "notBefore": "2026-08-01T00:00:00.000Z",
      "notAfter": "2026-10-01T00:00:00.000Z"
    }
  ],
  "anchors": [
    {
      "did": "did:web:agined.com",
      "maxAcceptedSafetyLevel": "destructive",
      "allowsFederation": true
    }
  ]
}
// → output
{
  "verdict": {
    "ok": true,
    "rootDid": "did:web:agined.com",
    "effectiveLevel": "mutation",
    "linksWalked": 1
  }
}
// note: A leaf under a trusted root.
```

##### `receipts.agent-ca.issue`

- **Summary**: Sign a certificate for an agent under this platform's CA, and record it. The issuer is the platform's own key — never a caller input.
- **Safety**: `destructive` (confirmation policy: `mandate`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.agent-ca.issue`

**Example**:

```jsonc
// input
{
  "subjectDid": "did:web:acme.example:agents:bot",
  "safetyLevel": "mutation",
  "notAfter": "2026-12-01T00:00:00.000Z",
  "published": true
}
// → output
{
  "certificate": {
    "subjectDid": "did:web:acme.example:agents:bot",
    "issuerDid": "did:web:agined.com:ca:root",
    "safetyLevel": "mutation",
    "notBefore": "2026-09-04T00:00:00.000Z",
    "notAfter": "2026-12-01T00:00:00.000Z",
    "revoked": false,
    "signature": "…",
    "signingKeyId": "agent-ca-2026-root"
  },
  "fingerprint": "…",
  "published": true,
  "recordedAt": "2026-09-04T00:00:00.000Z"
}
// note: Issue and publish. 501 when the CA has no signing identity configured — never an unsigned certificate.
```

##### `receipts.agent-ca.record`

- **Summary**: Record an issued agent certificate, optionally publishing it to the transparency registry.
- **Safety**: `mutation` (confirmation policy: `mandate`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.agent-ca.record`

**Example**:

```jsonc
// input
{
  "certificate": {
    "subjectDid": "did:web:acme.example:agents:bot",
    "issuerDid": "did:web:agined.com",
    "safetyLevel": "mutation",
    "notBefore": "2026-08-01T00:00:00.000Z",
    "notAfter": "2026-10-01T00:00:00.000Z"
  },
  "published": true
}
// → output
{
  "fingerprint": "…",
  "published": true,
  "recordedAt": "2026-09-04T00:00:00.000Z"
}
// note: Record and publish.
```

##### `receipts.agent-ca.revoke`

- **Summary**: Revoke a recorded certificate. It stays in the registry, flagged — a registry that hides revocations launders them.
- **Safety**: `destructive` (confirmation policy: `always`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: `agent_invocation`
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/receipts.agent-ca.revoke`

**Example**:

```jsonc
// input
{
  "fingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "reason": "agent decommissioned"
}
// → output
{
  "revoked": true,
  "fingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "revokedAt": "2026-09-04T00:00:00.000Z"
}
// note: Kill a certificate.
```

### `witness` (7 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/witness.frameworks.list`

**Example**:

```jsonc
// input
{
  "status": "stable"
}
// → output
{
  "frameworks": [],
  "counts": {
    "stable": 0,
    "beta": 0,
    "comingSoon": 0,
    "total": 0
  }
}
// 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/witness.frameworks.get`

**Example**:

```jsonc
// input
{
  "frameworkId": "langchain"
}
// → output
{
  "framework": {
    "id": "langchain",
    "name": "LangChain",
    "category": "orchestration",
    "status": "beta"
  }
}
// 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/witness.patterns.list`

**Example**:

```jsonc
// input
{}
// → output
{
  "patterns": []
}
// 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/witness.subscriptions.get`

**Example**:

```jsonc
// input
{}
// → output
{
  "subscriptions": {}
}
// note: The WITNESS_SUBSCRIPTIONS routing matrix.
```

##### `witness.records.list`

- **Summary**: List the workspace's adapter-captured agent records from the neutral Witness-Fabric store (chain-free read — product-independent; no 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/witness.records.list`

**Example**:

```jsonc
// input
{
  "frameworkId": "crewai",
  "limit": 20
}
// → output
{
  "records": [],
  "count": 0,
  "nextCursor": null
}
// 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 Agined's Tops 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, a2a, nlweb
- **REST endpoint**: `POST /api/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": "wr_demo00000000000000000000",
  "deduplicated": false,
  "chainAnchored": true
}
// 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, a2a, nlweb
- **REST endpoint**: `POST /api/v1/actions/witness.records.stats`

**Example**:

```jsonc
// input
{}
// → output
{
  "stats": {
    "total": 0,
    "byFramework": [],
    "byPattern": [],
    "byEvent": []
  }
}
// note: Stream aggregates for dashboards.
```

### `tranquility` (30 actions)

Actions in the `tranquility` domain: overview, slos.list, slos.create, slos.set-enabled, slos.get, slos.evaluate, goals.list, goals.create.

##### `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 endpoint**: `POST /api/v1/actions/tranquility.overview`

**Example**:

```jsonc
// input
{}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/tranquility.slos.list`

**Example**:

```jsonc
// input
{}
// → output
{}
// 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 endpoint**: `POST /api/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
{}
// note: A dollar-denominated SLO.
```

##### `tranquility.slos.set-enabled`

- **Summary**: Turn an SLO's tracking on or off. A disabled SLO keeps its history and refuses new evaluations.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: yes
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/tranquility.slos.set-enabled`

**Example**:

```jsonc
// input
{
  "sloId": "tyslo_1",
  "enabled": false
}
// → output
{}
// note: Stop tracking an SLO without losing its evaluations.
```

##### `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 endpoint**: `POST /api/v1/actions/tranquility.slos.get`

**Example**:

```jsonc
// input
{
  "sloId": "tyslo_x"
}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/tranquility.slos.evaluate`

**Example**:

```jsonc
// input
{
  "sloId": "tyslo_x",
  "points": [
    {
      "ts": "2026-07-21T00:00:00Z",
      "value": 340
    }
  ],
  "seal": true
}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/tranquility.goals.list`

**Example**:

```jsonc
// input
{
  "outcome": "resolved"
}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/tranquility.goals.create`

**Example**:

```jsonc
// input
{
  "externalRef": "ticket-42",
  "kind": "ticket",
  "costCenter": "cc-support"
}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/tranquility.goals.events.append`

**Example**:

```jsonc
// input
{
  "goalId": "tygoal_x",
  "events": [
    {
      "eventType": "tool.call",
      "costUm": 1200
    }
  ]
}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/tranquility.goals.close`

**Example**:

```jsonc
// input
{
  "goalId": "tygoal_x",
  "outcome": "resolved"
}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/tranquility.goals.summary`

**Example**:

```jsonc
// input
{}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/tranquility.agent.records`

**Example**:

```jsonc
// input
{
  "frameworkId": "langchain",
  "event": "tool.call"
}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/tranquility.agent.frameworks`

**Example**:

```jsonc
// input
{}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/tranquility.metrics.query`

**Example**:

```jsonc
// input
{
  "name": "http.server.duration"
}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/tranquility.metrics.names`

**Example**:

```jsonc
// input
{}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/tranquility.logs.search`

**Example**:

```jsonc
// input
{
  "minSeverity": 17
}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/tranquility.agent.tools`

**Example**:

```jsonc
// input
{
  "frameworkId": "langchain"
}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/tranquility.agent.fleet`

**Example**:

```jsonc
// input
{}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/tranquility.agent.failures`

**Example**:

```jsonc
// input
{}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/tranquility.agent.runTree`

**Example**:

```jsonc
// input
{
  "runId": "R1"
}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/tranquility.cognition.guardrailPressure`

**Example**:

```jsonc
// input
{
  "evaluations": [
    {
      "clause": "pii.redact",
      "outcome": "deny",
      "at": "2026-07-21T00:00:00Z"
    }
  ]
}
// → output
{}
// 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 endpoint**: `POST /api/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
{}
// note: Score a plan before it runs.
```

##### `tranquility.cognition.charterConformance`

- **Summary**: Diff an agent's observed behavior against its declared Agined mandate (allowed tools / autonomy ceiling / allowed tones). A pure diff with a COVERAGE statement: an undeclared dimension is unposeable, and a no-mandate 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 endpoint**: `POST /api/v1/actions/tranquility.cognition.charterConformance`

**Example**:

```jsonc
// input
{
  "observed": {
    "tools": [
      "search",
      "email.send"
    ]
  },
  "declared": {
    "allowedTools": [
      "search"
    ]
  }
}
// → output
{}
// note: Detect off-mandate 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 endpoint**: `POST /api/v1/actions/tranquility.cognition.vocabularyDrift`

**Example**:

```jsonc
// input
{
  "topN": 25
}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/tranquility.evidence.usage.seal`

**Example**:

```jsonc
// input
{
  "costCenter": "cc-support"
}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/tranquility.evidence.coverage.seal`

**Example**:

```jsonc
// input
{
  "metric": "p95",
  "value": 340,
  "unit": "ms"
}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/tranquility.artifacts.list`

**Example**:

```jsonc
// input
{
  "subjectKind": "slo"
}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/tranquility.views.list`

**Example**:

```jsonc
// input
{
  "surface": "agent"
}
// → output
{}
// 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 endpoint**: `POST /api/v1/actions/tranquility.views.create`

**Example**:

```jsonc
// input
{
  "name": "tool heatmap",
  "surface": "agent",
  "spec": {
    "panel": "heatmap"
  }
}
// → output
{}
// note: Save a monitor.
```

##### `tranquility.views.delete`

- **Summary**: Delete a saved view / custom monitor.
- **Safety**: `mutation` (confirmation policy: `ask`)
- **Idempotent**: no
- **Permissions**: _(no permission required)_
- **Audit kind**: _(read-only — gateway emits `agent_read`)_
- **Rate class**: `default`
- **Surfaces**: 
- **REST endpoint**: `POST /api/v1/actions/tranquility.views.delete`

**Example**:

```jsonc
// input
{
  "viewId": "tyv_01H…"
}
// → output
{
  "deleted": true
}
// note: Remove a saved monitor.
```


---

**Total**: 412 actions across 29 domains.

Generated 2026-11-10T21:32:07.834Z from contracts 0.32.289-agined.1.