{ "openapi": "3.1.0", "info": { "title": "Trustvice + Trustvice API", "version": "0.91.0", "description": "Programmatic + agentic control surface for Trustvice (compliance-first audit + receipts) and Trustvice Receipts (cryptographic-receipt-as-a-service). Every action exposed here is also reachable via MCP, ChatGPT Apps, Gemini Extensions, Perplexity, and Claude Cowork — see AGENTS.md for the catalogue. Auto-generated from `@trustvice/contracts@0.91.0` on 2026-11-08T20:41:05.782Z.", "contact": { "name": "Trustvice", "url": "https://trustvice.com", "email": "support@trustvice.com" }, "license": { "name": "Trustvice Terms of Service", "url": "https://trustvice.com/legal#terms-of-service" }, "x-trustvice-generated-at": "2026-11-08T20:41:05.782Z", "x-trustvice-contracts-version": "0.91.0" }, "servers": [ { "url": "https://api.trustvice.com", "description": "Production gateway." }, { "url": "https://api.eu.trustvice.com", "description": "Production gateway, EU regions." }, { "url": "https://api.asia.trustvice.com", "description": "Production gateway, Asia-Pacific." }, { "url": "https://api.oc.trustvice.com", "description": "Production gateway, Oceania." } ], "tags": [ { "name": "account", "description": "Login session, profile, passkeys, locale, notification preferences." }, { "name": "org", "description": "Organization-level CRUD, members, roles." }, { "name": "workspace", "description": "Workspace CRUD, members, settings, region binding." }, { "name": "billing", "description": "Subscription and invoices (Avonao Billing), cost centers." }, { "name": "keys", "description": "Personal access tokens, workspace API keys (tv_ + entp_)." }, { "name": "webhooks", "description": "Outbound webhook endpoints + signing secrets + deliveries." }, { "name": "alerts", "description": "Alert rules, test fires, history." }, { "name": "exports", "description": "Compliance exports + receipt bundles + EU AI Act Article 12." }, { "name": "retention", "description": "Retention policy + paid extension." }, { "name": "audit", "description": "Three-tier audit log (workspace, custody, Tops feed)." }, { "name": "tops", "description": "Tops config cascade (org → workspace → actor)." }, { "name": "referrals", "description": "Codes, redemption, spend ledger, Every.org charity." }, { "name": "number_one", "description": "Number One AI chat (Calculator / Analyst / Admin modes)." }, { "name": "entpoind", "description": "8 Trustvice Receipts primitives + workspace-level Trustvice Receipts controls." }, { "name": "privacy", "description": "GDPR/CCPA DSR submission, status, receipts." }, { "name": "support", "description": "Tickets, replies, satisfaction surveys." }, { "name": "discovery", "description": "Capabilities, version, schema, plan list (always-on)." }, { "name": "agents", "description": "W3C DID Web agent identity, A2A delegation, AP2 Verifiable Credential mandates, SPIFFE workload identity, partner-DID federation roots." } ], "paths": { "/v1/actions/account.session.list": { "post": { "operationId": "account_session_list", "summary": "List active sessions on this account.", "x-trustvice-description-key": "actions.account.session.list.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "List active sessions.", "value": { "limit": 10 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sessions": { "type": "array", "items": { "type": "object", "properties": { "sessionId": { "type": "string" }, "accountId": { "type": "string", "pattern": "^acc_[0-9A-Z]{20,}$" }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "authMethod": { "type": "string", "enum": [ "session_cookie", "pat", "workspace_api_key", "oauth_access_token", "oauth_access_token_dpop", "mtls_svid", "sidecar_token" ] }, "userAgent": { "type": "string", "maxLength": 500 }, "ipPrefix": { "type": "string", "pattern": "^[0-9a-f.:]+\\/\\d{1,3}$" }, "isCurrent": { "type": "boolean" } }, "required": [ "sessionId", "accountId", "issuedAt", "expiresAt", "authMethod", "isCurrent" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "sessions", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List active sessions.", "value": { "sessions": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/account.session.revoke": { "post": { "operationId": "account_session_revoke", "summary": "Revoke an active session by id (cannot be disabled — safety floor).", "x-trustvice-description-key": "actions.account.session.revoke.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sessionId": { "type": "string" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "sessionId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Kill an active session.", "value": { "sessionId": "sess_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "revoked": { "type": "boolean" }, "propagatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "revoked", "propagatedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Kill an active session.", "value": { "revoked": true, "propagatedAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "admin.action", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/account.session.current": { "post": { "operationId": "account_session_current", "summary": "Get the calling principal's current session.", "x-trustvice-description-key": "actions.account.session.current.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read your own session.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sessionId": { "type": "string" }, "accountId": { "type": "string", "pattern": "^acc_[0-9A-Z]{20,}$" }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "authMethod": { "type": "string", "enum": [ "session_cookie", "pat", "workspace_api_key", "oauth_access_token", "oauth_access_token_dpop", "mtls_svid", "sidecar_token" ] }, "userAgent": { "type": "string", "maxLength": 500 }, "ipPrefix": { "type": "string", "pattern": "^[0-9a-f.:]+\\/\\d{1,3}$" }, "isCurrent": { "type": "boolean" } }, "required": [ "sessionId", "accountId", "issuedAt", "expiresAt", "authMethod", "isCurrent" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read your own session.", "value": { "sessionId": "sess_abc", "accountId": "acc_DEMO00000000000000000000", "issuedAt": "2026-05-22T12:00:00.000Z", "expiresAt": "2026-05-22T12:30:00.000Z", "authMethod": "session_cookie", "isCurrent": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/account.profile.get": { "post": { "operationId": "account_profile_get", "summary": "Get the authenticated account's profile.", "x-trustvice-description-key": "actions.account.profile.get.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read your profile.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^acc_[0-9A-Z]{20,}$" }, "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 80 }, "locale": { "type": "string", "enum": [ "en", "es", "fr", "de", "de-du", "zh" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "avatarUrl": { "type": "string", "format": "uri" } }, "required": [ "accountId", "email", "locale", "createdAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read your profile.", "value": { "accountId": "acc_DEMO00000000000000000000", "email": "owner@example.com", "displayName": "Ada Lovelace", "locale": "en", "createdAt": "2026-01-01T00:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/account.profile.update": { "post": { "operationId": "account_profile_update", "summary": "Update account profile (display name, avatar URL).", "x-trustvice-description-key": "actions.account.profile.update.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 80 }, "avatarUrl": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Update display name.", "value": { "displayName": "Ada Lovelace" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^acc_[0-9A-Z]{20,}$" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 80 }, "avatarUrl": { "type": "string", "format": "uri" } }, "required": [ "accountId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Update display name.", "value": { "accountId": "acc_DEMO00000000000000000000", "displayName": "Ada Lovelace" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "admin.action", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/account.email.change": { "post": { "operationId": "account_email_change", "summary": "Request an email change. A verification email is sent to the new address; the change applies only after click-through.", "x-trustvice-description-key": "actions.account.email.change.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "newEmail": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "newEmail" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Start email change flow.", "value": { "newEmail": "new@example.com" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "pending": { "type": "boolean", "const": true }, "verificationSentTo": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "pending", "verificationSentTo" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Start email change flow.", "value": { "pending": true, "verificationSentTo": "new@example.com" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "admin.action", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/account.email.change.pending": { "post": { "operationId": "account_email_change_pending", "summary": "Read the email change already in flight, and which of the two addresses still has to confirm. Null when none is pending.", "x-trustvice-description-key": "actions.account.email.change.pending.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "A change waiting on the old address.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "pending": { "anyOf": [ { "type": "object", "properties": { "newEmail": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "requestedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "awaitingOldAddress": { "type": "boolean" }, "awaitingNewAddress": { "type": "boolean" } }, "required": [ "newEmail", "requestedAt", "expiresAt", "awaitingOldAddress", "awaitingNewAddress" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "pending" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "A change waiting on the old address.", "value": { "pending": { "newEmail": "new@example.com", "requestedAt": "2026-05-22T12:00:00.000Z", "expiresAt": "2026-05-23T12:00:00.000Z", "awaitingOldAddress": true, "awaitingNewAddress": false } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/account.passkey.list": { "post": { "operationId": "account_passkey_list", "summary": "List registered passkeys.", "x-trustvice-description-key": "actions.account.passkey.list.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "List passkeys.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "passkeys": { "type": "array", "items": { "type": "object", "properties": { "credentialId": { "type": "string" }, "nickname": { "type": "string", "minLength": 1, "maxLength": 80 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "aaguid": { "type": "string" }, "backupEligible": { "type": "boolean" } }, "required": [ "credentialId", "nickname", "createdAt", "lastUsedAt", "backupEligible" ], "additionalProperties": false } } }, "required": [ "passkeys" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List passkeys.", "value": { "passkeys": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/account.passkey.register-challenge": { "post": { "operationId": "account_passkey_register-challenge", "summary": "Begin passkey registration — returns a WebAuthn PublicKeyCredentialCreationOptions challenge.", "x-trustvice-description-key": "actions.account.passkey.register-challenge.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "nickname": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "nickname" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "WebAuthn registration challenge.", "value": { "nickname": "YubiKey 5C" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "challenge": { "type": "string" }, "rp": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "displayName": { "type": "string" } }, "required": [ "id", "name", "displayName" ], "additionalProperties": false }, "pubKeyCredParams": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "public-key" }, "alg": { "type": "number" } }, "required": [ "type", "alg" ], "additionalProperties": false } } }, "required": [ "challenge", "rp", "user", "pubKeyCredParams" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "WebAuthn registration challenge.", "value": { "challenge": "abc...", "rp": { "id": "trustvice.com", "name": "Trustvice" }, "user": { "id": "u", "name": "owner@example.com", "displayName": "Ada" }, "pubKeyCredParams": [ { "type": "public-key", "alg": -7 } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "dashboard" ] } }, "/v1/actions/account.passkey.register-finish": { "post": { "operationId": "account_passkey_register-finish", "summary": "Complete passkey registration with the WebAuthn attestation response.", "x-trustvice-description-key": "actions.account.passkey.register-finish.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "nickname": { "type": "string", "minLength": 1, "maxLength": 80 }, "attestationObject": { "type": "string" }, "clientDataJSON": { "type": "string" } }, "required": [ "nickname", "attestationObject", "clientDataJSON" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Finish passkey registration.", "value": { "nickname": "YubiKey 5C", "attestationObject": "...", "clientDataJSON": "..." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "credentialId": { "type": "string" }, "nickname": { "type": "string", "minLength": 1, "maxLength": 80 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "aaguid": { "type": "string" }, "backupEligible": { "type": "boolean" } }, "required": [ "credentialId", "nickname", "createdAt", "lastUsedAt", "backupEligible" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Finish passkey registration.", "value": { "credentialId": "cred_abc", "nickname": "YubiKey 5C", "createdAt": "2026-05-22T12:00:00.000Z", "lastUsedAt": null, "backupEligible": false } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "admin.action", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "dashboard" ] } }, "/v1/actions/account.passkey.revoke": { "post": { "operationId": "account_passkey_revoke", "summary": "Revoke a registered passkey.", "x-trustvice-description-key": "actions.account.passkey.revoke.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "credentialId": { "type": "string" } }, "required": [ "credentialId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Remove a passkey.", "value": { "credentialId": "cred_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Remove a passkey.", "value": { "revoked": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "admin.action", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/account.recovery-codes.generate": { "post": { "operationId": "account_recovery-codes_generate", "summary": "Generate a fresh set of 10 single-use recovery codes (existing codes are invalidated).", "x-trustvice-description-key": "actions.account.recovery-codes.generate.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "10 fresh recovery codes.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "codes": { "minItems": 10, "maxItems": 10, "type": "array", "items": { "type": "string" } }, "generatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "codes", "generatedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "10 fresh recovery codes.", "value": { "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" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "admin.action", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "dashboard" ] } }, "/v1/actions/account.locale.set": { "post": { "operationId": "account_locale_set", "summary": "Set the account-level preferred locale (overrides browser default).", "x-trustvice-description-key": "actions.account.locale.set.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "locale": { "type": "string", "enum": [ "en", "es", "fr", "de", "de-du", "zh" ] } }, "required": [ "locale" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Switch UI language to German.", "value": { "locale": "de" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "locale": { "type": "string", "enum": [ "en", "es", "fr", "de", "de-du", "zh" ] } }, "required": [ "locale" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Switch UI language to German.", "value": { "locale": "de" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/account.display-preferences.set": { "post": { "operationId": "account_display-preferences_set", "summary": "Set the account-level display preferences: colour theme and IANA timezone. Either field may be omitted; neither is a no-op.", "x-trustvice-description-key": "actions.account.display-preferences.set.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "theme": { "type": "string", "enum": [ "system", "light", "dark" ] }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z][A-Za-z0-9_+\\-]*(\\/[A-Za-z0-9_+\\-]+)*$" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Dark theme, Berlin time.", "value": { "theme": "dark", "timezone": "Europe/Berlin" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "theme": { "type": "string", "enum": [ "system", "light", "dark" ] }, "timezone": { "type": "string" } }, "required": [ "theme", "timezone" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Dark theme, Berlin time.", "value": { "theme": "dark", "timezone": "Europe/Berlin" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/account.notifications.get": { "post": { "operationId": "account_notifications_get", "summary": "Read notification preferences.", "x-trustvice-description-key": "actions.account.notifications.get.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read prefs.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "marketingEmails": { "type": "boolean" }, "securityAlerts": { "type": "boolean" }, "billingAlerts": { "type": "boolean" }, "productUpdates": { "type": "boolean" }, "agentSessionStarted": { "type": "boolean" }, "agentSessionAnomaly": { "type": "boolean" }, "digestCadence": { "type": "string", "enum": [ "off", "daily", "weekly" ] }, "invitationAlerts": { "type": "boolean" }, "quotaWarnings": { "type": "boolean" }, "privacyRightsAlerts": { "type": "boolean" }, "shadowSessionStarted": { "type": "boolean" } }, "required": [ "marketingEmails", "securityAlerts", "billingAlerts", "productUpdates", "agentSessionStarted", "agentSessionAnomaly", "digestCadence" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read prefs.", "value": { "marketingEmails": false, "securityAlerts": true, "billingAlerts": true, "productUpdates": false, "agentSessionStarted": true, "agentSessionAnomaly": true, "digestCadence": "weekly" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/account.notifications.update": { "post": { "operationId": "account_notifications_update", "summary": "Update notification preferences.", "x-trustvice-description-key": "actions.account.notifications.update.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "marketingEmails": { "type": "boolean" }, "securityAlerts": { "type": "boolean" }, "billingAlerts": { "type": "boolean" }, "productUpdates": { "type": "boolean" }, "agentSessionStarted": { "type": "boolean" }, "agentSessionAnomaly": { "type": "boolean" }, "digestCadence": { "type": "string", "enum": [ "off", "daily", "weekly" ] }, "invitationAlerts": { "type": "boolean" }, "quotaWarnings": { "type": "boolean" }, "privacyRightsAlerts": { "type": "boolean" }, "shadowSessionStarted": { "type": "boolean" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Turn on anomaly alerts.", "value": { "agentSessionAnomaly": true } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "marketingEmails": { "type": "boolean" }, "securityAlerts": { "type": "boolean" }, "billingAlerts": { "type": "boolean" }, "productUpdates": { "type": "boolean" }, "agentSessionStarted": { "type": "boolean" }, "agentSessionAnomaly": { "type": "boolean" }, "digestCadence": { "type": "string", "enum": [ "off", "daily", "weekly" ] }, "invitationAlerts": { "type": "boolean" }, "quotaWarnings": { "type": "boolean" }, "privacyRightsAlerts": { "type": "boolean" }, "shadowSessionStarted": { "type": "boolean" } }, "required": [ "marketingEmails", "securityAlerts", "billingAlerts", "productUpdates", "agentSessionStarted", "agentSessionAnomaly", "digestCadence" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Turn on anomaly alerts.", "value": { "marketingEmails": false, "securityAlerts": true, "billingAlerts": true, "productUpdates": false, "agentSessionStarted": true, "agentSessionAnomaly": true, "digestCadence": "weekly" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/account.token.list": { "post": { "operationId": "account_token_list", "summary": "List your Personal Access Tokens (PATs).", "x-trustvice-description-key": "actions.account.token.list.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "includeRevoked": { "default": false, "type": "boolean" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "List active PATs.", "value": { "includeRevoked": false } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tv_pat_[0-9A-Z]{20,}$" }, "prefix": { "type": "string" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "ipCidrBinding": { "type": "string" } }, "required": [ "id", "prefix", "label", "scopes", "createdAt", "expiresAt", "lastUsedAt", "revokedAt" ], "additionalProperties": false } } }, "required": [ "tokens" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List active PATs.", "value": { "tokens": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/account.token.issue": { "post": { "operationId": "account_token_issue", "summary": "Issue a new Personal Access Token. Cleartext shown ONCE.", "x-trustvice-description-key": "actions.account.token.issue.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "expiresInDays": { "default": 90, "type": "integer", "minimum": 1, "maximum": 365 }, "ipCidrBinding": { "type": "string", "pattern": "^[0-9.]+\\/\\d{1,2}$" } }, "required": [ "label", "scopes" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Mint a new PAT; cleartext shown once.", "value": { "label": "CI pipeline", "scopes": [ "read:workspace", "write:entpoind" ], "expiresInDays": 90 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "token": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tv_pat_[0-9A-Z]{20,}$" }, "prefix": { "type": "string" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "ipCidrBinding": { "type": "string" } }, "required": [ "id", "prefix", "label", "scopes", "createdAt", "expiresAt", "lastUsedAt", "revokedAt" ], "additionalProperties": false }, "cleartext": { "type": "string" } }, "required": [ "token", "cleartext" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Mint a new PAT; cleartext shown once.", "value": { "token": { "id": "tv_pat_ABC20CHARSFOREXAMPLEID", "prefix": "tv_pat_abc", "label": "CI pipeline", "scopes": [ "read:workspace", "write:entpoind" ], "createdAt": "2026-05-22T12:00:00.000Z", "expiresAt": "2026-08-20T12:00:00.000Z", "lastUsedAt": null, "revokedAt": null }, "cleartext": "tv_pat_abc_REDACTED_EXAMPLE_ONLY" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "key.issued", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "dashboard" ] } }, "/v1/actions/account.token.revoke": { "post": { "operationId": "account_token_revoke", "summary": "Revoke a PAT (cannot be disabled — safety floor).", "x-trustvice-description-key": "actions.account.token.revoke.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tokenId": { "type": "string", "pattern": "^tv_pat_[0-9A-Z]{20,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "tokenId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Revoke a PAT.", "value": { "tokenId": "tv_pat_ABC20CHARSFOREXAMPLEID" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "revoked": { "type": "boolean" }, "propagatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "revoked", "propagatedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Revoke a PAT.", "value": { "revoked": true, "propagatedAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "key.revoked", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/account.oauth-grants.list": { "post": { "operationId": "account_oauth-grants_list", "summary": "List active OAuth grants to third-party agents (Claude, ChatGPT, Gemini, etc.).", "x-trustvice-description-key": "actions.account.oauth-grants.list.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "List active connected apps.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "grants": { "type": "array", "items": { "type": "object", "properties": { "clientId": { "type": "string", "pattern": "^oauth_[0-9A-Z]{20,}$" }, "clientName": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "grantedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "dpopBound": { "type": "boolean" }, "delegationDepthAllowed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "clientId", "clientName", "scopes", "grantedAt", "lastUsedAt", "expiresAt", "dpopBound", "delegationDepthAllowed" ], "additionalProperties": false } } }, "required": [ "grants" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List active connected apps.", "value": { "grants": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/account.oauth-grants.revoke": { "post": { "operationId": "account_oauth-grants_revoke", "summary": "Revoke an OAuth grant. The third-party agent's tokens are immediately invalidated.", "x-trustvice-description-key": "actions.account.oauth-grants.revoke.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "clientId": { "type": "string", "pattern": "^oauth_[0-9A-Z]{20,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "clientId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Kill a connected app session.", "value": { "clientId": "oauth_CLAUDECOWORK0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "revoked": { "type": "boolean" }, "propagatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "revoked", "propagatedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Kill a connected app session.", "value": { "revoked": true, "propagatedAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "key.revoked", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/account.security-log.list": { "post": { "operationId": "account_security-log_list", "summary": "Read the account-level security log (logins, MFA, key issuance, anomalies).", "x-trustvice-description-key": "actions.account.security-log.list.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "kindFilter": { "type": "array", "items": { "type": "string" } }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Last 25 security events.", "value": { "limit": 25 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "kind": { "type": "string", "enum": [ "login_success", "login_failure", "logout", "passkey_registered", "passkey_revoked", "pat_issued", "pat_revoked", "oauth_grant_approved", "oauth_grant_revoked", "anomalous_login_location", "step_up_prompt", "recovery_code_used", "email_changed", "password_changed" ] }, "summary": { "type": "string" }, "ipPrefix": { "type": "string" }, "authMethod": { "type": "string", "enum": [ "session_cookie", "pat", "workspace_api_key", "oauth_access_token", "oauth_access_token_dpop", "mtls_svid", "sidecar_token" ] } }, "required": [ "timestamp", "kind", "summary" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "entries", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Last 25 security events.", "value": { "entries": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/account.delete": { "post": { "operationId": "account_delete", "summary": "Schedule account deletion in 30 days. Requires WebAuthn step-up.", "x-trustvice-description-key": "actions.account.delete.description", "tags": [ "account" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reason": { "type": "string", "minLength": 10, "maxLength": 500 }, "exportFirst": { "default": true, "type": "boolean" } }, "required": [ "reason" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Start account deletion with grace period.", "value": { "reason": "I no longer use this account; please delete in 30 days", "exportFirst": true } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scheduledDeletionAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "gracePeriodDays": { "type": "number", "const": 30 } }, "required": [ "scheduledDeletionAt", "gracePeriodDays" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Start account deletion with grace period.", "value": { "scheduledDeletionAt": "2026-06-21T00:00:00.000Z", "gracePeriodDays": 30 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "admin.action", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.get": { "post": { "operationId": "org_get", "summary": "Get the current organization's details.", "x-trustvice-description-key": "actions.org.get.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read org metadata.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9A-Z]{20,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "plan": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "scheduledDeletionAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "locale": { "type": "string", "enum": [ "en", "es", "fr", "de", "de-du", "zh" ] } }, "required": [ "id", "name", "plan", "createdAt", "scheduledDeletionAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read org metadata.", "value": { "id": "org_DEMO00000000000000000000", "name": "Demo Org", "plan": "pro", "createdAt": "2026-01-01T00:00:00.000Z", "scheduledDeletionAt": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.update": { "post": { "operationId": "org_update", "summary": "Update organization name + locale.", "x-trustvice-description-key": "actions.org.update.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "locale": { "type": "string", "enum": [ "en", "es", "fr", "de", "de-du", "zh" ] } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Rename the organization.", "value": { "name": "New Org Name" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9A-Z]{20,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "plan": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "scheduledDeletionAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "locale": { "type": "string", "enum": [ "en", "es", "fr", "de", "de-du", "zh" ] } }, "required": [ "id", "name", "plan", "createdAt", "scheduledDeletionAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Rename the organization.", "value": { "id": "org_DEMO00000000000000000000", "name": "New Org Name", "plan": "pro", "createdAt": "2026-01-01T00:00:00.000Z", "scheduledDeletionAt": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "organization.rename" ] }, { "OAuth2": [ "organization.rename" ] }, { "WorkspaceApiKey": [ "organization.rename" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "admin.action", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.locale.set": { "post": { "operationId": "org_locale_set", "summary": "Set the organization-default locale (inherited by new workspaces).", "x-trustvice-description-key": "actions.org.locale.set.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "locale": { "type": "string", "enum": [ "en", "es", "fr", "de", "de-du", "zh" ] } }, "required": [ "locale" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Org-default locale → German.", "value": { "locale": "de" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "locale": { "type": "string", "enum": [ "en", "es", "fr", "de", "de-du", "zh" ] } }, "required": [ "locale" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Org-default locale → German.", "value": { "locale": "de" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "organization.rename" ] }, { "OAuth2": [ "organization.rename" ] }, { "WorkspaceApiKey": [ "organization.rename" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.billing-state.get": { "post": { "operationId": "org_billing-state_get", "summary": "Get the org's current billing state (plan, subscription status, add-ons).", "x-trustvice-description-key": "actions.org.billing-state.get.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read billing state.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "plan": { "type": "string" }, "subscriptionStatus": { "type": "string", "enum": [ "trialing", "active", "past_due", "canceled", "unpaid", "suspended" ] }, "multiWorkspaceAddonActive": { "type": "boolean" }, "extraWorkspacesCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currentPeriodEnd": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "plan", "subscriptionStatus", "multiWorkspaceAddonActive", "extraWorkspacesCount", "currentPeriodEnd" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read billing state.", "value": { "plan": "pro", "subscriptionStatus": "active", "multiWorkspaceAddonActive": true, "extraWorkspacesCount": 2, "currentPeriodEnd": "2026-06-22T00:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.view" ] }, { "OAuth2": [ "billing.view" ] }, { "WorkspaceApiKey": [ "billing.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.member.list": { "post": { "operationId": "org_member_list", "summary": "List organization members.", "x-trustvice-description-key": "actions.org.member.list.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "List org members.", "value": { "limit": 25 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "members": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^acc_[0-9A-Z]{20,}$" }, "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 80 }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "joinedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "accountId", "email", "role", "joinedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "members", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List org members.", "value": { "members": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "members.view" ] }, { "OAuth2": [ "members.view" ] }, { "WorkspaceApiKey": [ "members.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.member.invite": { "post": { "operationId": "org_member_invite", "summary": "Invite a new member to the organization. Sends a verification email.", "x-trustvice-description-key": "actions.org.member.invite.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] } }, "required": [ "email", "role" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Invite a new member.", "value": { "email": "newmember@example.com", "role": "member" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "invitationId": { "type": "string" }, "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "invitedBy": { "type": "string", "pattern": "^acc_[0-9A-Z]{20,}$" }, "invitedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "status": { "type": "string", "enum": [ "pending", "accepted", "expired", "revoked" ] } }, "required": [ "invitationId", "email", "role", "invitedBy", "invitedAt", "expiresAt", "status" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Invite a new member.", "value": { "invitationId": "inv_abc", "email": "newmember@example.com", "role": "member", "invitedBy": "acc_DEMO00000000000000000000", "invitedAt": "2026-05-22T12:00:00.000Z", "expiresAt": "2026-05-29T12:00:00.000Z", "status": "pending" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "members.invite" ] }, { "OAuth2": [ "members.invite" ] }, { "WorkspaceApiKey": [ "members.invite" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "member.invited", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.member.remove": { "post": { "operationId": "org_member_remove", "summary": "Remove a member from the organization. They lose access to all workspaces immediately.", "x-trustvice-description-key": "actions.org.member.remove.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^acc_[0-9A-Z]{20,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "accountId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Remove a member.", "value": { "accountId": "acc_DEMO00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "removed": { "type": "boolean" } }, "required": [ "removed" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Remove a member.", "value": { "removed": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "members.remove" ] }, { "OAuth2": [ "members.remove" ] }, { "WorkspaceApiKey": [ "members.remove" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "member.removed", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.member.role.change": { "post": { "operationId": "org_member_role_change", "summary": "Change an org member's role.", "x-trustvice-description-key": "actions.org.member.role.change.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^acc_[0-9A-Z]{20,}$" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] } }, "required": [ "accountId", "role" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Promote to admin.", "value": { "accountId": "acc_DEMO00000000000000000000", "role": "admin" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^acc_[0-9A-Z]{20,}$" }, "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 80 }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "joinedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "accountId", "email", "role", "joinedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Promote to admin.", "value": { "accountId": "acc_DEMO00000000000000000000", "email": "member@example.com", "role": "admin", "joinedAt": "2026-01-01T00:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "members.change_role" ] }, { "OAuth2": [ "members.change_role" ] }, { "WorkspaceApiKey": [ "members.change_role" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "member.role_changed", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.invitations.list": { "post": { "operationId": "org_invitations_list", "summary": "List pending/expired invitations.", "x-trustvice-description-key": "actions.org.invitations.list.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "accepted", "expired", "revoked" ] } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "List pending invites.", "value": { "status": "pending" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "invitations": { "type": "array", "items": { "type": "object", "properties": { "invitationId": { "type": "string" }, "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "invitedBy": { "type": "string", "pattern": "^acc_[0-9A-Z]{20,}$" }, "invitedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "status": { "type": "string", "enum": [ "pending", "accepted", "expired", "revoked" ] } }, "required": [ "invitationId", "email", "role", "invitedBy", "invitedAt", "expiresAt", "status" ], "additionalProperties": false } } }, "required": [ "invitations" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List pending invites.", "value": { "invitations": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "members.view" ] }, { "OAuth2": [ "members.view" ] }, { "WorkspaceApiKey": [ "members.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.invitations.resend": { "post": { "operationId": "org_invitations_resend", "summary": "Resend a pending invitation (subject to 5-minute cooldown).", "x-trustvice-description-key": "actions.org.invitations.resend.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "invitationId": { "type": "string" } }, "required": [ "invitationId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Resend invite.", "value": { "invitationId": "inv_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "resent": { "type": "boolean" }, "nextResendAvailableAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "resent", "nextResendAvailableAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Resend invite.", "value": { "resent": true, "nextResendAvailableAt": "2026-05-22T12:05:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "members.invite" ] }, { "OAuth2": [ "members.invite" ] }, { "WorkspaceApiKey": [ "members.invite" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "member.invited", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.invitations.revoke": { "post": { "operationId": "org_invitations_revoke", "summary": "Revoke a pending invitation.", "x-trustvice-description-key": "actions.org.invitations.revoke.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "invitationId": { "type": "string" } }, "required": [ "invitationId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Cancel pending invite.", "value": { "invitationId": "inv_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Cancel pending invite.", "value": { "revoked": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "members.invite" ] }, { "OAuth2": [ "members.invite" ] }, { "WorkspaceApiKey": [ "members.invite" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "member.removed", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.transfer-ownership": { "post": { "operationId": "org_transfer-ownership", "summary": "Transfer org ownership to another admin. Requires WebAuthn step-up + reason.", "x-trustvice-description-key": "actions.org.transfer-ownership.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "newOwnerAccountId": { "type": "string", "pattern": "^acc_[0-9A-Z]{20,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "newOwnerAccountId", "reason" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Hand off org ownership.", "value": { "newOwnerAccountId": "acc_DEMO00000000000000000000", "reason": "Stepping down from CEO role; handing over to incoming lead" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9A-Z]{20,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "plan": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "scheduledDeletionAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "locale": { "type": "string", "enum": [ "en", "es", "fr", "de", "de-du", "zh" ] } }, "required": [ "id", "name", "plan", "createdAt", "scheduledDeletionAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Hand off org ownership.", "value": { "id": "org_DEMO00000000000000000000", "name": "Demo Org", "plan": "pro", "createdAt": "2026-01-01T00:00:00.000Z", "scheduledDeletionAt": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "organization.transfer_ownership" ] }, { "OAuth2": [ "organization.transfer_ownership" ] }, { "WorkspaceApiKey": [ "organization.transfer_ownership" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "admin.action", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.delete.schedule": { "post": { "operationId": "org_delete_schedule", "summary": "Schedule organization deletion in 30 days. Cancellable within the grace window.", "x-trustvice-description-key": "actions.org.delete.schedule.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reason": { "type": "string", "minLength": 10, "maxLength": 500 }, "graceDays": { "default": 30, "type": "integer", "minimum": 1, "maximum": 90 } }, "required": [ "reason" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Schedule org deletion.", "value": { "reason": "Winding down the company; please delete after 30 days of grace" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scheduledDeletionAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "scheduledDeletionAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Schedule org deletion.", "value": { "scheduledDeletionAt": "2026-06-21T00:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "organization.delete" ] }, { "OAuth2": [ "organization.delete" ] }, { "WorkspaceApiKey": [ "organization.delete" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "admin.action", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.delete.cancel": { "post": { "operationId": "org_delete_cancel", "summary": "Cancel a previously-scheduled org deletion (within grace).", "x-trustvice-description-key": "actions.org.delete.cancel.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Cancel scheduled deletion.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^org_[0-9A-Z]{20,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "plan": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "scheduledDeletionAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "locale": { "type": "string", "enum": [ "en", "es", "fr", "de", "de-du", "zh" ] } }, "required": [ "id", "name", "plan", "createdAt", "scheduledDeletionAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Cancel scheduled deletion.", "value": { "id": "org_DEMO00000000000000000000", "name": "Demo Org", "plan": "pro", "createdAt": "2026-01-01T00:00:00.000Z", "scheduledDeletionAt": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "organization.delete" ] }, { "OAuth2": [ "organization.delete" ] }, { "WorkspaceApiKey": [ "organization.delete" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "admin.action", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.audit.list": { "post": { "operationId": "org_audit_list", "summary": "Read org-level audit log entries (admin actions, member changes, billing).", "x-trustvice-description-key": "actions.org.audit.list.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read org audit log.", "value": { "limit": 25 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entries": { "type": "array", "items": {} }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "entries", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read org audit log.", "value": { "entries": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view_audit_log" ] }, { "OAuth2": [ "settings.view_audit_log" ] }, { "WorkspaceApiKey": [ "settings.view_audit_log" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.sso.connections.list": { "post": { "operationId": "org_sso_connections_list", "summary": "List the organization's SSO connections (SAML/OIDC), with sealed secrets redacted to booleans.", "x-trustvice-description-key": "actions.org.sso.connections.list.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "List SSO connections.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "type": { "type": "string", "enum": [ "saml", "oidc" ] }, "displayName": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "disabled", "testing" ] }, "samlIdpEntityId": { "type": [ "string", "null" ] }, "samlIdpSsoUrl": { "type": [ "string", "null" ] }, "samlIdpCertificateCount": { "type": "number" }, "samlAllowIdpInitiated": { "type": "boolean" }, "oidcIssuer": { "type": [ "string", "null" ] }, "oidcClientId": { "type": [ "string", "null" ] }, "oidcClientSecretSet": { "type": "boolean" }, "jitEnabled": { "type": "boolean" }, "defaultRole": { "type": "string", "enum": [ "admin", "member" ] }, "groupRoleMappings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "type", "displayName", "status", "samlIdpEntityId", "samlIdpSsoUrl", "samlIdpCertificateCount", "samlAllowIdpInitiated", "oidcIssuer", "oidcClientId", "oidcClientSecretSet", "jitEnabled", "defaultRole", "groupRoleMappings", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "connections" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List SSO connections.", "value": { "connections": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.configure_sso" ] }, { "OAuth2": [ "settings.configure_sso" ] }, { "WorkspaceApiKey": [ "settings.configure_sso" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.sso.connections.upsert": { "post": { "operationId": "org_sso_connections_upsert", "summary": "Create or update a SAML/OIDC SSO connection. A provided OIDC client secret is sealed; SAML certificates are validated.", "x-trustvice-description-key": "actions.org.sso.connections.upsert.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "saml", "oidc" ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 120 }, "status": { "type": "string", "enum": [ "active", "disabled", "testing" ] }, "jitEnabled": { "type": "boolean" }, "defaultRole": { "type": "string", "enum": [ "admin", "member" ] }, "groupRoleMappings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "enum": [ "admin", "member" ] } }, "samlIdpEntityId": { "type": "string" }, "samlIdpSsoUrl": { "type": "string", "format": "uri" }, "samlIdpCertificates": { "type": "string" }, "samlAllowIdpInitiated": { "type": "boolean" }, "oidcIssuer": { "type": "string", "format": "uri" }, "oidcClientId": { "type": "string" }, "oidcClientSecret": { "type": "string" } }, "required": [ "type", "displayName" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Create an OIDC connection.", "value": { "type": "oidc", "displayName": "Okta", "oidcIssuer": "https://acme.okta.com", "oidcClientId": "0oa1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "connection": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "type": { "type": "string", "enum": [ "saml", "oidc" ] }, "displayName": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "disabled", "testing" ] }, "samlIdpEntityId": { "type": [ "string", "null" ] }, "samlIdpSsoUrl": { "type": [ "string", "null" ] }, "samlIdpCertificateCount": { "type": "number" }, "samlAllowIdpInitiated": { "type": "boolean" }, "oidcIssuer": { "type": [ "string", "null" ] }, "oidcClientId": { "type": [ "string", "null" ] }, "oidcClientSecretSet": { "type": "boolean" }, "jitEnabled": { "type": "boolean" }, "defaultRole": { "type": "string", "enum": [ "admin", "member" ] }, "groupRoleMappings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "type", "displayName", "status", "samlIdpEntityId", "samlIdpSsoUrl", "samlIdpCertificateCount", "samlAllowIdpInitiated", "oidcIssuer", "oidcClientId", "oidcClientSecretSet", "jitEnabled", "defaultRole", "groupRoleMappings", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "connection" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Create an OIDC connection.", "value": { "connection": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.configure_sso" ] }, { "OAuth2": [ "settings.configure_sso" ] }, { "WorkspaceApiKey": [ "settings.configure_sso" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "org.sso_config_changed", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.sso.connections.delete": { "post": { "operationId": "org_sso_connections_delete", "summary": "Delete an SSO connection by id (org-scoped).", "x-trustvice-description-key": "actions.org.sso.connections.delete.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete a connection.", "value": { "id": "ssoc_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete a connection.", "value": { "deleted": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.configure_sso" ] }, { "OAuth2": [ "settings.configure_sso" ] }, { "WorkspaceApiKey": [ "settings.configure_sso" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "org.sso_config_changed", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.sso.domains.list": { "post": { "operationId": "org_sso_domains_list", "summary": "List the organization's captured SSO domains (verified state + the DNS TXT record to publish).", "x-trustvice-description-key": "actions.org.sso.domains.list.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "List SSO domains.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "connectionId": { "type": [ "string", "null" ] }, "domain": { "type": "string" }, "verified": { "type": "boolean" }, "verifiedAt": { "type": [ "string", "null" ] }, "enforceSso": { "type": "boolean" }, "dnsRecord": { "type": "object", "properties": { "host": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" } }, "required": [ "host", "type", "value" ], "additionalProperties": false }, "createdAt": { "type": "string" } }, "required": [ "id", "organizationId", "connectionId", "domain", "verified", "verifiedAt", "enforceSso", "dnsRecord", "createdAt" ], "additionalProperties": false } } }, "required": [ "domains" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List SSO domains.", "value": { "domains": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.configure_sso" ] }, { "OAuth2": [ "settings.configure_sso" ] }, { "WorkspaceApiKey": [ "settings.configure_sso" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.sso.domains.create": { "post": { "operationId": "org_sso_domains_create", "summary": "Claim an email domain for SSO and mint its DNS TXT verification challenge.", "x-trustvice-description-key": "actions.org.sso.domains.create.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "domain": { "type": "string", "minLength": 3, "maxLength": 253 }, "connectionId": { "type": "string" } }, "required": [ "domain" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Claim acme.com.", "value": { "domain": "acme.com" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "domain": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "connectionId": { "type": [ "string", "null" ] }, "domain": { "type": "string" }, "verified": { "type": "boolean" }, "verifiedAt": { "type": [ "string", "null" ] }, "enforceSso": { "type": "boolean" }, "dnsRecord": { "type": "object", "properties": { "host": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" } }, "required": [ "host", "type", "value" ], "additionalProperties": false }, "createdAt": { "type": "string" } }, "required": [ "id", "organizationId", "connectionId", "domain", "verified", "verifiedAt", "enforceSso", "dnsRecord", "createdAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "domain" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Claim acme.com.", "value": { "domain": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.configure_sso" ] }, { "OAuth2": [ "settings.configure_sso" ] }, { "WorkspaceApiKey": [ "settings.configure_sso" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "org.sso_config_changed", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.sso.domains.verify": { "post": { "operationId": "org_sso_domains_verify", "summary": "Verify a claimed domain via a DNS-over-HTTPS TXT lookup (proof of control).", "x-trustvice-description-key": "actions.org.sso.domains.verify.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify domain control.", "value": { "id": "ssod_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "verified": { "type": "boolean" }, "domain": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "connectionId": { "type": [ "string", "null" ] }, "domain": { "type": "string" }, "verified": { "type": "boolean" }, "verifiedAt": { "type": [ "string", "null" ] }, "enforceSso": { "type": "boolean" }, "dnsRecord": { "type": "object", "properties": { "host": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" } }, "required": [ "host", "type", "value" ], "additionalProperties": false }, "createdAt": { "type": "string" } }, "required": [ "id", "organizationId", "connectionId", "domain", "verified", "verifiedAt", "enforceSso", "dnsRecord", "createdAt" ], "additionalProperties": false }, { "type": "null" } ] }, "alreadyVerified": { "type": "boolean" } }, "required": [ "verified" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify domain control.", "value": { "verified": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.configure_sso" ] }, { "OAuth2": [ "settings.configure_sso" ] }, { "WorkspaceApiKey": [ "settings.configure_sso" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "org.sso_config_changed", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.sso.domains.enforcement": { "post": { "operationId": "org_sso_domains_enforcement", "summary": "Toggle SSO enforcement for a verified domain (requires a verified domain + an active connection).", "x-trustvice-description-key": "actions.org.sso.domains.enforcement.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "enforceSso": { "type": "boolean" } }, "required": [ "id", "enforceSso" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Require SSO for the domain.", "value": { "id": "ssod_abc", "enforceSso": true } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "domain": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "connectionId": { "type": [ "string", "null" ] }, "domain": { "type": "string" }, "verified": { "type": "boolean" }, "verifiedAt": { "type": [ "string", "null" ] }, "enforceSso": { "type": "boolean" }, "dnsRecord": { "type": "object", "properties": { "host": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" } }, "required": [ "host", "type", "value" ], "additionalProperties": false }, "createdAt": { "type": "string" } }, "required": [ "id", "organizationId", "connectionId", "domain", "verified", "verifiedAt", "enforceSso", "dnsRecord", "createdAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "domain" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Require SSO for the domain.", "value": { "domain": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.configure_sso" ] }, { "OAuth2": [ "settings.configure_sso" ] }, { "WorkspaceApiKey": [ "settings.configure_sso" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "org.sso_config_changed", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.sso.domains.delete": { "post": { "operationId": "org_sso_domains_delete", "summary": "Remove a captured SSO domain (org-scoped).", "x-trustvice-description-key": "actions.org.sso.domains.delete.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete a domain.", "value": { "id": "ssod_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete a domain.", "value": { "deleted": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.configure_sso" ] }, { "OAuth2": [ "settings.configure_sso" ] }, { "WorkspaceApiKey": [ "settings.configure_sso" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "org.sso_config_changed", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.sso.scim-tokens.list": { "post": { "operationId": "org_sso_scim-tokens_list", "summary": "List a connection's SCIM bearer tokens (hash-only; the raw token is never returned).", "x-trustvice-description-key": "actions.org.sso.scim-tokens.list.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "List SCIM tokens.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "connectionId": { "type": "string" }, "createdAt": { "type": "string" }, "lastUsedAt": { "type": [ "string", "null" ] }, "revoked": { "type": "boolean" }, "revokedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "connectionId", "createdAt", "lastUsedAt", "revoked", "revokedAt" ], "additionalProperties": false } } }, "required": [ "tokens" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List SCIM tokens.", "value": { "tokens": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.configure_sso" ] }, { "OAuth2": [ "settings.configure_sso" ] }, { "WorkspaceApiKey": [ "settings.configure_sso" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.sso.scim-tokens.mint": { "post": { "operationId": "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.", "x-trustvice-description-key": "actions.org.sso.scim-tokens.mint.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "connectionId": { "type": "string" } }, "required": [ "connectionId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Mint a SCIM token (shown once).", "value": { "connectionId": "ssoc_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "connectionId": { "type": "string" }, "token": { "type": "string" }, "scimBaseUrl": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "connectionId", "token", "scimBaseUrl", "createdAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Mint a SCIM token (shown once).", "value": { "id": "scimt_1", "connectionId": "ssoc_abc", "token": "scim_…", "scimBaseUrl": "https://api.trustvice.com/scim/v2", "createdAt": "2026-07-21T00:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.configure_sso" ] }, { "OAuth2": [ "settings.configure_sso" ] }, { "WorkspaceApiKey": [ "settings.configure_sso" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "org.sso_config_changed", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/org.sso.scim-tokens.revoke": { "post": { "operationId": "org_sso_scim-tokens_revoke", "summary": "Revoke a SCIM bearer token by id.", "x-trustvice-description-key": "actions.org.sso.scim-tokens.revoke.description", "tags": [ "org" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Revoke a SCIM token.", "value": { "id": "scimt_1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Revoke a SCIM token.", "value": { "revoked": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.configure_sso" ] }, { "OAuth2": [ "settings.configure_sso" ] }, { "WorkspaceApiKey": [ "settings.configure_sso" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "org.sso_config_changed", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/workspace.list": { "post": { "operationId": "workspace_list", "summary": "List all workspaces in the current organization.", "x-trustvice-description-key": "actions.workspace.list.description", "tags": [ "workspace" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "includeDeleted": { "default": false, "type": "boolean" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "List up to 10 workspaces in the active organization.", "value": { "limit": 10 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaces": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "organizationId": { "type": "string" }, "jurisdiction": { "type": "string", "enum": [ "WEUR", "ENAM" ] } }, "required": [ "id", "name", "organizationId", "jurisdiction" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "workspaces", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List up to 10 workspaces in the active organization.", "value": { "workspaces": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "workspaces.view" ] }, { "OAuth2": [ "workspaces.view" ] }, { "WorkspaceApiKey": [ "workspaces.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/workspace.get": { "post": { "operationId": "workspace_get", "summary": "Get the full state of a single workspace by id.", "x-trustvice-description-key": "actions.workspace.get.description", "tags": [ "workspace" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read the active workspace's full state.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "organizationId": { "type": "string" }, "jurisdiction": { "type": "string", "enum": [ "WEUR", "ENAM" ] } }, "required": [ "id", "name", "organizationId", "jurisdiction" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read the active workspace's full state.", "value": { "id": "ws_DEMODEFAULT0000000000", "name": "Default workspace" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "workspaces.view" ] }, { "OAuth2": [ "workspaces.view" ] }, { "WorkspaceApiKey": [ "workspaces.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/workspace.create": { "post": { "operationId": "workspace_create", "summary": "Create a new workspace in the current organization.", "x-trustvice-description-key": "actions.workspace.create.description", "tags": [ "workspace" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "regionId": { "type": "string", "pattern": "^(cloudflare-d1|aws-aurora):[a-z0-9-]+$" }, "euJurisdictionBound": { "default": false, "type": "boolean" }, "retentionDays": { "type": "integer", "minimum": 7, "maximum": 1825 }, "locale": { "type": "string", "enum": [ "en", "es", "fr", "de", "de-du", "zh" ] } }, "required": [ "name", "regionId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Create an EU-bound workspace in Western Europe.", "value": { "name": "EU production", "regionId": "cloudflare-d1:weur-1", "euJurisdictionBound": true } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "organizationId": { "type": "string" }, "jurisdiction": { "type": "string", "enum": [ "WEUR", "ENAM" ] } }, "required": [ "id", "name", "organizationId", "jurisdiction" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Create an EU-bound workspace in Western Europe.", "value": { "id": "ws_new", "name": "EU production", "organizationId": "org_demo", "jurisdiction": "WEUR" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "workspaces.create" ] }, { "OAuth2": [ "workspaces.create" ] }, { "WorkspaceApiKey": [ "workspaces.create" ] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "billing", "x-trustvice-audit-kind": "workspace.created", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/workspace.update": { "post": { "operationId": "workspace_update", "summary": "Update workspace settings (name, retention, locale, Trustvice Receipts controls).", "x-trustvice-description-key": "actions.workspace.update.description", "tags": [ "workspace" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "retentionDays": { "type": "integer", "minimum": 7, "maximum": 1825 }, "locale": { "type": "string", "enum": [ "en", "es", "fr", "de", "de-du", "zh" ] }, "entpoindAutoOverageEnabled": { "type": "boolean" }, "entpoindAutoOverageCapMultiplier": { "type": "integer", "minimum": 1, "maximum": 10 }, "entpoindBillingMode": { "type": "string", "enum": [ "combined", "separate" ] } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Rename a workspace — the one field this surface updates today.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "name": "Default" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "organizationId": { "type": "string" }, "jurisdiction": { "type": "string", "enum": [ "WEUR", "ENAM" ] } }, "required": [ "id", "name", "organizationId", "jurisdiction" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Rename a workspace — the one field this surface updates today.", "value": { "id": "ws_DEMODEFAULT0000000000", "name": "Default", "organizationId": "org_demo", "jurisdiction": "WEUR" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view", "workspace.rename" ] }, { "OAuth2": [ "settings.view", "workspace.rename" ] }, { "WorkspaceApiKey": [ "settings.view", "workspace.rename" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "workspace.renamed", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/workspace.rename": { "post": { "operationId": "workspace_rename", "summary": "Rename a workspace (convenience alias of workspace.update).", "x-trustvice-description-key": "actions.workspace.rename.description", "tags": [ "workspace" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "workspaceId", "name" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Rename a workspace.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "name": "EU production v2" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "organizationId": { "type": "string" }, "jurisdiction": { "type": "string", "enum": [ "WEUR", "ENAM" ] } }, "required": [ "id", "name", "organizationId", "jurisdiction" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Rename a workspace.", "value": { "id": "ws_DEMODEFAULT0000000000", "name": "EU production v2", "organizationId": "org_demo", "jurisdiction": "WEUR" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view", "workspace.rename" ] }, { "OAuth2": [ "settings.view", "workspace.rename" ] }, { "WorkspaceApiKey": [ "settings.view", "workspace.rename" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "workspace.renamed", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/workspace.delete.schedule": { "post": { "operationId": "workspace_delete_schedule", "summary": "Schedule a workspace for deletion in 30 days (grace period).", "x-trustvice-description-key": "actions.workspace.delete.schedule.description", "tags": [ "workspace" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "graceDays": { "default": 30, "type": "integer", "minimum": 1, "maximum": 90 }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "reason" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Schedule deletion with a 30-day grace.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "reason": "Migrated to new workspace; cleanup in progress" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "scheduledDeletionAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "workspaceId", "scheduledDeletionAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Schedule deletion with a 30-day grace.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "scheduledDeletionAt": "2026-06-21T00:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "workspaces.delete", "workspace.schedule_deletion" ] }, { "OAuth2": [ "workspaces.delete", "workspace.schedule_deletion" ] }, { "WorkspaceApiKey": [ "workspaces.delete", "workspace.schedule_deletion" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "workspace.scheduled_deletion", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/workspace.delete.cancel": { "post": { "operationId": "workspace_delete_cancel", "summary": "Cancel a previously-scheduled workspace deletion (within grace).", "x-trustvice-description-key": "actions.workspace.delete.cancel.description", "tags": [ "workspace" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Cancel deletion within the grace window.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "organizationId": { "type": "string" }, "jurisdiction": { "type": "string", "enum": [ "WEUR", "ENAM" ] } }, "required": [ "id", "name", "organizationId", "jurisdiction" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Cancel deletion within the grace window.", "value": { "id": "ws_DEMODEFAULT0000000000", "name": "Default", "organizationId": "org_demo", "jurisdiction": "WEUR" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "workspaces.delete", "workspace.schedule_deletion" ] }, { "OAuth2": [ "workspaces.delete", "workspace.schedule_deletion" ] }, { "WorkspaceApiKey": [ "workspaces.delete", "workspace.schedule_deletion" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "workspace.deletion_canceled", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/workspace.region.binding-proof": { "post": { "operationId": "workspace_region_binding-proof", "summary": "Download the OpenTimestamps proof of the workspace's region binding.", "x-trustvice-description-key": "actions.workspace.region.binding-proof.description", "tags": [ "workspace" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Pull the region-binding OTS proof for offline verification.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "otsProof": { "type": "string", "minLength": 20 }, "anchoredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "blockHeight": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "otsProof", "anchoredAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Pull the region-binding OTS proof for offline verification.", "value": { "otsProof": "base64-encoded-ots-proof-string-here-at-least-20-chars", "anchoredAt": "2026-05-22T12:00:00.000Z", "blockHeight": 854321 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "workspaces.view" ] }, { "OAuth2": [ "workspaces.view" ] }, { "WorkspaceApiKey": [ "workspaces.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/workspace.member.list": { "post": { "operationId": "workspace_member_list", "summary": "List members of a workspace with their roles.", "x-trustvice-description-key": "actions.workspace.member.list.description", "tags": [ "workspace" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List workspace members.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "members": { "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^acc_[0-9A-Z]{20,}$" }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "auditor" ] } }, "required": [ "accountId", "role" ], "additionalProperties": {} } } }, "required": [ "members" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List workspace members.", "value": { "members": [ { "accountId": "acc_001demo000000000000000000", "role": "owner" } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "workspaces.view" ] }, { "OAuth2": [ "workspaces.view" ] }, { "WorkspaceApiKey": [ "workspaces.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/workspace.member.add": { "post": { "operationId": "workspace_member_add", "summary": "Add an organization member to a workspace with a specific role.", "x-trustvice-description-key": "actions.workspace.member.add.description", "tags": [ "workspace" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "accountId": { "type": "string", "pattern": "^acc_[0-9A-Z]{20,}$" }, "role": { "type": "string", "enum": [ "admin", "member", "auditor" ] } }, "required": [ "workspaceId", "accountId", "role" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Add a member.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "accountId": "acc_002DEMO000000000000000000", "role": "member" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^acc_[0-9A-Z]{20,}$" }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "auditor" ] } }, "required": [ "accountId", "role" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Add a member.", "value": { "accountId": "acc_002DEMO000000000000000000", "role": "member" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "members.invite" ] }, { "OAuth2": [ "members.invite" ] }, { "WorkspaceApiKey": [ "members.invite" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "member.joined", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/workspace.member.role.change": { "post": { "operationId": "workspace_member_role_change", "summary": "Change a workspace member's role.", "x-trustvice-description-key": "actions.workspace.member.role.change.description", "tags": [ "workspace" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "accountId": { "type": "string", "pattern": "^acc_[0-9A-Z]{20,}$" }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "auditor" ] } }, "required": [ "workspaceId", "accountId", "role" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Promote a member to admin.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "accountId": "acc_002DEMO000000000000000000", "role": "admin" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^acc_[0-9A-Z]{20,}$" }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "auditor" ] } }, "required": [ "accountId", "role" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Promote a member to admin.", "value": { "accountId": "acc_002DEMO000000000000000000", "role": "admin" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "members.change_role" ] }, { "OAuth2": [ "members.change_role" ] }, { "WorkspaceApiKey": [ "members.change_role" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "member.role_changed", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/workspace.member.remove": { "post": { "operationId": "workspace_member_remove", "summary": "Remove a member from a workspace.", "x-trustvice-description-key": "actions.workspace.member.remove.description", "tags": [ "workspace" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "accountId": { "type": "string", "pattern": "^acc_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId", "accountId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Remove a workspace member.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "accountId": "acc_002DEMO000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "removed": { "type": "boolean" } }, "required": [ "removed" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Remove a workspace member.", "value": { "removed": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "members.remove" ] }, { "OAuth2": [ "members.remove" ] }, { "WorkspaceApiKey": [ "members.remove" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "member.removed", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/workspace.transfer-ownership": { "post": { "operationId": "workspace_transfer-ownership", "summary": "Transfer workspace ownership to another admin.", "x-trustvice-description-key": "actions.workspace.transfer-ownership.description", "tags": [ "workspace" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "newOwnerAccountId": { "type": "string", "pattern": "^acc_[0-9A-Z]{20,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "newOwnerAccountId", "reason" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Transfer ownership — destructive, requires confirmation.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "newOwnerAccountId": "acc_002DEMO000000000000000000", "reason": "Handing over to new compliance lead per Q3 reorg" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "organizationId": { "type": "string" }, "jurisdiction": { "type": "string", "enum": [ "WEUR", "ENAM" ] } }, "required": [ "id", "name", "organizationId", "jurisdiction" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Transfer ownership — destructive, requires confirmation.", "value": { "id": "ws_DEMODEFAULT0000000000", "name": "Default", "organizationId": "org_demo", "jurisdiction": "WEUR" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "workspaces.transfer" ] }, { "OAuth2": [ "workspaces.transfer" ] }, { "WorkspaceApiKey": [ "workspaces.transfer" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "admin.action", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/workspace.entpoind.enable": { "post": { "operationId": "workspace_entpoind_enable", "summary": "Enable Trustvice Receipts on a workspace (requires an org-level Trustvice Receipts subscription).", "x-trustvice-description-key": "actions.workspace.entpoind.enable.description", "tags": [ "workspace" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Enable Trustvice Receipts on a workspace.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "organizationId": { "type": "string" }, "jurisdiction": { "type": "string", "enum": [ "WEUR", "ENAM" ] } }, "required": [ "id", "name", "organizationId", "jurisdiction" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Enable Trustvice Receipts on a workspace.", "value": { "id": "ws_DEMODEFAULT0000000000", "name": "Default", "organizationId": "org_demo", "jurisdiction": "WEUR" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view", "workspace.rename" ] }, { "OAuth2": [ "settings.view", "workspace.rename" ] }, { "WorkspaceApiKey": [ "settings.view", "workspace.rename" ] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "billing", "x-trustvice-audit-kind": "workspace.renamed", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/workspace.entpoind.disable": { "post": { "operationId": "workspace_entpoind_disable", "summary": "Disable Trustvice Receipts on a workspace.", "x-trustvice-description-key": "actions.workspace.entpoind.disable.description", "tags": [ "workspace" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Turn off Trustvice Receipts on this workspace.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "organizationId": { "type": "string" }, "jurisdiction": { "type": "string", "enum": [ "WEUR", "ENAM" ] } }, "required": [ "id", "name", "organizationId", "jurisdiction" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Turn off Trustvice Receipts on this workspace.", "value": { "id": "ws_DEMODEFAULT0000000000", "name": "Default", "organizationId": "org_demo", "jurisdiction": "WEUR" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view", "workspace.rename" ] }, { "OAuth2": [ "settings.view", "workspace.rename" ] }, { "WorkspaceApiKey": [ "settings.view", "workspace.rename" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "workspace.renamed", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/workspace.regions.list": { "post": { "operationId": "workspace_regions_list", "summary": "List the available regions a workspace can be created in.", "x-trustvice-description-key": "actions.workspace.regions.list.description", "tags": [ "workspace" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "List every supported region for region picker UIs.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "regions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(cloudflare-d1|aws-aurora):[a-z0-9-]+$" }, "label": { "type": "string" }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" }, "euJurisdictionBound": { "type": "boolean" } }, "required": [ "id", "label", "countryCode", "euJurisdictionBound" ], "additionalProperties": {} } } }, "required": [ "regions" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List every supported region for region picker UIs.", "value": { "regions": [ { "id": "cloudflare-d1:weur-1", "label": "Europe Central", "countryCode": "EU", "euJurisdictionBound": true } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.subscription.get": { "post": { "operationId": "billing_subscription_get", "summary": "Get the org's current Stripe subscription.", "x-trustvice-description-key": "actions.billing.subscription.get.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read subscription.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subscriptionId": { "type": "string", "pattern": "^sub_[A-Za-z0-9]+$" }, "organizationId": { "type": "string", "pattern": "^org_[0-9A-Z]{20,}$" }, "plan": { "type": "string" }, "status": { "type": "string", "enum": [ "trialing", "active", "past_due", "canceled", "unpaid", "suspended" ] }, "currentPeriodStart": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "currentPeriodEnd": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "cancelAtPeriodEnd": { "type": "boolean" } }, "required": [ "subscriptionId", "organizationId", "plan", "status", "currentPeriodStart", "currentPeriodEnd", "cancelAtPeriodEnd" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read subscription.", "value": { "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 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.view" ] }, { "OAuth2": [ "billing.view" ] }, { "WorkspaceApiKey": [ "billing.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.subscription.upgrade": { "post": { "operationId": "billing_subscription_upgrade", "summary": "Upgrade to a higher tier. Prorates charges; takes effect immediately.", "x-trustvice-description-key": "actions.billing.subscription.upgrade.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "targetPlan": { "type": "string" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "targetPlan" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Upgrade to Team.", "value": { "targetPlan": "team" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subscriptionId": { "type": "string", "pattern": "^sub_[A-Za-z0-9]+$" }, "organizationId": { "type": "string", "pattern": "^org_[0-9A-Z]{20,}$" }, "plan": { "type": "string" }, "status": { "type": "string", "enum": [ "trialing", "active", "past_due", "canceled", "unpaid", "suspended" ] }, "currentPeriodStart": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "currentPeriodEnd": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "cancelAtPeriodEnd": { "type": "boolean" } }, "required": [ "subscriptionId", "organizationId", "plan", "status", "currentPeriodStart", "currentPeriodEnd", "cancelAtPeriodEnd" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Upgrade to Team.", "value": { "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 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.change_plan" ] }, { "OAuth2": [ "billing.change_plan" ] }, { "WorkspaceApiKey": [ "billing.change_plan" ] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "billing", "x-trustvice-audit-kind": "plan.changed", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.subscription.downgrade": { "post": { "operationId": "billing_subscription_downgrade", "summary": "Downgrade to a lower tier. Effective at next billing period.", "x-trustvice-description-key": "actions.billing.subscription.downgrade.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "targetPlan": { "type": "string" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "targetPlan", "reason" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Downgrade scheduled for period end.", "value": { "targetPlan": "starter", "reason": "Reducing usage; no longer need Pro" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subscriptionId": { "type": "string", "pattern": "^sub_[A-Za-z0-9]+$" }, "organizationId": { "type": "string", "pattern": "^org_[0-9A-Z]{20,}$" }, "plan": { "type": "string" }, "status": { "type": "string", "enum": [ "trialing", "active", "past_due", "canceled", "unpaid", "suspended" ] }, "currentPeriodStart": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "currentPeriodEnd": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "cancelAtPeriodEnd": { "type": "boolean" } }, "required": [ "subscriptionId", "organizationId", "plan", "status", "currentPeriodStart", "currentPeriodEnd", "cancelAtPeriodEnd" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Downgrade scheduled for period end.", "value": { "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 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.change_plan" ] }, { "OAuth2": [ "billing.change_plan" ] }, { "WorkspaceApiKey": [ "billing.change_plan" ] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "billing", "x-trustvice-audit-kind": "plan.changed", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.subscription.cancel": { "post": { "operationId": "billing_subscription_cancel", "summary": "Cancel subscription at current period end. Workspace remains accessible until then.", "x-trustvice-description-key": "actions.billing.subscription.cancel.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reason": { "type": "string", "minLength": 10, "maxLength": 500 }, "cancelImmediately": { "default": false, "type": "boolean" } }, "required": [ "reason" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Cancel at period end.", "value": { "reason": "Migrating to alternative provider; export complete" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subscriptionId": { "type": "string", "pattern": "^sub_[A-Za-z0-9]+$" }, "organizationId": { "type": "string", "pattern": "^org_[0-9A-Z]{20,}$" }, "plan": { "type": "string" }, "status": { "type": "string", "enum": [ "trialing", "active", "past_due", "canceled", "unpaid", "suspended" ] }, "currentPeriodStart": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "currentPeriodEnd": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "cancelAtPeriodEnd": { "type": "boolean" } }, "required": [ "subscriptionId", "organizationId", "plan", "status", "currentPeriodStart", "currentPeriodEnd", "cancelAtPeriodEnd" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Cancel at period end.", "value": { "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 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.change_plan" ] }, { "OAuth2": [ "billing.change_plan" ] }, { "WorkspaceApiKey": [ "billing.change_plan" ] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "billing", "x-trustvice-audit-kind": "plan.changed", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.subscription.reactivate": { "post": { "operationId": "billing_subscription_reactivate", "summary": "Reactivate a subscription that's been scheduled to cancel.", "x-trustvice-description-key": "actions.billing.subscription.reactivate.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Reactivate.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subscriptionId": { "type": "string", "pattern": "^sub_[A-Za-z0-9]+$" }, "organizationId": { "type": "string", "pattern": "^org_[0-9A-Z]{20,}$" }, "plan": { "type": "string" }, "status": { "type": "string", "enum": [ "trialing", "active", "past_due", "canceled", "unpaid", "suspended" ] }, "currentPeriodStart": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "currentPeriodEnd": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "cancelAtPeriodEnd": { "type": "boolean" } }, "required": [ "subscriptionId", "organizationId", "plan", "status", "currentPeriodStart", "currentPeriodEnd", "cancelAtPeriodEnd" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Reactivate.", "value": { "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 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.change_plan" ] }, { "OAuth2": [ "billing.change_plan" ] }, { "WorkspaceApiKey": [ "billing.change_plan" ] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "billing", "x-trustvice-audit-kind": "plan.changed", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.invoices.list": { "post": { "operationId": "billing_invoices_list", "summary": "List invoices.", "x-trustvice-description-key": "actions.billing.invoices.list.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "status": { "type": "string", "enum": [ "draft", "open", "paid", "void", "uncollectible" ] } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "List invoices.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "invoices": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^in_[A-Za-z0-9]+$" }, "organizationId": { "type": "string", "pattern": "^org_[0-9A-Z]{20,}$" }, "amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "status": { "type": "string", "enum": [ "draft", "open", "paid", "void", "uncollectible" ] }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "dueAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "hostedInvoiceUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "organizationId", "amount", "currency", "status", "issuedAt", "dueAt", "paidAt" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "invoices", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List invoices.", "value": { "invoices": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.view" ] }, { "OAuth2": [ "billing.view" ] }, { "WorkspaceApiKey": [ "billing.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.invoices.get": { "post": { "operationId": "billing_invoices_get", "summary": "Get a single invoice.", "x-trustvice-description-key": "actions.billing.invoices.get.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "invoiceId": { "type": "string", "pattern": "^in_[A-Za-z0-9]+$" } }, "required": [ "invoiceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read invoice.", "value": { "invoiceId": "in_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^in_[A-Za-z0-9]+$" }, "organizationId": { "type": "string", "pattern": "^org_[0-9A-Z]{20,}$" }, "amount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "status": { "type": "string", "enum": [ "draft", "open", "paid", "void", "uncollectible" ] }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "dueAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "hostedInvoiceUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "organizationId", "amount", "currency", "status", "issuedAt", "dueAt", "paidAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read invoice.", "value": { "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" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.view" ] }, { "OAuth2": [ "billing.view" ] }, { "WorkspaceApiKey": [ "billing.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.invoices.download": { "post": { "operationId": "billing_invoices_download", "summary": "Get a signed download URL for the invoice PDF.", "x-trustvice-description-key": "actions.billing.invoices.download.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "invoiceId": { "type": "string", "pattern": "^in_[A-Za-z0-9]+$" } }, "required": [ "invoiceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Download invoice PDF.", "value": { "invoiceId": "in_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "url", "expiresAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Download invoice PDF.", "value": { "url": "https://files.stripe.com/invoices/abc.pdf", "expiresAt": "2026-05-22T13:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.view" ] }, { "OAuth2": [ "billing.view" ] }, { "WorkspaceApiKey": [ "billing.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.payment-method.get": { "post": { "operationId": "billing_payment-method_get", "summary": "Get the current default payment method (masked).", "x-trustvice-description-key": "actions.billing.payment-method.get.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read masked payment method.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "paymentMethodId": { "type": "string" }, "brand": { "type": "string" }, "last4": { "type": "string" }, "expMonth": { "type": "integer", "minimum": 1, "maximum": 12 }, "expYear": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "paymentMethodId", "brand", "last4", "expMonth", "expYear" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read masked payment method.", "value": { "paymentMethodId": "pm_abc", "brand": "Visa", "last4": "4242", "expMonth": 12, "expYear": 2027 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.view" ] }, { "OAuth2": [ "billing.view" ] }, { "WorkspaceApiKey": [ "billing.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.payment-method.update-url": { "post": { "operationId": "billing_payment-method_update-url", "summary": "Get a signed URL to Stripe's hosted payment-method update page. Update happens in Stripe's UI.", "x-trustvice-description-key": "actions.billing.payment-method.update-url.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "returnUrl": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Get Stripe Portal URL.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "url", "expiresAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Get Stripe Portal URL.", "value": { "url": "https://billing.stripe.com/p/session/abc", "expiresAt": "2026-05-22T13:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.change_plan" ] }, { "OAuth2": [ "billing.change_plan" ] }, { "WorkspaceApiKey": [ "billing.change_plan" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.packs.list": { "post": { "operationId": "billing_packs_list", "summary": "List available top-up packs (runs, Number One queries, Trustvice calls).", "x-trustvice-description-key": "actions.billing.packs.list.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "kind": { "type": "string", "enum": [ "runs", "number-one", "entpoind-calls" ] } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Discover packs.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "packs": { "type": "array", "items": { "type": "object", "properties": { "packId": { "type": "string" }, "kind": { "type": "string", "enum": [ "runs", "number-one", "entpoind-calls" ] }, "unitCount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "priceUsdMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "packId", "kind", "unitCount", "priceUsdMinor" ], "additionalProperties": {} } } }, "required": [ "packs" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Discover packs.", "value": { "packs": [ { "packId": "runs_1k", "kind": "runs", "unitCount": 1000, "priceUsdMinor": 2900 } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.packs.purchase": { "post": { "operationId": "billing_packs_purchase", "summary": "Purchase a top-up pack.", "x-trustvice-description-key": "actions.billing.packs.purchase.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "packId": { "type": "string" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "packId", "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Buy a 1k-run pack.", "value": { "packId": "runs_1k", "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "topUpId": { "type": "string" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "packKind": { "type": "string" }, "unitCount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "priceUsdMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "purchasedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "unitsRemaining": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "forfeitedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "topUpId", "workspaceId", "packKind", "unitCount", "priceUsdMinor", "purchasedAt", "unitsRemaining", "forfeitedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Buy a 1k-run pack.", "value": { "topUpId": "tu_abc", "workspaceId": "ws_DEMODEFAULT0000000000", "packKind": "runs", "unitCount": 1000, "priceUsdMinor": 2900, "purchasedAt": "2026-05-22T12:00:00.000Z", "unitsRemaining": 1000, "forfeitedAt": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.buy_pack" ] }, { "OAuth2": [ "billing.buy_pack" ] }, { "WorkspaceApiKey": [ "billing.buy_pack" ] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "billing", "x-trustvice-audit-kind": "pack.purchased", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.auto-topup.get": { "post": { "operationId": "billing_auto-topup_get", "summary": "Get auto-topup configuration.", "x-trustvice-description-key": "actions.billing.auto-topup.get.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read auto-topup config.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "enabled": { "type": "boolean" }, "packId": { "type": [ "string", "null" ] }, "triggerAtPercent": { "anyOf": [ { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 80 }, { "type": "number", "const": 95 } ] }, { "type": "null" } ] }, "monthlyCapUsdMinor": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "enabled", "packId", "triggerAtPercent", "monthlyCapUsdMinor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read auto-topup config.", "value": { "enabled": false, "packId": null, "triggerAtPercent": null, "monthlyCapUsdMinor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.view" ] }, { "OAuth2": [ "billing.view" ] }, { "WorkspaceApiKey": [ "billing.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.auto-topup.configure": { "post": { "operationId": "billing_auto-topup_configure", "summary": "Configure auto-topup. Fires when balance drops below threshold; capped at monthly USD limit.", "x-trustvice-description-key": "actions.billing.auto-topup.configure.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "enabled": { "type": "boolean" }, "packId": { "type": "string" }, "triggerAtPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 80 }, { "type": "number", "const": 95 } ] }, "monthlyCapUsdMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "workspaceId", "enabled" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Enable auto-topup.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "enabled": true, "packId": "runs_1k", "triggerAtPercent": 80, "monthlyCapUsdMinor": 10000 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "enabled": { "type": "boolean" }, "packId": { "type": [ "string", "null" ] }, "triggerAtPercent": { "anyOf": [ { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 80 }, { "type": "number", "const": 95 } ] }, { "type": "null" } ] }, "monthlyCapUsdMinor": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "enabled", "packId", "triggerAtPercent", "monthlyCapUsdMinor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Enable auto-topup.", "value": { "enabled": true, "packId": "runs_1k", "triggerAtPercent": 80, "monthlyCapUsdMinor": 10000 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.configure_autotopup" ] }, { "OAuth2": [ "billing.configure_autotopup" ] }, { "WorkspaceApiKey": [ "billing.configure_autotopup" ] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "billing", "x-trustvice-audit-kind": "auto_topup.configured", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.cost-centers.list": { "post": { "operationId": "billing_cost-centers_list", "summary": "List org cost centers (for tagging charges + per-cost-center invoicing).", "x-trustvice-description-key": "actions.billing.cost-centers.list.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "List cost centers.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "costCenters": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cc_[0-9A-Z]{20,}$" }, "organizationId": { "type": "string", "pattern": "^org_[0-9A-Z]{20,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string" }, "taggableProducts": { "type": "array", "items": { "type": "string", "enum": [ "trustvice", "entpoind", "both" ] } }, "monthlyCapUsdMinor": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "notificationThresholdPercents": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 100 } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "id", "organizationId", "name", "taggableProducts", "monthlyCapUsdMinor", "notificationThresholdPercents", "createdAt" ], "additionalProperties": {} } } }, "required": [ "costCenters" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List cost centers.", "value": { "costCenters": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.view" ] }, { "OAuth2": [ "billing.view" ] }, { "WorkspaceApiKey": [ "billing.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.cost-centers.create": { "post": { "operationId": "billing_cost-centers_create", "summary": "Create a cost center.", "x-trustvice-description-key": "actions.billing.cost-centers.create.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "maxLength": 500 }, "taggableProducts": { "default": [ "both" ], "type": "array", "items": { "type": "string", "enum": [ "trustvice", "entpoind", "both" ] } }, "monthlyCapUsdMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "notificationThresholdPercents": { "default": [ 50, 80, 100 ], "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 100 } } }, "required": [ "name" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Create cost center.", "value": { "name": "Engineering", "description": "All engineering teams" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^cc_[0-9A-Z]{20,}$" }, "organizationId": { "type": "string", "pattern": "^org_[0-9A-Z]{20,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string" }, "taggableProducts": { "type": "array", "items": { "type": "string", "enum": [ "trustvice", "entpoind", "both" ] } }, "monthlyCapUsdMinor": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "notificationThresholdPercents": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 100 } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "id", "organizationId", "name", "taggableProducts", "monthlyCapUsdMinor", "notificationThresholdPercents", "createdAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Create cost center.", "value": { "id": "cc_DEMO00000000000000000000", "organizationId": "org_DEMO00000000000000000000", "name": "Engineering", "taggableProducts": [ "both" ], "monthlyCapUsdMinor": null, "notificationThresholdPercents": [ 50, 80, 100 ], "createdAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.change_plan" ] }, { "OAuth2": [ "billing.change_plan" ] }, { "WorkspaceApiKey": [ "billing.change_plan" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.cost-centers.update": { "post": { "operationId": "billing_cost-centers_update", "summary": "Update a cost center.", "x-trustvice-description-key": "actions.billing.cost-centers.update.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "costCenterId": { "type": "string", "pattern": "^cc_[0-9A-Z]{20,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "maxLength": 500 }, "monthlyCapUsdMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "notificationThresholdPercents": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 100 } } }, "required": [ "costCenterId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Set monthly cap.", "value": { "costCenterId": "cc_DEMO00000000000000000000", "monthlyCapUsdMinor": 50000 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^cc_[0-9A-Z]{20,}$" }, "organizationId": { "type": "string", "pattern": "^org_[0-9A-Z]{20,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string" }, "taggableProducts": { "type": "array", "items": { "type": "string", "enum": [ "trustvice", "entpoind", "both" ] } }, "monthlyCapUsdMinor": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "notificationThresholdPercents": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 100 } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "id", "organizationId", "name", "taggableProducts", "monthlyCapUsdMinor", "notificationThresholdPercents", "createdAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Set monthly cap.", "value": { "id": "cc_DEMO00000000000000000000", "organizationId": "org_DEMO00000000000000000000", "name": "Engineering", "taggableProducts": [ "both" ], "monthlyCapUsdMinor": 50000, "notificationThresholdPercents": [ 50, 80, 100 ], "createdAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.change_plan" ] }, { "OAuth2": [ "billing.change_plan" ] }, { "WorkspaceApiKey": [ "billing.change_plan" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.cost-centers.delete": { "post": { "operationId": "billing_cost-centers_delete", "summary": "Delete a cost center. Tagged charges keep historical tag.", "x-trustvice-description-key": "actions.billing.cost-centers.delete.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "costCenterId": { "type": "string", "pattern": "^cc_[0-9A-Z]{20,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "costCenterId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete.", "value": { "costCenterId": "cc_DEMO00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete.", "value": { "deleted": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.change_plan" ] }, { "OAuth2": [ "billing.change_plan" ] }, { "WorkspaceApiKey": [ "billing.change_plan" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.cost-centers.assign-charge": { "post": { "operationId": "billing_cost-centers_assign-charge", "summary": "Tag a charge / invoice line with a cost center.", "x-trustvice-description-key": "actions.billing.cost-centers.assign-charge.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "chargeId": { "type": "string" }, "costCenterId": { "type": "string", "pattern": "^cc_[0-9A-Z]{20,}$" } }, "required": [ "chargeId", "costCenterId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Tag a charge.", "value": { "chargeId": "ch_abc", "costCenterId": "cc_DEMO00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tagged": { "type": "boolean" } }, "required": [ "tagged" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Tag a charge.", "value": { "tagged": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.change_plan" ] }, { "OAuth2": [ "billing.change_plan" ] }, { "WorkspaceApiKey": [ "billing.change_plan" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.entpoind.tier.set": { "post": { "operationId": "billing_entpoind_tier_set", "summary": "Set the Trustvice Receipts subscription tier for the org.", "x-trustvice-description-key": "actions.billing.entpoind.tier.set.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tier": { "type": "string" } }, "required": [ "tier" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Set Trustvice Receipts tier.", "value": { "tier": "scale" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subscriptionId": { "type": "string", "pattern": "^sub_[A-Za-z0-9]+$" }, "organizationId": { "type": "string", "pattern": "^org_[0-9A-Z]{20,}$" }, "plan": { "type": "string" }, "status": { "type": "string", "enum": [ "trialing", "active", "past_due", "canceled", "unpaid", "suspended" ] }, "currentPeriodStart": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "currentPeriodEnd": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "cancelAtPeriodEnd": { "type": "boolean" } }, "required": [ "subscriptionId", "organizationId", "plan", "status", "currentPeriodStart", "currentPeriodEnd", "cancelAtPeriodEnd" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Set Trustvice Receipts tier.", "value": { "subscriptionId": "sub_entp_abc", "organizationId": "org_DEMO00000000000000000000", "plan": "scale", "status": "active", "currentPeriodStart": "2026-05-22T12:00:00.000Z", "currentPeriodEnd": "2026-06-22T12:00:00.000Z", "cancelAtPeriodEnd": false } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.change_plan" ] }, { "OAuth2": [ "billing.change_plan" ] }, { "WorkspaceApiKey": [ "billing.change_plan" ] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "billing", "x-trustvice-audit-kind": "plan.changed", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.entpoind.tier.get": { "post": { "operationId": "billing_entpoind_tier_get", "summary": "Get the current Trustvice Receipts tier.", "x-trustvice-description-key": "actions.billing.entpoind.tier.get.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read Trustvice Receipts tier.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tier": { "type": "string" }, "monthlyCalls": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "retentionDays": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "tier", "monthlyCalls", "retentionDays" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read Trustvice Receipts tier.", "value": { "tier": "team", "monthlyCalls": 100000, "retentionDays": 365 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.view" ] }, { "OAuth2": [ "billing.view" ] }, { "WorkspaceApiKey": [ "billing.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.entpoind.top-up.purchase": { "post": { "operationId": "billing_entpoind_top-up_purchase", "summary": "Purchase a Trustvice Receipts top-up pack (extra call quota for the current month).", "x-trustvice-description-key": "actions.billing.entpoind.top-up.purchase.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "packId": { "type": "string" } }, "required": [ "workspaceId", "packId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Buy 100k Trustvice calls.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "packId": "entpoind_100k" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "topUpId": { "type": "string" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "packKind": { "type": "string" }, "unitCount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "priceUsdMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "purchasedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "unitsRemaining": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "forfeitedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "topUpId", "workspaceId", "packKind", "unitCount", "priceUsdMinor", "purchasedAt", "unitsRemaining", "forfeitedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Buy 100k Trustvice calls.", "value": { "topUpId": "tu_entp_abc", "workspaceId": "ws_DEMODEFAULT0000000000", "packKind": "entpoind-calls", "unitCount": 100000, "priceUsdMinor": 1900, "purchasedAt": "2026-05-22T12:00:00.000Z", "unitsRemaining": 100000, "forfeitedAt": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.buy_pack" ] }, { "OAuth2": [ "billing.buy_pack" ] }, { "WorkspaceApiKey": [ "billing.buy_pack" ] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "billing", "x-trustvice-audit-kind": "pack.purchased", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.entpoind.auto-overage.set": { "post": { "operationId": "billing_entpoind_auto-overage_set", "summary": "Configure auto-overage for an Entpoind-enabled workspace.", "x-trustvice-description-key": "actions.billing.entpoind.auto-overage.set.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "enabled": { "type": "boolean" }, "capMultiplier": { "type": "integer", "minimum": 1, "maximum": 10 } }, "required": [ "workspaceId", "enabled" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Enable auto-overage at 3× cap.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "enabled": true, "capMultiplier": 3 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "enabled": { "type": "boolean" }, "capMultiplier": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "enabled", "capMultiplier" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Enable auto-overage at 3× cap.", "value": { "enabled": true, "capMultiplier": 3 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.configure_autotopup" ] }, { "OAuth2": [ "billing.configure_autotopup" ] }, { "WorkspaceApiKey": [ "billing.configure_autotopup" ] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "billing", "x-trustvice-audit-kind": "auto_topup.configured", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.entpoind.billing-mode.set": { "post": { "operationId": "billing_entpoind_billing-mode_set", "summary": "Set the Trustvice Receipts billing mode (combined vs separate Stripe subscription).", "x-trustvice-description-key": "actions.billing.entpoind.billing-mode.set.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "combined", "separate" ] } }, "required": [ "mode" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Separate Stripe subscriptions for Trustvice + Trustvice Receipts.", "value": { "mode": "separate" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "combined", "separate" ] } }, "required": [ "mode" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Separate Stripe subscriptions for Trustvice + Trustvice Receipts.", "value": { "mode": "separate" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.change_plan" ] }, { "OAuth2": [ "billing.change_plan" ] }, { "WorkspaceApiKey": [ "billing.change_plan" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.entpoind.usage.current": { "post": { "operationId": "billing_entpoind_usage_current", "summary": "Get current Trustvice Receipts usage for the org (calls used + remaining quota + auto-overage status).", "x-trustvice-description-key": "actions.billing.entpoind.usage.current.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read current Trustvice Receipts usage.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "callsUsed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "monthlyAllowance": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "remaining": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "autoOverageActive": { "type": "boolean" }, "periodEnd": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "callsUsed", "monthlyAllowance", "remaining", "autoOverageActive", "periodEnd" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read current Trustvice Receipts usage.", "value": { "callsUsed": 45000, "monthlyAllowance": 100000, "remaining": 55000, "autoOverageActive": false, "periodEnd": "2026-06-01T00:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.view" ] }, { "OAuth2": [ "billing.view" ] }, { "WorkspaceApiKey": [ "billing.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.notarian.subscribe": { "post": { "operationId": "billing_notarian_subscribe", "summary": "Subscribe to the Notarian add-on (per-tier subscription pricing).", "x-trustvice-description-key": "actions.billing.notarian.subscribe.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Subscribe to Notarian.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subscribed": { "type": "boolean" } }, "required": [ "subscribed" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Subscribe to Notarian.", "value": { "subscribed": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.subscribe_addons" ] }, { "OAuth2": [ "billing.subscribe_addons" ] }, { "WorkspaceApiKey": [ "billing.subscribe_addons" ] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "billing", "x-trustvice-audit-kind": "notarian.subscribed", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.notarian.unsubscribe": { "post": { "operationId": "billing_notarian_unsubscribe", "summary": "Unsubscribe from Notarian at next billing period.", "x-trustvice-description-key": "actions.billing.notarian.unsubscribe.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Unsubscribe Notarian.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "unsubscribed": { "type": "boolean" }, "effectiveAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "unsubscribed", "effectiveAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Unsubscribe Notarian.", "value": { "unsubscribed": true, "effectiveAt": "2026-06-22T00:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.subscribe_addons" ] }, { "OAuth2": [ "billing.subscribe_addons" ] }, { "WorkspaceApiKey": [ "billing.subscribe_addons" ] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "billing", "x-trustvice-audit-kind": "notarian.canceled", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.infinite-memory.subscribe": { "post": { "operationId": "billing_infinite-memory_subscribe", "summary": "Subscribe to the Infinite Memory add-on for Number One ($19/mo on paid tiers).", "x-trustvice-description-key": "actions.billing.infinite-memory.subscribe.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Subscribe Infinite Memory.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subscribed": { "type": "boolean" } }, "required": [ "subscribed" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Subscribe Infinite Memory.", "value": { "subscribed": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.subscribe_addons" ] }, { "OAuth2": [ "billing.subscribe_addons" ] }, { "WorkspaceApiKey": [ "billing.subscribe_addons" ] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "billing", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.infinite-memory.unsubscribe": { "post": { "operationId": "billing_infinite-memory_unsubscribe", "summary": "Unsubscribe Infinite Memory at next billing period.", "x-trustvice-description-key": "actions.billing.infinite-memory.unsubscribe.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Unsubscribe Infinite Memory.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "unsubscribed": { "type": "boolean" }, "effectiveAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "unsubscribed", "effectiveAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Unsubscribe Infinite Memory.", "value": { "unsubscribed": true, "effectiveAt": "2026-06-22T00:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.subscribe_addons" ] }, { "OAuth2": [ "billing.subscribe_addons" ] }, { "WorkspaceApiKey": [ "billing.subscribe_addons" ] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "billing", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/billing.retention-extension.subscribe": { "post": { "operationId": "billing_retention-extension_subscribe", "summary": "Subscribe to the universal paid retention extension. Convenience alias of retention.extension.subscribe.", "x-trustvice-description-key": "actions.billing.retention-extension.subscribe.description", "tags": [ "billing" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "extendedToDays": { "type": "integer", "minimum": 7, "maximum": 1825 } }, "required": [ "workspaceId", "extendedToDays" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Subscribe to 3-year retention extension.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "extendedToDays": 1095 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subscribed": { "type": "boolean" }, "perGbCostUsdMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "subscribed", "perGbCostUsdMinor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Subscribe to 3-year retention extension.", "value": { "subscribed": true, "perGbCostUsdMinor": 1000 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.subscribe_addons" ] }, { "OAuth2": [ "billing.subscribe_addons" ] }, { "WorkspaceApiKey": [ "billing.subscribe_addons" ] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "billing", "x-trustvice-audit-kind": "retention.updated", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/keys.list": { "post": { "operationId": "keys_list", "summary": "List workspace API keys (active + revoked filter).", "x-trustvice-description-key": "actions.keys.list.description", "tags": [ "keys" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "includeRevoked": { "default": false, "type": "boolean" }, "product": { "type": "string", "enum": [ "trustvice", "entpoind" ] } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List active keys.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(tv|entp)_[a-z0-9_]{4,}_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "product": { "type": "string", "enum": [ "trustvice", "entpoind" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "id", "workspaceId", "product", "label", "prefix", "scopes", "createdAt", "lastUsedAt", "expiresAt", "revokedAt" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "keys", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List active keys.", "value": { "keys": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "keys.view" ] }, { "OAuth2": [ "keys.view" ] }, { "WorkspaceApiKey": [ "keys.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/keys.get": { "post": { "operationId": "keys_get", "summary": "Get a single workspace API key by id.", "x-trustvice-description-key": "actions.keys.get.description", "tags": [ "keys" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "keyId": { "type": "string", "pattern": "^(tv|entp)_[a-z0-9_]{4,}_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId", "keyId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Fetch one key.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "keyId": "tv_workspace_ABC20CHARSFOREXAMPLEID" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^(tv|entp)_[a-z0-9_]{4,}_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "product": { "type": "string", "enum": [ "trustvice", "entpoind" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "id", "workspaceId", "product", "label", "prefix", "scopes", "createdAt", "lastUsedAt", "expiresAt", "revokedAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Fetch one key.", "value": { "id": "tv_workspace_ABC20CHARSFOREXAMPLEID", "workspaceId": "ws_DEMODEFAULT0000000000", "product": "trustvice", "label": "Prod key", "prefix": "tv_abc", "scopes": [ "ingest:write" ], "createdAt": "2026-05-22T12:00:00.000Z", "lastUsedAt": null, "expiresAt": null, "revokedAt": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "keys.view" ] }, { "OAuth2": [ "keys.view" ] }, { "WorkspaceApiKey": [ "keys.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/keys.issue": { "post": { "operationId": "keys_issue", "summary": "Issue a new workspace API key. Cleartext returned ONCE.", "x-trustvice-description-key": "actions.keys.issue.description", "tags": [ "keys" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "product": { "default": "trustvice", "type": "string", "const": "trustvice" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "expiry": { "default": "never", "type": "string", "enum": [ "never", "30d", "90d", "1y" ] } }, "required": [ "workspaceId", "label", "scopes" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Mint a new key; cleartext shown once.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "product": "trustvice", "label": "Prod ingest key", "scopes": [ "ingest:write" ], "expiry": "1y" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(tv|entp)_[a-z0-9_]{4,}_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "product": { "type": "string", "enum": [ "trustvice", "entpoind" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "id", "workspaceId", "product", "label", "prefix", "scopes", "createdAt", "lastUsedAt", "expiresAt", "revokedAt" ], "additionalProperties": {} }, "cleartext": { "type": "string" } }, "required": [ "key", "cleartext" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Mint a new key; cleartext shown once.", "value": { "key": { "id": "tv_workspace_ABC20CHARSFOREXAMPLEID", "workspaceId": "ws_DEMODEFAULT0000000000", "product": "trustvice", "label": "Prod ingest key", "prefix": "tv_abc", "scopes": [ "ingest:write" ], "createdAt": "2026-05-22T12:00:00.000Z", "lastUsedAt": null, "expiresAt": "2027-05-22T12:00:00.000Z", "revokedAt": null }, "cleartext": "tv_abc_REDACTED_EXAMPLE_ONLY" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "keys.create" ] }, { "OAuth2": [ "keys.create" ] }, { "WorkspaceApiKey": [ "keys.create" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "key.issued", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/keys.revoke": { "post": { "operationId": "keys_revoke", "summary": "Revoke a workspace API key. Propagates in ≤30s.", "x-trustvice-description-key": "actions.keys.revoke.description", "tags": [ "keys" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "keyId": { "type": "string", "pattern": "^(tv|entp)_[a-z0-9_]{4,}_[0-9A-Z]{20,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "keyId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Revoke a key.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "keyId": "tv_workspace_ABC20CHARSFOREXAMPLEID" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "revoked": { "type": "boolean" }, "propagatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "revoked", "propagatedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Revoke a key.", "value": { "revoked": true, "propagatedAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "keys.revoke" ] }, { "OAuth2": [ "keys.revoke" ] }, { "WorkspaceApiKey": [ "keys.revoke" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "key.revoked", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/keys.rotate": { "post": { "operationId": "keys_rotate", "summary": "Rotate a key: revoke the current value + issue a replacement with the same label + scopes. Cleartext returned ONCE.", "x-trustvice-description-key": "actions.keys.rotate.description", "tags": [ "keys" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "keyId": { "type": "string", "pattern": "^(tv|entp)_[a-z0-9_]{4,}_[0-9A-Z]{20,}$" }, "gracePeriodMinutes": { "default": 5, "type": "integer", "minimum": 0, "maximum": 60 } }, "required": [ "workspaceId", "keyId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Rotate a key with 5-min grace.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "keyId": "tv_workspace_ABC20CHARSFOREXAMPLEID" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "revokedKeyId": { "type": "string", "pattern": "^(tv|entp)_[a-z0-9_]{4,}_[0-9A-Z]{20,}$" }, "newKey": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(tv|entp)_[a-z0-9_]{4,}_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "product": { "type": "string", "enum": [ "trustvice", "entpoind" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "id", "workspaceId", "product", "label", "prefix", "scopes", "createdAt", "lastUsedAt", "expiresAt", "revokedAt" ], "additionalProperties": {} }, "cleartext": { "type": "string" }, "graceUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "revokedKeyId", "newKey", "cleartext", "graceUntil" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Rotate a key with 5-min grace.", "value": { "revokedKeyId": "tv_workspace_ABC20CHARSFOREXAMPLEID", "newKey": { "id": "tv_workspace_def20charsforexampleid", "workspaceId": "ws_DEMODEFAULT0000000000", "product": "trustvice", "label": "Prod ingest key", "prefix": "tv_def", "scopes": [ "ingest:write" ], "createdAt": "2026-05-22T12:00:00.000Z", "lastUsedAt": null, "expiresAt": null, "revokedAt": null }, "cleartext": "tv_def_REDACTED_EXAMPLE_ONLY", "graceUntil": "2026-05-22T12:05:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "keys.create", "keys.revoke" ] }, { "OAuth2": [ "keys.create", "keys.revoke" ] }, { "WorkspaceApiKey": [ "keys.create", "keys.revoke" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "key.rotated", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/keys.scopes.list": { "post": { "operationId": "keys_scopes_list", "summary": "List the available scope grants for workspace API keys.", "x-trustvice-description-key": "actions.keys.scopes.list.description", "tags": [ "keys" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "product": { "type": "string", "enum": [ "trustvice", "tools" ] } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Discover scopes.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scopes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "product": { "type": "string", "enum": [ "trustvice", "tools" ] }, "label": { "type": "string" }, "description": { "type": "string" }, "severity": { "type": "string", "enum": [ "read", "write", "delete" ] } }, "required": [ "id", "product", "label", "description", "severity" ], "additionalProperties": false } } }, "required": [ "scopes" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Discover scopes.", "value": { "scopes": [ { "id": "ingest:write", "product": "tools", "label": "Ingest write", "description": "Send runs / events into the workspace", "severity": "write" } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/keys.usage.get": { "post": { "operationId": "keys_usage_get", "summary": "Get usage statistics (calls + last-used + IP CIDRs) for a key over a time window.", "x-trustvice-description-key": "actions.keys.usage.get.description", "tags": [ "keys" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "keyId": { "type": "string", "pattern": "^(tv|entp)_[a-z0-9_]{4,}_[0-9A-Z]{20,}$" }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "workspaceId", "keyId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read key usage.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "keyId": "tv_workspace_ABC20CHARSFOREXAMPLEID" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "totalCalls": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "uniqueIpCidrs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "perEndpointBreakdown": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "path", "count" ], "additionalProperties": false } } }, "required": [ "totalCalls", "uniqueIpCidrs", "lastUsedAt", "perEndpointBreakdown" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read key usage.", "value": { "totalCalls": 12345, "uniqueIpCidrs": 3, "lastUsedAt": "2026-05-22T12:00:00.000Z", "perEndpointBreakdown": [ { "path": "/v1/ingest", "count": 12000 } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "keys.view" ] }, { "OAuth2": [ "keys.view" ] }, { "WorkspaceApiKey": [ "keys.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/keys.last-used.get": { "post": { "operationId": "keys_last-used_get", "summary": "Quick lookup: when was this key last used?", "x-trustvice-description-key": "actions.keys.last-used.get.description", "tags": [ "keys" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "keyId": { "type": "string", "pattern": "^(tv|entp)_[a-z0-9_]{4,}_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId", "keyId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Lightweight last-used check.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "keyId": "tv_workspace_ABC20CHARSFOREXAMPLEID" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "lastUsedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Lightweight last-used check.", "value": { "lastUsedAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "keys.view" ] }, { "OAuth2": [ "keys.view" ] }, { "WorkspaceApiKey": [ "keys.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/keys.entpoind.list": { "post": { "operationId": "keys_entpoind_list", "summary": "Convenience: list only the Entpoind-product workspace keys.", "x-trustvice-description-key": "actions.keys.entpoind.list.description", "tags": [ "keys" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "includeRevoked": { "default": false, "type": "boolean" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List Entpoind-only keys.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(tv|entp)_[a-z0-9_]{4,}_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "product": { "type": "string", "enum": [ "trustvice", "entpoind" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "id", "workspaceId", "product", "label", "prefix", "scopes", "createdAt", "lastUsedAt", "expiresAt", "revokedAt" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "keys", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List Entpoind-only keys.", "value": { "keys": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "keys.view" ] }, { "OAuth2": [ "keys.view" ] }, { "WorkspaceApiKey": [ "keys.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/keys.entpoind.issue": { "post": { "operationId": "keys_entpoind_issue", "summary": "Issue an Entpoind-product workspace key (entp_*). Cleartext shown ONCE.", "x-trustvice-description-key": "actions.keys.entpoind.issue.description", "tags": [ "keys" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "expiry": { "default": "never", "type": "string", "enum": [ "never", "30d", "90d", "1y" ] } }, "required": [ "workspaceId", "label", "scopes" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Mint a Trustvice Receipts key.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "label": "Trustvice Receipts attestation key", "scopes": [ "entpoind:agent-call:write", "entpoind:content-attest:write" ], "expiry": "90d" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(tv|entp)_[a-z0-9_]{4,}_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "product": { "type": "string", "enum": [ "trustvice", "entpoind" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "id", "workspaceId", "product", "label", "prefix", "scopes", "createdAt", "lastUsedAt", "expiresAt", "revokedAt" ], "additionalProperties": {} }, "cleartext": { "type": "string" } }, "required": [ "key", "cleartext" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Mint a Trustvice Receipts key.", "value": { "key": { "id": "entp_workspace_abc20charsforexampleid", "workspaceId": "ws_DEMODEFAULT0000000000", "product": "entpoind", "label": "Trustvice Receipts attestation key", "prefix": "entp_abc", "scopes": [ "entpoind:agent-call:write", "entpoind:content-attest:write" ], "createdAt": "2026-05-22T12:00:00.000Z", "lastUsedAt": null, "expiresAt": "2026-08-20T12:00:00.000Z", "revokedAt": null }, "cleartext": "entp_abc_REDACTED_EXAMPLE_ONLY" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "keys.create" ] }, { "OAuth2": [ "keys.create" ] }, { "WorkspaceApiKey": [ "keys.create" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "key.issued", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/webhooks.list": { "post": { "operationId": "webhooks_list", "summary": "List webhook endpoints for a workspace.", "x-trustvice-description-key": "actions.webhooks.list.description", "tags": [ "webhooks" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "enabledOnly": { "default": false, "type": "boolean" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List webhooks.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "webhooks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^wh_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "url": { "type": "string", "format": "uri" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "events": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "secretPrefix": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "id", "workspaceId", "url", "label", "events", "enabled", "secretPrefix", "createdAt", "updatedAt" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "webhooks", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List webhooks.", "value": { "webhooks": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "webhooks.view" ] }, { "OAuth2": [ "webhooks.view" ] }, { "WorkspaceApiKey": [ "webhooks.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/webhooks.get": { "post": { "operationId": "webhooks_get", "summary": "Get a single webhook endpoint.", "x-trustvice-description-key": "actions.webhooks.get.description", "tags": [ "webhooks" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "webhookId": { "type": "string", "pattern": "^wh_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId", "webhookId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read a webhook.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "webhookId": "wh_DEMO00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^wh_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "url": { "type": "string", "format": "uri" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "events": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "secretPrefix": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "id", "workspaceId", "url", "label", "events", "enabled", "secretPrefix", "createdAt", "updatedAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read a webhook.", "value": { "id": "wh_DEMO00000000000000000000", "workspaceId": "ws_DEMODEFAULT0000000000", "url": "https://example.com/webhook", "label": "Production hook", "events": [ "alert.fired" ], "enabled": true, "secretPrefix": "whsec_ab", "createdAt": "2026-05-22T12:00:00.000Z", "updatedAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "webhooks.view" ] }, { "OAuth2": [ "webhooks.view" ] }, { "WorkspaceApiKey": [ "webhooks.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/webhooks.create": { "post": { "operationId": "webhooks_create", "summary": "Register a new webhook endpoint. Returns the signing secret cleartext ONCE.", "x-trustvice-description-key": "actions.webhooks.create.description", "tags": [ "webhooks" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "url": { "type": "string", "format": "uri" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "events": { "minItems": 1, "type": "array", "items": { "type": "string" } } }, "required": [ "workspaceId", "url", "label", "events" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Create + receive signing secret.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "url": "https://example.com/webhook", "label": "Prod hook", "events": [ "alert.fired", "export.ready" ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "webhook": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^wh_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "url": { "type": "string", "format": "uri" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "events": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "secretPrefix": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "id", "workspaceId", "url", "label", "events", "enabled", "secretPrefix", "createdAt", "updatedAt" ], "additionalProperties": {} }, "signingSecretCleartext": { "type": "string" } }, "required": [ "webhook", "signingSecretCleartext" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Create + receive signing secret.", "value": { "webhook": { "id": "wh_DEMO00000000000000000000", "workspaceId": "ws_DEMODEFAULT0000000000", "url": "https://example.com/webhook", "label": "Prod hook", "events": [ "alert.fired", "export.ready" ], "enabled": true, "secretPrefix": "whsec_ab", "createdAt": "2026-05-22T12:00:00.000Z", "updatedAt": "2026-05-22T12:00:00.000Z" }, "signingSecretCleartext": "whsec_REDACTED_EXAMPLE_ONLY" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "webhooks.create" ] }, { "OAuth2": [ "webhooks.create" ] }, { "WorkspaceApiKey": [ "webhooks.create" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "webhook.created", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/webhooks.update": { "post": { "operationId": "webhooks_update", "summary": "Update a webhook's URL, label, or event subscriptions.", "x-trustvice-description-key": "actions.webhooks.update.description", "tags": [ "webhooks" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "webhookId": { "type": "string", "pattern": "^wh_[0-9A-Z]{20,}$" }, "url": { "type": "string", "format": "uri" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "events": { "minItems": 1, "type": "array", "items": { "type": "string" } } }, "required": [ "workspaceId", "webhookId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Narrow subscription set.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "webhookId": "wh_DEMO00000000000000000000", "events": [ "alert.fired" ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^wh_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "url": { "type": "string", "format": "uri" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "events": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "secretPrefix": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "id", "workspaceId", "url", "label", "events", "enabled", "secretPrefix", "createdAt", "updatedAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Narrow subscription set.", "value": { "id": "wh_DEMO00000000000000000000", "workspaceId": "ws_DEMODEFAULT0000000000", "url": "https://example.com/webhook", "label": "Prod hook", "events": [ "alert.fired" ], "enabled": true, "secretPrefix": "whsec_ab", "createdAt": "2026-05-22T12:00:00.000Z", "updatedAt": "2026-05-22T12:05:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "webhooks.create" ] }, { "OAuth2": [ "webhooks.create" ] }, { "WorkspaceApiKey": [ "webhooks.create" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "webhook.updated", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/webhooks.delete": { "post": { "operationId": "webhooks_delete", "summary": "Delete a webhook endpoint. Pending deliveries are abandoned.", "x-trustvice-description-key": "actions.webhooks.delete.description", "tags": [ "webhooks" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "webhookId": { "type": "string", "pattern": "^wh_[0-9A-Z]{20,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "webhookId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Remove a webhook.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "webhookId": "wh_DEMO00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Remove a webhook.", "value": { "deleted": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "webhooks.delete" ] }, { "OAuth2": [ "webhooks.delete" ] }, { "WorkspaceApiKey": [ "webhooks.delete" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "webhook.deleted", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/webhooks.enable": { "post": { "operationId": "webhooks_enable", "summary": "Enable or disable a webhook without deleting it.", "x-trustvice-description-key": "actions.webhooks.enable.description", "tags": [ "webhooks" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "webhookId": { "type": "string", "pattern": "^wh_[0-9A-Z]{20,}$" }, "enabled": { "type": "boolean" } }, "required": [ "workspaceId", "webhookId", "enabled" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Disable temporarily.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "webhookId": "wh_DEMO00000000000000000000", "enabled": false } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^wh_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "url": { "type": "string", "format": "uri" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "events": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "secretPrefix": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "id", "workspaceId", "url", "label", "events", "enabled", "secretPrefix", "createdAt", "updatedAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Disable temporarily.", "value": { "id": "wh_DEMO00000000000000000000", "workspaceId": "ws_DEMODEFAULT0000000000", "url": "https://example.com/webhook", "label": "Prod hook", "events": [ "alert.fired" ], "enabled": false, "secretPrefix": "whsec_ab", "createdAt": "2026-05-22T12:00:00.000Z", "updatedAt": "2026-05-22T12:10:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "webhooks.create" ] }, { "OAuth2": [ "webhooks.create" ] }, { "WorkspaceApiKey": [ "webhooks.create" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "webhook.updated", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/webhooks.test-fire": { "post": { "operationId": "webhooks_test-fire", "summary": "Fire a synthetic test event to a webhook to verify delivery + signature validation.", "x-trustvice-description-key": "actions.webhooks.test-fire.description", "tags": [ "webhooks" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "webhookId": { "type": "string", "pattern": "^wh_[0-9A-Z]{20,}$" }, "eventType": { "default": "webhook.test", "type": "string" } }, "required": [ "workspaceId", "webhookId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Test webhook delivery.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "webhookId": "wh_DEMO00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deliveryId": { "type": "string" }, "webhookId": { "type": "string", "pattern": "^wh_[0-9A-Z]{20,}$" }, "eventType": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "success", "failed", "retrying" ] }, "statusCode": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "attemptCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "attemptedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "responseTimeMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "errorMessage": { "type": "string" } }, "required": [ "deliveryId", "webhookId", "eventType", "status", "attemptCount", "attemptedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Test webhook delivery.", "value": { "deliveryId": "del_abc", "webhookId": "wh_DEMO00000000000000000000", "eventType": "webhook.test", "status": "success", "statusCode": 200, "attemptCount": 1, "attemptedAt": "2026-05-22T12:00:00.000Z", "responseTimeMs": 87 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "webhooks.create" ] }, { "OAuth2": [ "webhooks.create" ] }, { "WorkspaceApiKey": [ "webhooks.create" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/webhooks.events.list": { "post": { "operationId": "webhooks_events_list", "summary": "List the event types this webhook can subscribe to (from the AsyncAPI 3 spec).", "x-trustvice-description-key": "actions.webhooks.events.list.description", "tags": [ "webhooks" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Discover event types.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "severity": { "type": "string", "enum": [ "info", "warning", "critical" ] } }, "required": [ "id", "description", "severity" ], "additionalProperties": false } } }, "required": [ "events" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Discover event types.", "value": { "events": [ { "id": "alert.fired", "description": "An alert rule fired.", "severity": "warning" } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/webhooks.events.replay": { "post": { "operationId": "webhooks_events_replay", "summary": "Replay missed events from a time window. Useful for recovering after webhook downtime.", "x-trustvice-description-key": "actions.webhooks.events.replay.description", "tags": [ "webhooks" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "webhookId": { "type": "string", "pattern": "^wh_[0-9A-Z]{20,}$" }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "until": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "workspaceId", "webhookId", "since" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Replay events from yesterday.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "webhookId": "wh_DEMO00000000000000000000", "since": "2026-05-21T00:00:00.000Z" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "replayId": { "type": "string" }, "eventsQueued": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "replayId", "eventsQueued" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Replay events from yesterday.", "value": { "replayId": "rep_abc", "eventsQueued": 42 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "webhooks.create" ] }, { "OAuth2": [ "webhooks.create" ] }, { "WorkspaceApiKey": [ "webhooks.create" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/webhooks.signing-secret.rotate": { "post": { "operationId": "webhooks_signing-secret_rotate", "summary": "Rotate the HMAC signing secret. Old secret valid for 24h grace.", "x-trustvice-description-key": "actions.webhooks.signing-secret.rotate.description", "tags": [ "webhooks" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "webhookId": { "type": "string", "pattern": "^wh_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId", "webhookId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Rotate webhook signing secret.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "webhookId": "wh_DEMO00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "newSigningSecretCleartext": { "type": "string" }, "oldSecretValidUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "newSigningSecretCleartext", "oldSecretValidUntil" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Rotate webhook signing secret.", "value": { "newSigningSecretCleartext": "whsec_REDACTED_EXAMPLE_ONLY", "oldSecretValidUntil": "2026-05-23T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "webhooks.create" ] }, { "OAuth2": [ "webhooks.create" ] }, { "WorkspaceApiKey": [ "webhooks.create" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "webhook.updated", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/webhooks.deliveries.list": { "post": { "operationId": "webhooks_deliveries_list", "summary": "List delivery attempts for a webhook (success + failure history).", "x-trustvice-description-key": "actions.webhooks.deliveries.list.description", "tags": [ "webhooks" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "webhookId": { "type": "string", "pattern": "^wh_[0-9A-Z]{20,}$" }, "statusFilter": { "type": "string", "enum": [ "pending", "success", "failed", "retrying" ] } }, "required": [ "workspaceId", "webhookId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List delivery attempts.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "webhookId": "wh_DEMO00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deliveries": { "type": "array", "items": { "type": "object", "properties": { "deliveryId": { "type": "string" }, "webhookId": { "type": "string", "pattern": "^wh_[0-9A-Z]{20,}$" }, "eventType": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "success", "failed", "retrying" ] }, "statusCode": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "attemptCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "attemptedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "responseTimeMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "errorMessage": { "type": "string" } }, "required": [ "deliveryId", "webhookId", "eventType", "status", "attemptCount", "attemptedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "deliveries", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List delivery attempts.", "value": { "deliveries": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "webhooks.view" ] }, { "OAuth2": [ "webhooks.view" ] }, { "WorkspaceApiKey": [ "webhooks.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/webhooks.deliveries.retry": { "post": { "operationId": "webhooks_deliveries_retry", "summary": "Retry a specific failed delivery.", "x-trustvice-description-key": "actions.webhooks.deliveries.retry.description", "tags": [ "webhooks" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "webhookId": { "type": "string", "pattern": "^wh_[0-9A-Z]{20,}$" }, "deliveryId": { "type": "string" } }, "required": [ "workspaceId", "webhookId", "deliveryId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Retry a delivery.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "webhookId": "wh_DEMO00000000000000000000", "deliveryId": "del_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deliveryId": { "type": "string" }, "webhookId": { "type": "string", "pattern": "^wh_[0-9A-Z]{20,}$" }, "eventType": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "success", "failed", "retrying" ] }, "statusCode": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "attemptCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "attemptedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "responseTimeMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "errorMessage": { "type": "string" } }, "required": [ "deliveryId", "webhookId", "eventType", "status", "attemptCount", "attemptedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Retry a delivery.", "value": { "deliveryId": "del_abc", "webhookId": "wh_DEMO00000000000000000000", "eventType": "alert.fired", "status": "success", "statusCode": 200, "attemptCount": 2, "attemptedAt": "2026-05-22T12:00:00.000Z", "responseTimeMs": 42 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "webhooks.create" ] }, { "OAuth2": [ "webhooks.create" ] }, { "WorkspaceApiKey": [ "webhooks.create" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/alerts.list": { "post": { "operationId": "alerts_list", "summary": "List alert rules for a workspace.", "x-trustvice-description-key": "actions.alerts.list.description", "tags": [ "alerts" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "enabledOnly": { "default": false, "type": "boolean" }, "typeFilter": { "type": "string" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List alerts.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "alerts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^alert_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "type": { "type": "string" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "enabled": { "type": "boolean" }, "config": {}, "channels": { "type": "array", "items": {} }, "lastFiredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "firedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "id", "workspaceId", "type", "label", "enabled", "config", "channels", "lastFiredAt", "firedCount", "createdAt", "updatedAt" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "alerts", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List alerts.", "value": { "alerts": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/alerts.get": { "post": { "operationId": "alerts_get", "summary": "Get a single alert rule.", "x-trustvice-description-key": "actions.alerts.get.description", "tags": [ "alerts" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "alertId": { "type": "string", "pattern": "^alert_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId", "alertId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read an alert rule.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "alertId": "alert_DEMO00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^alert_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "type": { "type": "string" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "enabled": { "type": "boolean" }, "config": {}, "channels": { "type": "array", "items": {} }, "lastFiredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "firedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "id", "workspaceId", "type", "label", "enabled", "config", "channels", "lastFiredAt", "firedCount", "createdAt", "updatedAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read an alert rule.", "value": { "id": "alert_DEMO00000000000000000000", "workspaceId": "ws_DEMODEFAULT0000000000", "type": "quota_threshold", "label": "80% quota", "enabled": true, "config": { "type": "quota_threshold", "thresholdPercent": 80, "quotaKind": "runs" }, "channels": [], "lastFiredAt": null, "firedCount": 0, "createdAt": "2026-05-22T12:00:00.000Z", "updatedAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/alerts.create": { "post": { "operationId": "alerts_create", "summary": "Create a new alert rule.", "x-trustvice-description-key": "actions.alerts.create.description", "tags": [ "alerts" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "type": { "type": "string" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "config": {}, "channels": { "type": "array", "items": {} } }, "required": [ "workspaceId", "type", "label", "config", "channels" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Create alert.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "type": "quota_threshold", "label": "80% quota", "config": { "type": "quota_threshold", "thresholdPercent": 80, "quotaKind": "runs" }, "channels": [ { "kind": "email", "addresses": [ "ops@example.com" ] } ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^alert_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "type": { "type": "string" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "enabled": { "type": "boolean" }, "config": {}, "channels": { "type": "array", "items": {} }, "lastFiredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "firedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "id", "workspaceId", "type", "label", "enabled", "config", "channels", "lastFiredAt", "firedCount", "createdAt", "updatedAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Create alert.", "value": { "id": "alert_new0000000000000000000", "workspaceId": "ws_DEMODEFAULT0000000000", "type": "quota_threshold", "label": "80% quota", "enabled": true, "config": { "type": "quota_threshold", "thresholdPercent": 80, "quotaKind": "runs" }, "channels": [ { "kind": "email", "addresses": [ "ops@example.com" ] } ], "lastFiredAt": null, "firedCount": 0, "createdAt": "2026-05-22T12:00:00.000Z", "updatedAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "alert.created", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/alerts.update": { "post": { "operationId": "alerts_update", "summary": "Update an alert's label / config / channels / enabled flag.", "x-trustvice-description-key": "actions.alerts.update.description", "tags": [ "alerts" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "alertId": { "type": "string", "pattern": "^alert_[0-9A-Z]{20,}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "enabled": { "type": "boolean" }, "config": {}, "channels": { "type": "array", "items": {} } }, "required": [ "workspaceId", "alertId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Update alert.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "alertId": "alert_DEMO00000000000000000000", "label": "Renamed" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^alert_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "type": { "type": "string" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "enabled": { "type": "boolean" }, "config": {}, "channels": { "type": "array", "items": {} }, "lastFiredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "firedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "id", "workspaceId", "type", "label", "enabled", "config", "channels", "lastFiredAt", "firedCount", "createdAt", "updatedAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Update alert.", "value": { "id": "alert_DEMO00000000000000000000", "workspaceId": "ws_DEMODEFAULT0000000000", "type": "quota_threshold", "label": "Renamed", "enabled": true, "config": {}, "channels": [], "lastFiredAt": null, "firedCount": 0, "createdAt": "2026-05-22T12:00:00.000Z", "updatedAt": "2026-05-22T12:05:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "alert.updated", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/alerts.delete": { "post": { "operationId": "alerts_delete", "summary": "Delete an alert rule.", "x-trustvice-description-key": "actions.alerts.delete.description", "tags": [ "alerts" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "alertId": { "type": "string", "pattern": "^alert_[0-9A-Z]{20,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "alertId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete alert.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "alertId": "alert_DEMO00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete alert.", "value": { "deleted": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "alert.deleted", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/alerts.enable": { "post": { "operationId": "alerts_enable", "summary": "Enable an alert rule.", "x-trustvice-description-key": "actions.alerts.enable.description", "tags": [ "alerts" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "alertId": { "type": "string", "pattern": "^alert_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId", "alertId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Enable.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "alertId": "alert_DEMO00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^alert_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "type": { "type": "string" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "enabled": { "type": "boolean" }, "config": {}, "channels": { "type": "array", "items": {} }, "lastFiredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "firedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "id", "workspaceId", "type", "label", "enabled", "config", "channels", "lastFiredAt", "firedCount", "createdAt", "updatedAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Enable.", "value": { "id": "alert_DEMO00000000000000000000", "workspaceId": "ws_DEMODEFAULT0000000000", "type": "quota_threshold", "label": "Quota", "enabled": true, "config": {}, "channels": [], "lastFiredAt": null, "firedCount": 0, "createdAt": "2026-05-22T12:00:00.000Z", "updatedAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "alert.updated", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/alerts.disable": { "post": { "operationId": "alerts_disable", "summary": "Disable an alert rule without deleting it.", "x-trustvice-description-key": "actions.alerts.disable.description", "tags": [ "alerts" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "alertId": { "type": "string", "pattern": "^alert_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId", "alertId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Disable.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "alertId": "alert_DEMO00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^alert_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "type": { "type": "string" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "enabled": { "type": "boolean" }, "config": {}, "channels": { "type": "array", "items": {} }, "lastFiredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "firedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "id", "workspaceId", "type", "label", "enabled", "config", "channels", "lastFiredAt", "firedCount", "createdAt", "updatedAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Disable.", "value": { "id": "alert_DEMO00000000000000000000", "workspaceId": "ws_DEMODEFAULT0000000000", "type": "quota_threshold", "label": "Quota", "enabled": false, "config": {}, "channels": [], "lastFiredAt": null, "firedCount": 0, "createdAt": "2026-05-22T12:00:00.000Z", "updatedAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "alert.updated", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/alerts.test-fire": { "post": { "operationId": "alerts_test-fire", "summary": "Fire a synthetic test of an alert to verify channels.", "x-trustvice-description-key": "actions.alerts.test-fire.description", "tags": [ "alerts" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "alertId": { "type": "string", "pattern": "^alert_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId", "alertId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Test fire.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "alertId": "alert_DEMO00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fired": { "type": "boolean" }, "channelResults": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "kind", "success" ], "additionalProperties": false } } }, "required": [ "fired", "channelResults" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Test fire.", "value": { "fired": true, "channelResults": [ { "kind": "email", "success": true } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/alerts.kinds.list": { "post": { "operationId": "alerts_kinds_list", "summary": "List all supported alert kinds + their config shapes + severity classifications.", "x-trustvice-description-key": "actions.alerts.kinds.list.description", "tags": [ "alerts" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Discover alert kinds.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "kinds": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "severity": { "type": "string", "enum": [ "ops", "billing", "compliance", "informational" ] }, "configurable": { "type": "boolean" } }, "required": [ "id", "label", "description", "severity", "configurable" ], "additionalProperties": false } } }, "required": [ "kinds" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Discover alert kinds.", "value": { "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 } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/alerts.history.list": { "post": { "operationId": "alerts_history_list", "summary": "List historical firings for a given alert rule.", "x-trustvice-description-key": "actions.alerts.history.list.description", "tags": [ "alerts" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "alertId": { "type": "string", "pattern": "^alert_[0-9A-Z]{20,}$" }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "workspaceId", "alertId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read alert fire history.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "alertId": "alert_DEMO00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "firings": { "type": "array", "items": { "type": "object", "properties": { "firedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "context": {} }, "required": [ "firedAt", "context" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "firings", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read alert fire history.", "value": { "firings": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/exports.list": { "post": { "operationId": "exports_list", "summary": "List exports for a workspace.", "x-trustvice-description-key": "actions.exports.list.description", "tags": [ "exports" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "status": { "type": "string", "enum": [ "queued", "running", "ready", "failed", "expired" ] }, "kind": { "type": "string", "enum": [ "audit-log", "entpoind-receipts", "trustvice-receipts", "eu-ai-act-article-12", "workspace-snapshot", "policy-pack", "tops-feed", "custody-log", "pii-portability", "compliance-bundle" ] } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List exports.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "exports": { "type": "array", "items": { "type": "object", "properties": { "exportId": { "type": "string" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "kind": { "type": "string", "enum": [ "audit-log", "entpoind-receipts", "trustvice-receipts", "eu-ai-act-article-12", "workspace-snapshot", "policy-pack", "tops-feed", "custody-log", "pii-portability", "compliance-bundle" ] }, "status": { "type": "string", "enum": [ "queued", "running", "ready", "failed", "expired" ] }, "format": { "type": "string", "enum": [ "json", "csv", "zip", "compliance-bundle" ] }, "requestedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "readyAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "signature": { "type": "string" }, "signingKeyId": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "signedUrl": { "type": "string", "format": "uri" } }, "required": [ "exportId", "workspaceId", "kind", "status", "format", "requestedAt", "readyAt", "expiresAt" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "exports", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List exports.", "value": { "exports": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "exports.view" ] }, { "OAuth2": [ "exports.view" ] }, { "WorkspaceApiKey": [ "exports.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/exports.get": { "post": { "operationId": "exports_get", "summary": "Get a single export's status + metadata.", "x-trustvice-description-key": "actions.exports.get.description", "tags": [ "exports" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "exportId": { "type": "string" } }, "required": [ "workspaceId", "exportId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read export status.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "exportId": "exp_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "exportId": { "type": "string" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "kind": { "type": "string", "enum": [ "audit-log", "entpoind-receipts", "trustvice-receipts", "eu-ai-act-article-12", "workspace-snapshot", "policy-pack", "tops-feed", "custody-log", "pii-portability", "compliance-bundle" ] }, "status": { "type": "string", "enum": [ "queued", "running", "ready", "failed", "expired" ] }, "format": { "type": "string", "enum": [ "json", "csv", "zip", "compliance-bundle" ] }, "requestedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "readyAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "signature": { "type": "string" }, "signingKeyId": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "signedUrl": { "type": "string", "format": "uri" } }, "required": [ "exportId", "workspaceId", "kind", "status", "format", "requestedAt", "readyAt", "expiresAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read export status.", "value": { "exportId": "exp_abc", "workspaceId": "ws_DEMODEFAULT0000000000", "kind": "audit-log", "status": "ready", "format": "json", "requestedAt": "2026-05-22T12:00:00.000Z", "readyAt": "2026-05-22T12:10:00.000Z", "expiresAt": "2026-05-29T12:10:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "exports.view" ] }, { "OAuth2": [ "exports.view" ] }, { "WorkspaceApiKey": [ "exports.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/exports.request": { "post": { "operationId": "exports_request", "summary": "Request a new compliance export. Returns the export id; status polls reveal readiness.", "x-trustvice-description-key": "actions.exports.request.description", "tags": [ "exports" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "kind": { "type": "string", "enum": [ "audit-log", "entpoind-receipts", "trustvice-receipts", "eu-ai-act-article-12", "workspace-snapshot", "policy-pack", "tops-feed", "custody-log", "pii-portability", "compliance-bundle" ] }, "format": { "default": "compliance-bundle", "type": "string", "enum": [ "json", "csv", "zip", "compliance-bundle" ] }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "until": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "filters": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "workspaceId", "kind" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Request a compliance bundle.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "kind": "compliance-bundle", "format": "zip" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "exportId": { "type": "string" }, "estimatedReadyAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "exportId", "estimatedReadyAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Request a compliance bundle.", "value": { "exportId": "exp_abc", "estimatedReadyAt": "2026-05-22T12:10:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "exports.create" ] }, { "OAuth2": [ "exports.create" ] }, { "WorkspaceApiKey": [ "exports.create" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": "export.requested", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/exports.download": { "post": { "operationId": "exports_download", "summary": "Get the signed download URL for a ready export (URL is time-bounded; SHA-256 included for integrity check).", "x-trustvice-description-key": "actions.exports.download.description", "tags": [ "exports" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "exportId": { "type": "string" } }, "required": [ "workspaceId", "exportId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Get signed download URL.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "exportId": "exp_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "url", "expiresAt", "sha256" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Get signed download URL.", "value": { "url": "https://r2.trustvice.com/exports/abc", "expiresAt": "2026-05-22T13:00:00.000Z", "sha256": "abcd1234567890abcdef1234567890abcdef1234567890abcdef12345678abcd" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "exports.download" ] }, { "OAuth2": [ "exports.download" ] }, { "WorkspaceApiKey": [ "exports.download" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "export.completed", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/exports.verify": { "post": { "operationId": "exports_verify", "summary": "Verify an export's Ed25519 signature + OTS Bitcoin proof. Offline-verifiable.", "x-trustvice-description-key": "actions.exports.verify.description", "tags": [ "exports" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "exportSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "signature": { "type": "string" }, "signingKeyId": { "type": "string" }, "otsProof": { "type": "string" } }, "required": [ "exportSha256", "signature", "signingKeyId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Offline verify an export.", "value": { "exportSha256": "abcd1234567890abcdef1234567890abcdef1234567890abcdef12345678abcd", "signature": "...", "signingKeyId": "trustvice-2026-q2-enam" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "valid": { "type": "boolean" }, "signatureValid": { "type": "boolean" }, "otsValid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "valid", "signatureValid", "otsValid", "errors" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Offline verify an export.", "value": { "valid": true, "signatureValid": true, "otsValid": true, "errors": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/exports.entpoind.receipt-bundle.request": { "post": { "operationId": "exports_entpoind_receipt-bundle_request", "summary": "Request a portable Entpoind-receipt bundle — JSON manifest + receipt files + public key JWK + verify README. Verifiable with @entpoind/verify.", "x-trustvice-description-key": "actions.exports.entpoind.receipt-bundle.request.description", "tags": [ "exports" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "until": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "primitiveFilter": { "type": "array", "items": { "type": "string" } }, "signingKeyIdFilter": { "type": "string" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Bundle Trustvice receipts.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "primitiveFilter": [ "agent.call", "content.attest" ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "exportId": { "type": "string" }, "estimatedReadyAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "exportId", "estimatedReadyAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Bundle Trustvice receipts.", "value": { "exportId": "exp_entp_abc", "estimatedReadyAt": "2026-05-22T12:15:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "exports.create" ] }, { "OAuth2": [ "exports.create" ] }, { "WorkspaceApiKey": [ "exports.create" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": "export.requested", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/exports.eu-ai-act.article-12.request": { "post": { "operationId": "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.", "x-trustvice-description-key": "actions.exports.eu-ai-act.article-12.request.description", "tags": [ "exports" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "until": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "jurisdictionFilter": { "default": "all", "type": "string", "enum": [ "WEUR", "ENAM", "all" ] } }, "required": [ "workspaceId", "since", "until" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "EU AI Act Art. 12 compliance export.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "since": "2026-04-01T00:00:00.000Z", "until": "2026-05-01T00:00:00.000Z" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "exportId": { "type": "string" }, "estimatedReadyAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "schemaVersion": { "type": "string" } }, "required": [ "exportId", "estimatedReadyAt", "schemaVersion" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "EU AI Act Art. 12 compliance export.", "value": { "exportId": "exp_eu12_abc", "estimatedReadyAt": "2026-05-22T12:30:00.000Z", "schemaVersion": "prEN-18229-1-draft-2026-03" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "exports.create" ] }, { "OAuth2": [ "exports.create" ] }, { "WorkspaceApiKey": [ "exports.create" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": "export.requested", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/exports.audit-log.request": { "post": { "operationId": "exports_audit-log_request", "summary": "Request a JSON or CSV export of the workspace audit log filtered by time + kind.", "x-trustvice-description-key": "actions.exports.audit-log.request.description", "tags": [ "exports" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "until": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "kindsFilter": { "type": "array", "items": { "type": "string" } }, "format": { "default": "json", "type": "string", "enum": [ "json", "csv" ] } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Export audit log as CSV.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "format": "csv" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "exportId": { "type": "string" }, "estimatedReadyAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "exportId", "estimatedReadyAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Export audit log as CSV.", "value": { "exportId": "exp_audit_abc", "estimatedReadyAt": "2026-05-22T12:10:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "exports.create", "settings.view_audit_log" ] }, { "OAuth2": [ "exports.create", "settings.view_audit_log" ] }, { "WorkspaceApiKey": [ "exports.create", "settings.view_audit_log" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": "export.requested", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/exports.kinds.list": { "post": { "operationId": "exports_kinds_list", "summary": "List the supported export kinds + their output formats + retention.", "x-trustvice-description-key": "actions.exports.kinds.list.description", "tags": [ "exports" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Discover export kinds.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "kinds": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "audit-log", "entpoind-receipts", "trustvice-receipts", "eu-ai-act-article-12", "workspace-snapshot", "policy-pack", "tops-feed", "custody-log", "pii-portability", "compliance-bundle" ] }, "label": { "type": "string" }, "description": { "type": "string" }, "supportedFormats": { "type": "array", "items": { "type": "string" } }, "retentionDays": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "label", "description", "supportedFormats", "retentionDays" ], "additionalProperties": false } } }, "required": [ "kinds" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Discover export kinds.", "value": { "kinds": [ { "id": "compliance-bundle", "label": "Compliance bundle", "description": "Full audit + custody + receipts + signing keys for offline verification.", "supportedFormats": [ "zip" ], "retentionDays": 7 } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/exports.delete": { "post": { "operationId": "exports_delete", "summary": "Delete a completed export (frees R2 storage immediately).", "x-trustvice-description-key": "actions.exports.delete.description", "tags": [ "exports" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "exportId": { "type": "string" } }, "required": [ "workspaceId", "exportId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete an export.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "exportId": "exp_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete an export.", "value": { "deleted": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "exports.view" ] }, { "OAuth2": [ "exports.view" ] }, { "WorkspaceApiKey": [ "exports.view" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/retention.policy.get": { "post": { "operationId": "retention_policy_get", "summary": "Get the active retention policy for a workspace.", "x-trustvice-description-key": "actions.retention.policy.get.description", "tags": [ "retention" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read retention policy.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "retentionDays": { "type": "integer", "minimum": 7, "maximum": 1825 }, "isCustom": { "type": "boolean" }, "appliedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "appliedBy": { "type": "string" } }, "required": [ "workspaceId", "retentionDays", "isCustom", "appliedAt", "appliedBy" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read retention policy.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "retentionDays": 365, "isCustom": false, "appliedAt": "2026-01-01T00:00:00.000Z", "appliedBy": "tier_default" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/retention.policy.update": { "post": { "operationId": "retention_policy_update", "summary": "Update workspace retention days (within tier limits).", "x-trustvice-description-key": "actions.retention.policy.update.description", "tags": [ "retention" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "retentionDays": { "type": "integer", "minimum": 7, "maximum": 1825 } }, "required": [ "workspaceId", "retentionDays" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Extend retention via paid extension.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "retentionDays": 730 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "retentionDays": { "type": "integer", "minimum": 7, "maximum": 1825 }, "isCustom": { "type": "boolean" }, "appliedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "appliedBy": { "type": "string" } }, "required": [ "workspaceId", "retentionDays", "isCustom", "appliedAt", "appliedBy" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Extend retention via paid extension.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "retentionDays": 730, "isCustom": true, "appliedAt": "2026-05-22T12:00:00.000Z", "appliedBy": "acc_DEMO00000000000000000000" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.edit_retention" ] }, { "OAuth2": [ "settings.edit_retention" ] }, { "WorkspaceApiKey": [ "settings.edit_retention" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "retention.updated", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/retention.histogram.get": { "post": { "operationId": "retention_histogram_get", "summary": "Get a histogram of record ages in the workspace (helps visualize what's near purge).", "x-trustvice-description-key": "actions.retention.histogram.get.description", "tags": [ "retention" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "bucketSizeDays": { "default": 7, "type": "integer", "minimum": 1, "maximum": 30 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read age distribution.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "ageDays": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "recordCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "ageDays", "recordCount" ], "additionalProperties": false } }, "totalRecords": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "oldestRecordAge": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "buckets", "totalRecords", "oldestRecordAge" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read age distribution.", "value": { "buckets": [ { "ageDays": 0, "recordCount": 1000 }, { "ageDays": 7, "recordCount": 900 } ], "totalRecords": 12000, "oldestRecordAge": 350 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/retention.next-purge.preview": { "post": { "operationId": "retention_next-purge_preview", "summary": "Preview which records will purge in the next cycle (live 1-Hz countdown on the dashboard).", "x-trustvice-description-key": "actions.retention.next-purge.preview.description", "tags": [ "retention" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "limit": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Preview upcoming purge.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "purgeAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "recordsToBepurged": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sampleEntries": { "type": "array", "items": {} } }, "required": [ "purgeAt", "recordsToBepurged", "sampleEntries" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Preview upcoming purge.", "value": { "purgeAt": "2026-05-22T13:00:00.000Z", "recordsToBepurged": 42, "sampleEntries": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/retention.purge-history.list": { "post": { "operationId": "retention_purge-history_list", "summary": "List historical purge events with verification status.", "x-trustvice-description-key": "actions.retention.purge-history.list.description", "tags": [ "retention" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read purge history.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "purges": { "type": "array", "items": { "type": "object", "properties": { "purgedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "recordsPurged": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "verificationState": { "type": "string", "enum": [ "verified", "awaiting_anchor", "unanchored" ] } }, "required": [ "purgedAt", "recordsPurged", "verificationState" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "purges", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read purge history.", "value": { "purges": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/retention.extension.subscribe": { "post": { "operationId": "retention_extension_subscribe", "summary": "Subscribe to the paid retention extension at the per-tier rate.", "x-trustvice-description-key": "actions.retention.extension.subscribe.description", "tags": [ "retention" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "extendedToDays": { "type": "integer", "minimum": 7, "maximum": 1825 } }, "required": [ "workspaceId", "extendedToDays" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Subscribe to 3-year retention extension.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "extendedToDays": 1095 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "extendedToDays": { "type": "integer", "minimum": 7, "maximum": 1825 }, "monthlyCostUsdMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "perGbMonthlyCostUsdMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "storageGbBilled": { "type": "number", "minimum": 0 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "canceledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "effectiveUntil": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "workspaceId", "extendedToDays", "monthlyCostUsdMinor", "perGbMonthlyCostUsdMinor", "storageGbBilled", "startedAt", "canceledAt", "effectiveUntil" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Subscribe to 3-year retention extension.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "extendedToDays": 1095, "monthlyCostUsdMinor": 1200, "perGbMonthlyCostUsdMinor": 1000, "storageGbBilled": 1.2, "startedAt": "2026-05-22T12:00:00.000Z", "canceledAt": null, "effectiveUntil": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.subscribe_addons" ] }, { "OAuth2": [ "billing.subscribe_addons" ] }, { "WorkspaceApiKey": [ "billing.subscribe_addons" ] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "billing", "x-trustvice-audit-kind": "retention.updated", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/retention.extension.get": { "post": { "operationId": "retention_extension_get", "summary": "Get the current retention extension subscription (if any).", "x-trustvice-description-key": "actions.retention.extension.get.description", "tags": [ "retention" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "A workspace with the 5-year retention extension.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } }, "example_1": { "summary": "Workspace has no extension subscription.", "value": { "workspaceId": "ws_NOEXTENSION0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "extendedToDays": { "type": "integer", "minimum": 7, "maximum": 1825 }, "monthlyCostUsdMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "perGbMonthlyCostUsdMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "storageGbBilled": { "type": "number", "minimum": 0 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "canceledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "effectiveUntil": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "workspaceId", "extendedToDays", "monthlyCostUsdMinor", "perGbMonthlyCostUsdMinor", "storageGbBilled", "startedAt", "canceledAt", "effectiveUntil" ], "additionalProperties": {} }, { "type": "null" } ] }, "examples": { "example_0": { "summary": "A workspace with the 5-year retention extension.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "extendedToDays": 1825, "monthlyCostUsdMinor": 2400, "perGbMonthlyCostUsdMinor": 1000, "storageGbBilled": 2.4, "startedAt": "2026-05-22T12:00:00.000Z", "canceledAt": null, "effectiveUntil": null } }, "example_1": { "summary": "Workspace has no extension subscription.", "value": null } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.view" ] }, { "OAuth2": [ "billing.view" ] }, { "WorkspaceApiKey": [ "billing.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/retention.extension.update": { "post": { "operationId": "retention_extension_update", "summary": "Update the active retention extension (change duration).", "x-trustvice-description-key": "actions.retention.extension.update.description", "tags": [ "retention" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "extendedToDays": { "type": "integer", "minimum": 7, "maximum": 1825 } }, "required": [ "workspaceId", "extendedToDays" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Bump to 5-year retention.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "extendedToDays": 1825 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "extendedToDays": { "type": "integer", "minimum": 7, "maximum": 1825 }, "monthlyCostUsdMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "perGbMonthlyCostUsdMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "storageGbBilled": { "type": "number", "minimum": 0 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "canceledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "effectiveUntil": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "workspaceId", "extendedToDays", "monthlyCostUsdMinor", "perGbMonthlyCostUsdMinor", "storageGbBilled", "startedAt", "canceledAt", "effectiveUntil" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Bump to 5-year retention.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "extendedToDays": 1825, "monthlyCostUsdMinor": 2400, "perGbMonthlyCostUsdMinor": 1000, "storageGbBilled": 2.4, "startedAt": "2026-05-22T12:00:00.000Z", "canceledAt": null, "effectiveUntil": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.subscribe_addons" ] }, { "OAuth2": [ "billing.subscribe_addons" ] }, { "WorkspaceApiKey": [ "billing.subscribe_addons" ] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "billing", "x-trustvice-audit-kind": "retention.updated", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/retention.extension.cancel": { "post": { "operationId": "retention_extension_cancel", "summary": "Cancel the retention extension at the end of the current billing period.", "x-trustvice-description-key": "actions.retention.extension.cancel.description", "tags": [ "retention" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Cancel at period end.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "extendedToDays": { "type": "integer", "minimum": 7, "maximum": 1825 }, "monthlyCostUsdMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "perGbMonthlyCostUsdMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "storageGbBilled": { "type": "number", "minimum": 0 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "canceledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "effectiveUntil": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "workspaceId", "extendedToDays", "monthlyCostUsdMinor", "perGbMonthlyCostUsdMinor", "storageGbBilled", "startedAt", "canceledAt", "effectiveUntil" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Cancel at period end.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "extendedToDays": 1825, "monthlyCostUsdMinor": 2400, "perGbMonthlyCostUsdMinor": 1000, "storageGbBilled": 2.4, "startedAt": "2026-05-22T12:00:00.000Z", "canceledAt": "2026-05-22T12:00:00.000Z", "effectiveUntil": "2026-06-22T00:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.subscribe_addons" ] }, { "OAuth2": [ "billing.subscribe_addons" ] }, { "WorkspaceApiKey": [ "billing.subscribe_addons" ] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "billing", "x-trustvice-audit-kind": "retention.updated", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/retention.extension.rates.list": { "post": { "operationId": "retention_extension_rates_list", "summary": "List the per-tier retention extension rates (USD cents per GB per month).", "x-trustvice-description-key": "actions.retention.extension.rates.list.description", "tags": [ "retention" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "List per-tier rates.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "rates": { "type": "array", "items": { "type": "object", "properties": { "tier": { "type": "string" }, "perGbCentsPerMonth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "tier", "perGbCentsPerMonth" ], "additionalProperties": false } } }, "required": [ "rates" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List per-tier rates.", "value": { "rates": [ { "tier": "free", "perGbCentsPerMonth": 1200 }, { "tier": "starter", "perGbCentsPerMonth": 1100 } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/retention.policy.suggested-tier.get": { "post": { "operationId": "retention_policy_suggested-tier_get", "summary": "Recommend a higher tier if the workspace's data growth + retention needs make extension uneconomical.", "x-trustvice-description-key": "actions.retention.policy.suggested-tier.get.description", "tags": [ "retention" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Suggested upgrade.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "suggestedTier": { "type": [ "string", "null" ] }, "monthlySavingsUsdMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "explanation": { "type": "string" } }, "required": [ "suggestedTier", "monthlySavingsUsdMinor", "explanation" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Suggested upgrade.", "value": { "suggestedTier": "pro", "monthlySavingsUsdMinor": 800, "explanation": "At your current storage growth, Pro tier's bundled retention saves about $8/mo over the extension." } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.view" ] }, { "OAuth2": [ "billing.view" ] }, { "WorkspaceApiKey": [ "billing.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/retention.audit.list": { "post": { "operationId": "retention_audit_list", "summary": "List retention-policy audit events (changes, purges, extensions).", "x-trustvice-description-key": "actions.retention.audit.list.description", "tags": [ "retention" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read retention audit.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entries": { "type": "array", "items": {} }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "entries", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read retention audit.", "value": { "entries": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view_audit_log" ] }, { "OAuth2": [ "settings.view_audit_log" ] }, { "WorkspaceApiKey": [ "settings.view_audit_log" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/retention.subject-key.issue": { "post": { "operationId": "retention_subject-key_issue", "summary": "Issue (or fetch) the per-subject data key whose destruction IS the erasure.", "x-trustvice-description-key": "actions.retention.subject-key.issue.description", "tags": [ "retention" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "dataSubjectRefHash": { "type": "string", "minLength": 1, "description": "A salted hash of the data subject reference — never the identifier itself." } }, "required": [ "dataSubjectRefHash" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "The plaintext key is never stored, so destroying the row is the shred.", "value": { "dataSubjectRefHash": "sha256:9f2c…" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "keyId": { "type": "string" }, "dek": { "type": "string", "description": "The plaintext data key, returned once. Only the wrapped form is stored; returning it on every read would put it in as many logs as there are calls." }, "created": { "type": "boolean", "description": "True when this call minted the key; false when it already existed." } }, "required": [ "keyId", "dek", "created" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "The plaintext key is never stored, so destroying the row is the shred.", "value": { "keyId": "sk_01J9", "dek": "base64url…", "created": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.edit_retention" ] }, { "OAuth2": [ "settings.edit_retention" ] }, { "WorkspaceApiKey": [ "settings.edit_retention" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "retention.updated", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/retention.subject.shred": { "post": { "operationId": "retention_subject_shred", "summary": "Destroy a data subject's key and append the destruction to the hash-chained shred ledger.", "x-trustvice-description-key": "actions.retention.subject.shred.description", "tags": [ "retention" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "dataSubjectRefHash": { "type": "string", "minLength": 1 } }, "required": [ "dataSubjectRefHash" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Destroy first, then append — a ledger entry for a destruction that did not happen is worse than no entry.", "value": { "dataSubjectRefHash": "sha256:9f2c…" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "shredded": { "type": "boolean" }, "keyId": { "type": [ "string", "null" ] }, "bytesAffected": { "type": "number" }, "recordKinds": { "type": "array", "items": { "type": "string" } }, "chainSeq": { "type": [ "number", "null" ] }, "reason": { "type": "string", "description": "Why this is the outcome. A key that encrypted nothing says so rather than reporting a successful erasure of nothing." }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "shredded", "keyId", "bytesAffected", "recordKinds", "chainSeq", "reason", "notes" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Destroy first, then append — a ledger entry for a destruction that did not happen is worse than no entry.", "value": { "shredded": true, "keyId": "sk_01J9", "bytesAffected": 40211, "recordKinds": [ "support_attachment" ], "chainSeq": 12, "reason": "The key was destroyed; the ciphertext it protected is unopenable.", "notes": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.edit_retention" ] }, { "OAuth2": [ "settings.edit_retention" ] }, { "WorkspaceApiKey": [ "settings.edit_retention" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": "retention.updated", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/retention.erasure-certificate.get": { "post": { "operationId": "retention_erasure-certificate_get", "summary": "Certify what was destroyed for one data subject, with the chain verified.", "x-trustvice-description-key": "actions.retention.erasure-certificate.get.description", "tags": [ "retention" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "dsrRef": { "type": "string", "minLength": 1, "description": "The data-subject-request this certificate answers." }, "dataSubjectRefHash": { "type": "string", "minLength": 1 } }, "required": [ "dsrRef", "dataSubjectRefHash" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "GDPR Art. 17 — what was destroyed, and what provably was not.", "value": { "dsrRef": "dsr_01J9", "dataSubjectRefHash": "sha256:9f2c…" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "certificate": { "type": "object", "properties": {}, "additionalProperties": {} }, "chainVerified": { "type": "boolean", "description": "False means the ledger did not verify — the certificate is then evidence of a broken chain, not of an erasure." }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "certificate", "chainVerified", "notes" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "GDPR Art. 17 — what was destroyed, and what provably was not.", "value": { "certificate": { "dsrRef": "dsr_01J9", "entries": 1 }, "chainVerified": true, "notes": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/audit.workspace.list": { "post": { "operationId": "audit_workspace_list", "summary": "List audit log entries for a workspace.", "x-trustvice-description-key": "actions.audit.workspace.list.description", "tags": [ "audit" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "until": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "kinds": { "type": "array", "items": { "type": "string" } }, "transport": { "type": "string", "enum": [ "rest", "mcp", "mcp_apps", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "a2a", "claude_skill", "nlweb", "dashboard", "sidecar", "service_to_service" ] }, "agentClientId": { "type": "string" }, "outcome": { "type": "string", "enum": [ "success", "denied", "failed", "partial" ] } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read workspace audit log.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^aud_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "timestamp": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "kind": { "type": "string" }, "actorAccountId": { "type": "string" }, "transport": { "type": "string", "enum": [ "rest", "mcp", "mcp_apps", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "a2a", "claude_skill", "nlweb", "dashboard", "sidecar", "service_to_service" ] }, "agentClientId": { "type": "string" }, "agentSessionId": { "type": "string" }, "promptExcerpt": { "type": "string", "maxLength": 200 }, "confirmationTokenId": { "type": "string" }, "delegationChainDepth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outcome": { "type": "string", "enum": [ "success", "denied", "failed", "partial" ] }, "inputHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "outputHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "id", "workspaceId", "timestamp", "kind", "outcome" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "entries", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read workspace audit log.", "value": { "entries": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view_audit_log" ] }, { "OAuth2": [ "settings.view_audit_log" ] }, { "WorkspaceApiKey": [ "settings.view_audit_log" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/audit.workspace.get": { "post": { "operationId": "audit_workspace_get", "summary": "Get a specific audit entry by id.", "x-trustvice-description-key": "actions.audit.workspace.get.description", "tags": [ "audit" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "entryId": { "type": "string", "pattern": "^aud_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId", "entryId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Fetch a single entry.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "entryId": "aud_DEMO00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^aud_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "timestamp": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "kind": { "type": "string" }, "actorAccountId": { "type": "string" }, "transport": { "type": "string", "enum": [ "rest", "mcp", "mcp_apps", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "a2a", "claude_skill", "nlweb", "dashboard", "sidecar", "service_to_service" ] }, "agentClientId": { "type": "string" }, "agentSessionId": { "type": "string" }, "promptExcerpt": { "type": "string", "maxLength": 200 }, "confirmationTokenId": { "type": "string" }, "delegationChainDepth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outcome": { "type": "string", "enum": [ "success", "denied", "failed", "partial" ] }, "inputHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "outputHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "id", "workspaceId", "timestamp", "kind", "outcome" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Fetch a single entry.", "value": { "id": "aud_DEMO00000000000000000000", "workspaceId": "ws_DEMODEFAULT0000000000", "timestamp": "2026-05-22T12:00:00.000Z", "kind": "workspace.created", "outcome": "success" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view_audit_log" ] }, { "OAuth2": [ "settings.view_audit_log" ] }, { "WorkspaceApiKey": [ "settings.view_audit_log" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/audit.workspace.search": { "post": { "operationId": "audit_workspace_search", "summary": "Full-text search across a workspace's audit log.", "x-trustvice-description-key": "actions.audit.workspace.search.description", "tags": [ "audit" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "query": { "type": "string", "minLength": 1, "maxLength": 500 }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "workspaceId", "query" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Search for any mention of an email in the audit log.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "query": "alice@example.com" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^aud_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "timestamp": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "kind": { "type": "string" }, "actorAccountId": { "type": "string" }, "transport": { "type": "string", "enum": [ "rest", "mcp", "mcp_apps", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "a2a", "claude_skill", "nlweb", "dashboard", "sidecar", "service_to_service" ] }, "agentClientId": { "type": "string" }, "agentSessionId": { "type": "string" }, "promptExcerpt": { "type": "string", "maxLength": 200 }, "confirmationTokenId": { "type": "string" }, "delegationChainDepth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outcome": { "type": "string", "enum": [ "success", "denied", "failed", "partial" ] }, "inputHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "outputHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "id", "workspaceId", "timestamp", "kind", "outcome" ], "additionalProperties": {} } } }, "required": [ "entries" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Search for any mention of an email in the audit log.", "value": { "entries": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view_audit_log" ] }, { "OAuth2": [ "settings.view_audit_log" ] }, { "WorkspaceApiKey": [ "settings.view_audit_log" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/audit.workspace.live-tail": { "post": { "operationId": "audit_workspace_live-tail", "summary": "Open a streaming subscription to new audit entries (SSE/streamable HTTP).", "x-trustvice-description-key": "actions.audit.workspace.live-tail.description", "tags": [ "audit" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "kinds": { "type": "array", "items": { "type": "string" } } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Open a live tail subscription.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subscription": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "subscription", "startedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Open a live tail subscription.", "value": { "subscription": "sub_abc", "startedAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view_audit_log" ] }, { "OAuth2": [ "settings.view_audit_log" ] }, { "WorkspaceApiKey": [ "settings.view_audit_log" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/audit.workspace.share": { "post": { "operationId": "audit_workspace_share", "summary": "Generate a time-bounded share URL to an audit entry (for external auditors).", "x-trustvice-description-key": "actions.audit.workspace.share.description", "tags": [ "audit" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "entryId": { "type": "string", "pattern": "^aud_[0-9A-Z]{20,}$" }, "ttlHours": { "default": 24, "anyOf": [ { "type": "number", "const": 1 }, { "type": "number", "const": 24 }, { "type": "number", "const": 168 } ] }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "workspaceId", "entryId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Share with auditor.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "entryId": "aud_DEMO00000000000000000000", "ttlHours": 24, "note": "Q3 audit — Foo & Co LLP" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "shareUrl": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "shareUrl", "expiresAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Share with auditor.", "value": { "shareUrl": "https://trustvice.com/audit/share/abc", "expiresAt": "2026-05-23T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view_audit_log" ] }, { "OAuth2": [ "settings.view_audit_log" ] }, { "WorkspaceApiKey": [ "settings.view_audit_log" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "admin.action", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/audit.workspace.share.list": { "post": { "operationId": "audit_workspace_share_list", "summary": "List the audit share links this workspace has minted, and whether each is still live.", "x-trustvice-description-key": "actions.audit.workspace.share.list.description", "tags": [ "audit" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "See what has been shared.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "shares": { "type": "array", "items": { "type": "object", "properties": { "shareId": { "type": "string" }, "entryId": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "live": { "type": "boolean" } }, "required": [ "shareId", "entryId", "note", "createdAt", "expiresAt", "revokedAt", "live" ], "additionalProperties": false } }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "shares", "count" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "See what has been shared.", "value": { "shares": [ { "shareId": "a1b2c3d4e5f6a1b2c3d4e5f6", "entryId": "aud_DEMO00000000000000000000", "note": "Q3 audit — Foo & Co LLP", "createdAt": "2026-05-22T12:00:00.000Z", "expiresAt": "2026-05-23T12:00:00.000Z", "revokedAt": null, "live": true } ], "count": 1 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view_audit_log" ] }, { "OAuth2": [ "settings.view_audit_log" ] }, { "WorkspaceApiKey": [ "settings.view_audit_log" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/audit.workspace.share.revoke": { "post": { "operationId": "audit_workspace_share_revoke", "summary": "Revoke an audit share link before it expires.", "x-trustvice-description-key": "actions.audit.workspace.share.revoke.description", "tags": [ "audit" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "shareId": { "type": "string", "minLength": 8, "maxLength": 64 } }, "required": [ "workspaceId", "shareId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Close a share early.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "shareId": "a1b2c3d4e5f6a1b2c3d4e5f6" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "shareId": { "type": "string" }, "revokedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "alreadyRevoked": { "type": "boolean" } }, "required": [ "shareId", "revokedAt", "alreadyRevoked" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Close a share early.", "value": { "shareId": "a1b2c3d4e5f6a1b2c3d4e5f6", "revokedAt": "2026-05-22T18:00:00.000Z", "alreadyRevoked": false } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view_audit_log" ] }, { "OAuth2": [ "settings.view_audit_log" ] }, { "WorkspaceApiKey": [ "settings.view_audit_log" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "admin.action", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/audit.custody.list": { "post": { "operationId": "audit_custody_list", "summary": "List custody chain entries for a workspace (hash-chained, Ed25519-signed).", "x-trustvice-description-key": "actions.audit.custody.list.description", "tags": [ "audit" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read custody chain.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cust_[A-Za-z0-9_-]+$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "timestamp": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "prevHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "entryHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "signature": { "type": "string" }, "signingKeyId": { "type": "string" } }, "required": [ "id", "workspaceId", "timestamp", "prevHash", "entryHash", "signature", "signingKeyId" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "entries", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read custody chain.", "value": { "entries": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view_audit_log" ] }, { "OAuth2": [ "settings.view_audit_log" ] }, { "WorkspaceApiKey": [ "settings.view_audit_log" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/audit.custody.get": { "post": { "operationId": "audit_custody_get", "summary": "Get a custody entry by id (includes Ed25519 signature for offline verification).", "x-trustvice-description-key": "actions.audit.custody.get.description", "tags": [ "audit" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "entryId": { "type": "string", "pattern": "^cust_[A-Za-z0-9_-]+$" } }, "required": [ "workspaceId", "entryId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Fetch a custody entry.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "entryId": "cust_DEMO0000-0000-0000-0000-000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^cust_[A-Za-z0-9_-]+$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "timestamp": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "prevHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "entryHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "signature": { "type": "string" }, "signingKeyId": { "type": "string" } }, "required": [ "id", "workspaceId", "timestamp", "prevHash", "entryHash", "signature", "signingKeyId" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Fetch a custody entry.", "value": { "id": "cus_DEMO00000000000000000000", "workspaceId": "ws_DEMODEFAULT0000000000", "timestamp": "2026-05-22T12:00:00.000Z", "prevHash": "0000000000000000000000000000000000000000000000000000000000000000", "entryHash": "abcd567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "signature": "...", "signingKeyId": "entpoind-2026-q2-enam" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view_audit_log" ] }, { "OAuth2": [ "settings.view_audit_log" ] }, { "WorkspaceApiKey": [ "settings.view_audit_log" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/audit.custody.verify": { "post": { "operationId": "audit_custody_verify", "summary": "Walk the workspace's custody chain and report whether it holds, naming the sequence where it breaks.", "x-trustvice-description-key": "actions.audit.custody.verify.description", "tags": [ "audit" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "limit": { "default": 1000, "type": "integer", "minimum": 1, "maximum": 5000 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify the custody chain.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "limit": 1000 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ok": { "type": "boolean" }, "checkedCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "tipHash": { "type": [ "string", "null" ] }, "breakAtSeq": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "breakReason": { "type": [ "string", "null" ] }, "truncated": { "type": "boolean" } }, "required": [ "ok", "checkedCount", "tipHash", "breakAtSeq", "breakReason", "truncated" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify the custody chain.", "value": { "ok": true, "checkedCount": 42, "tipHash": "abcd567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "breakAtSeq": null, "breakReason": null, "truncated": false } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view_audit_log" ] }, { "OAuth2": [ "settings.view_audit_log" ] }, { "WorkspaceApiKey": [ "settings.view_audit_log" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/audit.tops.list": { "post": { "operationId": "audit_tops_list", "summary": "List Tops feed entries (hash-chained + Ed25519-signed + OTS Bitcoin-anchored).", "x-trustvice-description-key": "actions.audit.tops.list.description", "tags": [ "audit" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "kinds": { "type": "array", "items": { "type": "string" } } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read Tops feed.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tops_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "timestamp": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "kind": { "type": "string" }, "prevHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "entryHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "signature": { "type": "string" }, "signingKeyId": { "type": "string" }, "otsProof": { "type": "string" } }, "required": [ "id", "workspaceId", "timestamp", "kind", "prevHash", "entryHash", "signature", "signingKeyId" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "entries", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read Tops feed.", "value": { "entries": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view_audit_log" ] }, { "OAuth2": [ "settings.view_audit_log" ] }, { "WorkspaceApiKey": [ "settings.view_audit_log" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/audit.tops.verify": { "post": { "operationId": "audit_tops_verify", "summary": "Verify the hash chain + signatures + OTS proof of a range of Tops entries.", "x-trustvice-description-key": "actions.audit.tops.verify.description", "tags": [ "audit" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "fromEntryId": { "type": "string", "pattern": "^tops_[0-9A-Z]{20,}$" }, "toEntryId": { "type": "string", "pattern": "^tops_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId", "fromEntryId", "toEntryId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify a Tops range end-to-end.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "fromEntryId": "tops_AAAA00000000000000000000", "toEntryId": "tops_ZZZZ00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "chainValid": { "type": "boolean" }, "signaturesValid": { "type": "boolean" }, "otsValid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "chainValid", "signaturesValid", "otsValid", "errors" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify a Tops range end-to-end.", "value": { "chainValid": true, "signaturesValid": true, "otsValid": true, "errors": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view_audit_log" ] }, { "OAuth2": [ "settings.view_audit_log" ] }, { "WorkspaceApiKey": [ "settings.view_audit_log" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/audit.tops.continuity": { "post": { "operationId": "audit_tops_continuity", "summary": "Check whether a Tops chain is committed through the period — the gap a passing hash walk cannot show.", "x-trustvice-description-key": "actions.audit.tops.continuity.description", "tags": [ "audit" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "periodEnd": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "The same chain audit.tops.verify reports as valid.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "standing": { "type": "string", "enum": [ "no_entries", "nothing_sealed", "assessed" ] }, "entryCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sealedCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unsealedCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "attestedAnchorCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "periodEnd": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "tail": { "type": [ "string", "null" ] }, "head": { "type": [ "string", "null" ] }, "continuous": { "type": "boolean" }, "missingEntries": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "supportedClaim": { "type": "string" }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "standing", "entryCount", "sealedCount", "unsealedCount", "attestedAnchorCount", "periodEnd", "tail", "head", "continuous", "missingEntries", "supportedClaim", "notes" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "The same chain audit.tops.verify reports as valid.", "value": { "standing": "nothing_sealed", "entryCount": 3, "sealedCount": 0, "unsealedCount": 3, "attestedAnchorCount": 0, "periodEnd": "2026-09-04T00:00:00.000Z", "tail": null, "head": null, "continuous": false, "missingEntries": 0, "supportedClaim": "All 3 entr(ies) link correctly and NONE is covered by a seal.", "notes": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view_audit_log" ] }, { "OAuth2": [ "settings.view_audit_log" ] }, { "WorkspaceApiKey": [ "settings.view_audit_log" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/audit.shadow-sessions.list": { "post": { "operationId": "audit_shadow-sessions_list", "summary": "List Trustvice-staff shadow-mode sessions on a workspace.", "x-trustvice-description-key": "actions.audit.shadow-sessions.list.description", "tags": [ "audit" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List Trustvice-staff shadow sessions.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sessions": { "type": "array", "items": {} }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "sessions", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List Trustvice-staff shadow sessions.", "value": { "sessions": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view_audit_log" ] }, { "OAuth2": [ "settings.view_audit_log" ] }, { "WorkspaceApiKey": [ "settings.view_audit_log" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/audit.shadow-sessions.get": { "post": { "operationId": "audit_shadow-sessions_get", "summary": "Get full details + action feed of a shadow-mode session.", "x-trustvice-description-key": "actions.audit.shadow-sessions.get.description", "tags": [ "audit" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "sessionId": { "type": "string" } }, "required": [ "workspaceId", "sessionId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Inspect a shadow session.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "sessionId": "shadow_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "session": {}, "actions": { "type": "array", "items": {} } }, "required": [ "session", "actions" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Inspect a shadow session.", "value": { "session": {}, "actions": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view_audit_log" ] }, { "OAuth2": [ "settings.view_audit_log" ] }, { "WorkspaceApiKey": [ "settings.view_audit_log" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/audit.aggregate": { "post": { "operationId": "audit_aggregate", "summary": "Group + count audit entries by a dimension (kind, transport, outcome, agentClientId).", "x-trustvice-description-key": "actions.audit.aggregate.description", "tags": [ "audit" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "by": { "type": "string", "enum": [ "kind", "transport", "outcome", "agentClientId" ] }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "until": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "workspaceId", "by" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Group by transport.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "by": "transport" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "buckets": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "key", "count" ], "additionalProperties": false } } }, "required": [ "buckets" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Group by transport.", "value": { "buckets": [ { "key": "rest", "count": 1234 }, { "key": "mcp", "count": 567 } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view_audit_log" ] }, { "OAuth2": [ "settings.view_audit_log" ] }, { "WorkspaceApiKey": [ "settings.view_audit_log" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/audit.kinds.list": { "post": { "operationId": "audit_kinds_list", "summary": "List all audit-kind discriminator values supported by the platform.", "x-trustvice-description-key": "actions.audit.kinds.list.description", "tags": [ "audit" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Discover audit kinds.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "kinds": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "category", "description" ], "additionalProperties": false } } }, "required": [ "kinds" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Discover audit kinds.", "value": { "kinds": [ { "id": "workspace.created", "category": "workspace", "description": "A new workspace was created." } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/audit.export.scoped": { "post": { "operationId": "audit_export_scoped", "summary": "Request a scoped CSV/JSON export of audit entries matching filters. Returns a download URL when ready (signed, time-bounded).", "x-trustvice-description-key": "actions.audit.export.scoped.description", "tags": [ "audit" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "until": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "kinds": { "type": "array", "items": { "type": "string" } }, "format": { "default": "json", "type": "string", "enum": [ "csv", "json", "compliance-bundle" ] } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Queue a compliance-bundle export.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "format": "compliance-bundle" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "exportId": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "ready" ] } }, "required": [ "exportId", "status" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Queue a compliance-bundle export.", "value": { "exportId": "exp_abc", "status": "queued" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "exports.create" ] }, { "OAuth2": [ "exports.create" ] }, { "WorkspaceApiKey": [ "exports.create" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": "export.requested", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/audit.outside-access.list": { "post": { "operationId": "audit_outside-access_list", "summary": "List entries representing access from outside the workspace's normal principals (admin reads, side-car reads, share-url access).", "x-trustvice-description-key": "actions.audit.outside-access.list.description", "tags": [ "audit" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "See every external touch on this workspace.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^aud_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "timestamp": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "kind": { "type": "string" }, "actorAccountId": { "type": "string" }, "transport": { "type": "string", "enum": [ "rest", "mcp", "mcp_apps", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "a2a", "claude_skill", "nlweb", "dashboard", "sidecar", "service_to_service" ] }, "agentClientId": { "type": "string" }, "agentSessionId": { "type": "string" }, "promptExcerpt": { "type": "string", "maxLength": 200 }, "confirmationTokenId": { "type": "string" }, "delegationChainDepth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outcome": { "type": "string", "enum": [ "success", "denied", "failed", "partial" ] }, "inputHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "outputHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "id", "workspaceId", "timestamp", "kind", "outcome" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "entries", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "See every external touch on this workspace.", "value": { "entries": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view_audit_log" ] }, { "OAuth2": [ "settings.view_audit_log" ] }, { "WorkspaceApiKey": [ "settings.view_audit_log" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/audit.stream.list": { "post": { "operationId": "audit_stream_list", "summary": "List the workspace's SIEM/S3 audit-stream destinations (Splunk HEC / Datadog / webhook / S3), with sealed credentials masked.", "x-trustvice-description-key": "actions.audit.stream.list.description", "tags": [ "audit" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "List audit-stream destinations.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "destinations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "splunk_hec", "datadog", "webhook", "s3" ] }, "displayName": { "type": "string" }, "enabled": { "type": "boolean" }, "endpoint": { "type": [ "string", "null" ] }, "datadogSite": { "type": [ "string", "null" ] }, "splunkIndex": { "type": [ "string", "null" ] }, "splunkSourcetype": { "type": [ "string", "null" ] }, "datadogService": { "type": [ "string", "null" ] }, "datadogTags": { "type": [ "string", "null" ] }, "s3Bucket": { "type": [ "string", "null" ] }, "s3Region": { "type": [ "string", "null" ] }, "s3Prefix": { "type": [ "string", "null" ] }, "s3AccessKeyId": { "type": [ "string", "null" ] }, "tokenConfigured": { "type": "boolean" }, "webhookSecretConfigured": { "type": "boolean" }, "cursorChainSeq": { "type": "number" }, "healthy": { "type": "boolean" }, "consecutiveFailures": { "type": "number" }, "lastSuccessAt": { "type": [ "string", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string" } }, "required": [ "id", "kind", "displayName", "enabled", "endpoint", "datadogSite", "splunkIndex", "splunkSourcetype", "datadogService", "datadogTags", "s3Bucket", "s3Region", "s3Prefix", "s3AccessKeyId", "tokenConfigured", "webhookSecretConfigured", "cursorChainSeq", "healthy", "consecutiveFailures", "lastSuccessAt", "lastError", "updatedAt" ], "additionalProperties": false } } }, "required": [ "destinations" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List audit-stream destinations.", "value": { "destinations": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/audit.stream.configure": { "post": { "operationId": "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.", "x-trustvice-description-key": "actions.audit.stream.configure.description", "tags": [ "audit" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "splunk_hec", "datadog", "webhook", "s3" ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 120 }, "enabled": { "type": "boolean" }, "endpoint": { "type": "string", "format": "uri" }, "datadogSite": { "type": "string" }, "splunkIndex": { "type": "string" }, "splunkSourcetype": { "type": "string" }, "datadogService": { "type": "string" }, "datadogTags": { "type": "string" }, "s3Bucket": { "type": "string" }, "s3Region": { "type": "string" }, "s3Prefix": { "type": "string" }, "s3AccessKeyId": { "type": "string" }, "token": { "type": "string" }, "webhookSecret": { "type": "string" }, "s3SecretAccessKey": { "type": "string" } }, "required": [ "kind", "displayName" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Add a Splunk HEC destination.", "value": { "kind": "splunk_hec", "displayName": "SOC Splunk", "endpoint": "https://http-inputs.splunkcloud.com", "token": "hec-EXAMPLE0000TOKEN0000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "destination": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "splunk_hec", "datadog", "webhook", "s3" ] }, "displayName": { "type": "string" }, "enabled": { "type": "boolean" }, "endpoint": { "type": [ "string", "null" ] }, "datadogSite": { "type": [ "string", "null" ] }, "splunkIndex": { "type": [ "string", "null" ] }, "splunkSourcetype": { "type": [ "string", "null" ] }, "datadogService": { "type": [ "string", "null" ] }, "datadogTags": { "type": [ "string", "null" ] }, "s3Bucket": { "type": [ "string", "null" ] }, "s3Region": { "type": [ "string", "null" ] }, "s3Prefix": { "type": [ "string", "null" ] }, "s3AccessKeyId": { "type": [ "string", "null" ] }, "tokenConfigured": { "type": "boolean" }, "webhookSecretConfigured": { "type": "boolean" }, "cursorChainSeq": { "type": "number" }, "healthy": { "type": "boolean" }, "consecutiveFailures": { "type": "number" }, "lastSuccessAt": { "type": [ "string", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string" } }, "required": [ "id", "kind", "displayName", "enabled", "endpoint", "datadogSite", "splunkIndex", "splunkSourcetype", "datadogService", "datadogTags", "s3Bucket", "s3Region", "s3Prefix", "s3AccessKeyId", "tokenConfigured", "webhookSecretConfigured", "cursorChainSeq", "healthy", "consecutiveFailures", "lastSuccessAt", "lastError", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "destination" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Add a Splunk HEC destination.", "value": { "destination": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.edit_integrations" ] }, { "OAuth2": [ "settings.edit_integrations" ] }, { "WorkspaceApiKey": [ "settings.edit_integrations" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "audit.stream.configured", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/audit.stream.delete": { "post": { "operationId": "audit_stream_delete", "summary": "Delete an audit-stream destination by id (workspace-scoped).", "x-trustvice-description-key": "actions.audit.stream.delete.description", "tags": [ "audit" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete a destination.", "value": { "id": "astr_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete a destination.", "value": { "deleted": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.edit_integrations" ] }, { "OAuth2": [ "settings.edit_integrations" ] }, { "WorkspaceApiKey": [ "settings.edit_integrations" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "audit.stream.configured", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tops.config.get": { "post": { "operationId": "tops_config_get", "summary": "Get the Tops config for a specific scope (org, workspace, or actor).", "x-trustvice-description-key": "actions.tops.config.get.description", "tags": [ "tops" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scope": { "type": "string", "enum": [ "org", "workspace", "actor" ] }, "scopeId": { "type": "string" } }, "required": [ "scope", "scopeId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read scope config.", "value": { "scope": "workspace", "scopeId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "org", "workspace", "actor" ] }, "scopeId": { "type": "string" }, "enabled": { "type": "boolean" }, "kinds": { "type": "array", "items": { "type": "string", "enum": [ "run", "policy_change", "key_event", "billing_event", "config_change" ] } }, "environments": { "type": "array", "items": { "type": "string" } }, "samplingPercent": { "type": "number", "minimum": 0, "maximum": 100 }, "detailLevel": { "type": "string", "enum": [ "safe", "extended", "forensic" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "updatedBy": { "type": "string" } }, "required": [ "scope", "scopeId", "enabled", "kinds", "environments", "samplingPercent", "detailLevel", "updatedAt", "updatedBy" ], "additionalProperties": {} }, { "type": "null" } ] }, "examples": { "example_0": { "summary": "Read scope config.", "value": { "scope": "workspace", "scopeId": "ws_DEMODEFAULT0000000000", "enabled": true, "kinds": [ "run", "policy_change" ], "environments": [ "production" ], "samplingPercent": 100, "detailLevel": "safe", "updatedAt": "2026-05-22T12:00:00.000Z", "updatedBy": "acc_DEMO00000000000000000000" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tops.config.set": { "post": { "operationId": "tops_config_set", "summary": "Set the Tops config for a scope. Forensic detail level requires explicit acknowledgement.", "x-trustvice-description-key": "actions.tops.config.set.description", "tags": [ "tops" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scope": { "type": "string", "enum": [ "org", "workspace", "actor" ] }, "scopeId": { "type": "string" }, "enabled": { "type": "boolean" }, "kinds": { "type": "array", "items": { "type": "string" } }, "environments": { "type": "array", "items": { "type": "string" } }, "samplingPercent": { "type": "number", "minimum": 0, "maximum": 100 }, "detailLevel": { "type": "string", "enum": [ "safe", "extended", "forensic" ] }, "forensicAck": { "type": "string" } }, "required": [ "scope", "scopeId", "enabled", "kinds", "environments", "samplingPercent", "detailLevel" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Set scope config.", "value": { "scope": "workspace", "scopeId": "ws_DEMODEFAULT0000000000", "enabled": true, "kinds": [ "run", "policy_change" ], "environments": [ "production" ], "samplingPercent": 100, "detailLevel": "extended" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scope": { "type": "string", "enum": [ "org", "workspace", "actor" ] }, "scopeId": { "type": "string" }, "enabled": { "type": "boolean" }, "kinds": { "type": "array", "items": { "type": "string", "enum": [ "run", "policy_change", "key_event", "billing_event", "config_change" ] } }, "environments": { "type": "array", "items": { "type": "string" } }, "samplingPercent": { "type": "number", "minimum": 0, "maximum": 100 }, "detailLevel": { "type": "string", "enum": [ "safe", "extended", "forensic" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "updatedBy": { "type": "string" } }, "required": [ "scope", "scopeId", "enabled", "kinds", "environments", "samplingPercent", "detailLevel", "updatedAt", "updatedBy" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Set scope config.", "value": { "scope": "workspace", "scopeId": "ws_DEMODEFAULT0000000000", "enabled": true, "kinds": [ "run", "policy_change" ], "environments": [ "production" ], "samplingPercent": 100, "detailLevel": "extended", "updatedAt": "2026-05-22T12:00:00.000Z", "updatedBy": "acc_DEMO00000000000000000000" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "admin.action", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tops.config.delete": { "post": { "operationId": "tops_config_delete", "summary": "Delete a scope-level Tops config (scope reverts to parent inheritance).", "x-trustvice-description-key": "actions.tops.config.delete.description", "tags": [ "tops" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scope": { "type": "string", "enum": [ "org", "workspace", "actor" ] }, "scopeId": { "type": "string" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "scope", "scopeId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete scope config.", "value": { "scope": "workspace", "scopeId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete scope config.", "value": { "deleted": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "admin.action", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tops.config.list": { "post": { "operationId": "tops_config_list", "summary": "List Tops configs (all scopes in an org or workspace).", "x-trustvice-description-key": "actions.tops.config.list.description", "tags": [ "tops" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "organizationId": { "type": "string", "pattern": "^org_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "List configs.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "configs": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "org", "workspace", "actor" ] }, "scopeId": { "type": "string" }, "enabled": { "type": "boolean" }, "kinds": { "type": "array", "items": { "type": "string", "enum": [ "run", "policy_change", "key_event", "billing_event", "config_change" ] } }, "environments": { "type": "array", "items": { "type": "string" } }, "samplingPercent": { "type": "number", "minimum": 0, "maximum": 100 }, "detailLevel": { "type": "string", "enum": [ "safe", "extended", "forensic" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "updatedBy": { "type": "string" } }, "required": [ "scope", "scopeId", "enabled", "kinds", "environments", "samplingPercent", "detailLevel", "updatedAt", "updatedBy" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "configs", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List configs.", "value": { "configs": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tops.config.cascade.resolve": { "post": { "operationId": "tops_config_cascade_resolve", "summary": "Resolve the effective Tops config at a specific (org, workspace, actor) leaf — applies the leaf-wins cascade.", "x-trustvice-description-key": "actions.tops.config.cascade.resolve.description", "tags": [ "tops" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "pattern": "^org_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "actorId": { "type": "string", "pattern": "^actor_[a-z0-9]{20,}$" } }, "required": [ "organizationId", "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Resolve effective config.", "value": { "organizationId": "org_DEMO00000000000000000000", "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "effectiveConfig": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "org", "workspace", "actor" ] }, "scopeId": { "type": "string" }, "enabled": { "type": "boolean" }, "kinds": { "type": "array", "items": { "type": "string", "enum": [ "run", "policy_change", "key_event", "billing_event", "config_change" ] } }, "environments": { "type": "array", "items": { "type": "string" } }, "samplingPercent": { "type": "number", "minimum": 0, "maximum": 100 }, "detailLevel": { "type": "string", "enum": [ "safe", "extended", "forensic" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "updatedBy": { "type": "string" } }, "required": [ "scope", "scopeId", "enabled", "kinds", "environments", "samplingPercent", "detailLevel", "updatedAt", "updatedBy" ], "additionalProperties": {} }, "source": { "type": "string", "enum": [ "org", "workspace", "actor" ] }, "inheritedFields": { "type": "array", "items": { "type": "string" } } }, "required": [ "effectiveConfig", "source", "inheritedFields" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Resolve effective config.", "value": { "effectiveConfig": { "scope": "workspace", "scopeId": "ws_DEMODEFAULT0000000000", "enabled": true, "kinds": [ "run" ], "environments": [ "production" ], "samplingPercent": 100, "detailLevel": "safe", "updatedAt": "2026-05-22T12:00:00.000Z", "updatedBy": "acc_DEMO00000000000000000000" }, "source": "workspace", "inheritedFields": [ "environments" ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tops.config.preset.apply": { "post": { "operationId": "tops_config_preset_apply", "summary": "Apply one of the 3 presets (Minimal / Recommended / Forensic) to a scope.", "x-trustvice-description-key": "actions.tops.config.preset.apply.description", "tags": [ "tops" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scope": { "type": "string", "enum": [ "org", "workspace", "actor" ] }, "scopeId": { "type": "string" }, "presetId": { "type": "string", "enum": [ "minimal", "recommended", "forensic" ] }, "forensicAck": { "type": "string" } }, "required": [ "scope", "scopeId", "presetId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Apply recommended preset.", "value": { "scope": "workspace", "scopeId": "ws_DEMODEFAULT0000000000", "presetId": "recommended" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scope": { "type": "string", "enum": [ "org", "workspace", "actor" ] }, "scopeId": { "type": "string" }, "enabled": { "type": "boolean" }, "kinds": { "type": "array", "items": { "type": "string", "enum": [ "run", "policy_change", "key_event", "billing_event", "config_change" ] } }, "environments": { "type": "array", "items": { "type": "string" } }, "samplingPercent": { "type": "number", "minimum": 0, "maximum": 100 }, "detailLevel": { "type": "string", "enum": [ "safe", "extended", "forensic" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "updatedBy": { "type": "string" } }, "required": [ "scope", "scopeId", "enabled", "kinds", "environments", "samplingPercent", "detailLevel", "updatedAt", "updatedBy" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Apply recommended preset.", "value": { "scope": "workspace", "scopeId": "ws_DEMODEFAULT0000000000", "enabled": true, "kinds": [ "run", "policy_change", "key_event" ], "environments": [ "production" ], "samplingPercent": 100, "detailLevel": "safe", "updatedAt": "2026-05-22T12:00:00.000Z", "updatedBy": "acc_DEMO00000000000000000000" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "admin.action", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tops.config.presets.list": { "post": { "operationId": "tops_config_presets_list", "summary": "List the 3 supported presets with their config shapes + tradeoff labels.", "x-trustvice-description-key": "actions.tops.config.presets.list.description", "tags": [ "tops" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Discover presets.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "presets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "config": {}, "tradeoff": { "type": "string" } }, "required": [ "id", "label", "description", "config", "tradeoff" ], "additionalProperties": false } } }, "required": [ "presets" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Discover presets.", "value": { "presets": [ { "id": "minimal", "label": "Minimal", "description": "Smallest footprint; just the essentials.", "config": {}, "tradeoff": "May miss forensic detail in incidents." } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tops.config.testbed.run": { "post": { "operationId": "tops_config_testbed_run", "summary": "Test the cascade resolver against a synthetic actor id to preview what entries it would generate.", "x-trustvice-description-key": "actions.tops.config.testbed.run.description", "tags": [ "tops" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "pattern": "^org_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "actorId": { "type": "string", "pattern": "^actor_[a-z0-9]{20,}$" }, "syntheticEvent": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "organizationId", "workspaceId", "actorId", "syntheticEvent" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Test cascade.", "value": { "organizationId": "org_DEMO00000000000000000000", "workspaceId": "ws_DEMODEFAULT0000000000", "actorId": "actor_demo00000000000000000000", "syntheticEvent": { "kind": "run" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "resolved": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "org", "workspace", "actor" ] }, "scopeId": { "type": "string" }, "enabled": { "type": "boolean" }, "kinds": { "type": "array", "items": { "type": "string", "enum": [ "run", "policy_change", "key_event", "billing_event", "config_change" ] } }, "environments": { "type": "array", "items": { "type": "string" } }, "samplingPercent": { "type": "number", "minimum": 0, "maximum": 100 }, "detailLevel": { "type": "string", "enum": [ "safe", "extended", "forensic" ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "updatedBy": { "type": "string" } }, "required": [ "scope", "scopeId", "enabled", "kinds", "environments", "samplingPercent", "detailLevel", "updatedAt", "updatedBy" ], "additionalProperties": {} }, "wouldRecord": { "type": "boolean" }, "wouldRecordFields": { "type": "array", "items": { "type": "string" } } }, "required": [ "resolved", "wouldRecord", "wouldRecordFields" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Test cascade.", "value": { "resolved": { "scope": "workspace", "scopeId": "ws_DEMODEFAULT0000000000", "enabled": true, "kinds": [ "run" ], "environments": [ "production" ], "samplingPercent": 100, "detailLevel": "safe", "updatedAt": "2026-05-22T12:00:00.000Z", "updatedBy": "acc_DEMO00000000000000000000" }, "wouldRecord": true, "wouldRecordFields": [ "kind", "timestamp" ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tops.config.change-history.list": { "post": { "operationId": "tops_config_change-history_list", "summary": "List Tops-config change events (audit cross-link).", "x-trustvice-description-key": "actions.tops.config.change-history.list.description", "tags": [ "tops" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "scope": { "type": "string", "enum": [ "org", "workspace", "actor" ] }, "scopeId": { "type": "string" }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read config change history.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "changes": { "type": "array", "items": {} }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "changes", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read config change history.", "value": { "changes": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tops.config.sparkline.get": { "post": { "operationId": "tops_config_sparkline_get", "summary": "Get a 30-day sparkline of Tops detail-level changes (visualizes forensic-cooldown nudge).", "x-trustvice-description-key": "actions.tops.config.sparkline.get.description", "tags": [ "tops" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scope": { "type": "string", "enum": [ "org", "workspace", "actor" ] }, "scopeId": { "type": "string" } }, "required": [ "scope", "scopeId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Sparkline data.", "value": { "scope": "workspace", "scopeId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "detailLevel": { "type": "string", "enum": [ "safe", "extended", "forensic" ] } }, "required": [ "date", "detailLevel" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Sparkline data.", "value": { "data": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tops.config.audit-cross-links.get": { "post": { "operationId": "tops_config_audit-cross-links_get", "summary": "Get deep-links to the workspace audit log filtered by Tops-config-change events.", "x-trustvice-description-key": "actions.tops.config.audit-cross-links.get.description", "tags": [ "tops" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Audit cross-link helper.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "links": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "href": { "type": "string" } }, "required": [ "label", "href" ], "additionalProperties": false } } }, "required": [ "links" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Audit cross-link helper.", "value": { "links": [ { "label": "Recent config changes", "href": "/app/audit-log?source=tops" } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tops.config.cooldown-status.get": { "post": { "operationId": "tops_config_cooldown-status_get", "summary": "Check if a scope is in the forensic cooldown window (auto-revert nudge).", "x-trustvice-description-key": "actions.tops.config.cooldown-status.get.description", "tags": [ "tops" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scope": { "type": "string", "enum": [ "org", "workspace", "actor" ] }, "scopeId": { "type": "string" } }, "required": [ "scope", "scopeId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read cooldown state.", "value": { "scope": "workspace", "scopeId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "inCooldown": { "type": "boolean" }, "enteredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "inCooldown", "enteredAt", "expiresAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read cooldown state.", "value": { "inCooldown": false, "enteredAt": null, "expiresAt": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "settings.view" ] }, { "OAuth2": [ "settings.view" ] }, { "WorkspaceApiKey": [ "settings.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/referrals.code.get": { "post": { "operationId": "referrals_code_get", "summary": "Get your active referral code + share URL.", "x-trustvice-description-key": "actions.referrals.code.get.description", "tags": [ "referrals" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read your referral code.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Z0-9]{6,16}$" }, "shareUrl": { "type": "string", "format": "uri" }, "qrCodeDataUrl": { "type": "string" } }, "required": [ "code", "shareUrl", "qrCodeDataUrl" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read your referral code.", "value": { "code": "DEMO12", "shareUrl": "https://trustvice.com/?ref=DEMO12", "qrCodeDataUrl": "data:image/png;base64,..." } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/referrals.code.regenerate": { "post": { "operationId": "referrals_code_regenerate", "summary": "Regenerate referral code. Old code stops working.", "x-trustvice-description-key": "actions.referrals.code.regenerate.description", "tags": [ "referrals" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Get a fresh referral code.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Z0-9]{6,16}$" } }, "required": [ "code" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Get a fresh referral code.", "value": { "code": "NEWCODE99" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/referrals.list-sent": { "post": { "operationId": "referrals_list-sent", "summary": "List referrals you have sent.", "x-trustvice-description-key": "actions.referrals.list-sent.description", "tags": [ "referrals" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "status": { "type": "string", "enum": [ "sent", "joined", "redeemed", "expired" ] } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "List sent referrals.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "referrals": { "type": "array", "items": { "type": "object", "properties": { "referralId": { "type": "string" }, "code": { "type": "string", "pattern": "^[A-Z0-9]{6,16}$" }, "status": { "type": "string", "enum": [ "sent", "joined", "redeemed", "expired" ] }, "recipientEmailHash": { "type": "string" }, "sentAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "redeemedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "rewardPoints": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "referralId", "code", "status", "sentAt", "redeemedAt", "rewardPoints" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "referrals", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List sent referrals.", "value": { "referrals": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/referrals.list-received": { "post": { "operationId": "referrals_list-received", "summary": "List referrals where you were the referee.", "x-trustvice-description-key": "actions.referrals.list-received.description", "tags": [ "referrals" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "List received referrals.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "referrals": { "type": "array", "items": { "type": "object", "properties": { "referralId": { "type": "string" }, "code": { "type": "string", "pattern": "^[A-Z0-9]{6,16}$" }, "status": { "type": "string", "enum": [ "sent", "joined", "redeemed", "expired" ] }, "recipientEmailHash": { "type": "string" }, "sentAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "redeemedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "rewardPoints": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "referralId", "code", "status", "sentAt", "redeemedAt", "rewardPoints" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "referrals", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List received referrals.", "value": { "referrals": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/referrals.balance.get": { "post": { "operationId": "referrals_balance_get", "summary": "Get your current point balance + lifetime multiplier tier.", "x-trustvice-description-key": "actions.referrals.balance.get.description", "tags": [ "referrals" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read point balance.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "pointBalance": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lifetimeMultiplier": { "type": "number", "minimum": 1, "maximum": 2 }, "nextMultiplierAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "pointBalance", "lifetimeMultiplier", "nextMultiplierAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read point balance.", "value": { "pointBalance": 1500, "lifetimeMultiplier": 1.2, "nextMultiplierAt": 2500 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/referrals.funnel.get": { "post": { "operationId": "referrals_funnel_get", "summary": "Get conversion funnel analytics (sent → clicked → joined → redeemed).", "x-trustvice-description-key": "actions.referrals.funnel.get.description", "tags": [ "referrals" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read funnel.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sent": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "clicked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "joined": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "redeemed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "sent", "clicked", "joined", "redeemed" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read funnel.", "value": { "sent": 50, "clicked": 30, "joined": 12, "redeemed": 8 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/referrals.redeem": { "post": { "operationId": "referrals_redeem", "summary": "Redeem a referral or voucher code.", "x-trustvice-description-key": "actions.referrals.redeem.description", "tags": [ "referrals" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "code": { "type": "string", "minLength": 6, "maxLength": 20 } }, "required": [ "code" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Redeem a code.", "value": { "code": "DEMO12" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "redeemed": { "type": "boolean" }, "rewardKind": { "type": "string" }, "rewardValue": {} }, "required": [ "redeemed", "rewardKind", "rewardValue" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Redeem a code.", "value": { "redeemed": true, "rewardKind": "points", "rewardValue": 1000 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/referrals.spend": { "post": { "operationId": "referrals_spend", "summary": "Spend points on a reward (run pack, add-on credit, Every.org charity, etc.).", "x-trustvice-description-key": "actions.referrals.spend.description", "tags": [ "referrals" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "product": { "type": "string" }, "pointAmount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "product", "pointAmount" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Donate to charity.", "value": { "product": "every-org-charity", "pointAmount": 200, "metadata": { "charityId": "every:childrens-hospital" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "spentAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "transactionId": { "type": "string" }, "remainingBalance": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "spentAt", "transactionId", "remainingBalance" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Donate to charity.", "value": { "spentAt": "2026-05-22T12:00:00.000Z", "transactionId": "tx_abc", "remainingBalance": 1300 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/referrals.spend-products.list": { "post": { "operationId": "referrals_spend-products_list", "summary": "List the products you can redeem points against.", "x-trustvice-description-key": "actions.referrals.spend-products.list.description", "tags": [ "referrals" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Discover spend products.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "pointCost": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "description": { "type": "string" } }, "required": [ "id", "label", "pointCost", "description" ], "additionalProperties": false } } }, "required": [ "products" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Discover spend products.", "value": { "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." } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/referrals.ledger.list": { "post": { "operationId": "referrals_ledger_list", "summary": "List point transactions (earned + spent).", "x-trustvice-description-key": "actions.referrals.ledger.list.description", "tags": [ "referrals" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read point ledger.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "transactions": { "type": "array", "items": { "type": "object", "properties": { "ts": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "kind": { "type": "string", "enum": [ "earned", "spent", "expired", "adjustment" ] }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": { "type": "string" } }, "required": [ "ts", "kind", "amount", "description" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "transactions", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read point ledger.", "value": { "transactions": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/number_one.conversation.create": { "post": { "operationId": "number_one_conversation_create", "summary": "Start a new Number One conversation.", "x-trustvice-description-key": "actions.number_one.conversation.create.description", "tags": [ "number_one" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "mode": { "type": "string", "enum": [ "calculator", "analyst", "admin" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "workspaceId", "mode" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Start a new conversation.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "mode": "analyst", "title": "Q3 audit review" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "pattern": "^conv_[a-z0-9]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "mode": { "type": "string", "enum": [ "calculator", "analyst", "admin" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 80 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "lastActivityAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "messageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "factsLearnedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "conversationId", "workspaceId", "mode", "startedAt", "lastActivityAt", "messageCount", "factsLearnedCount" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Start a new conversation.", "value": { "conversationId": "conv_demo00000000000000000000", "workspaceId": "ws_DEMODEFAULT0000000000", "mode": "analyst", "title": "Q3 audit review", "startedAt": "2026-05-22T12:00:00.000Z", "lastActivityAt": "2026-05-22T12:00:00.000Z", "messageCount": 0, "factsLearnedCount": 0 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/number_one.conversation.list": { "post": { "operationId": "number_one_conversation_list", "summary": "List your conversations (most recent first).", "x-trustvice-description-key": "actions.number_one.conversation.list.description", "tags": [ "number_one" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "mode": { "type": "string", "enum": [ "calculator", "analyst", "admin" ] } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List conversations.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversations": { "type": "array", "items": { "type": "object", "properties": { "conversationId": { "type": "string", "pattern": "^conv_[a-z0-9]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "mode": { "type": "string", "enum": [ "calculator", "analyst", "admin" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 80 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "lastActivityAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "messageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "factsLearnedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "conversationId", "workspaceId", "mode", "startedAt", "lastActivityAt", "messageCount", "factsLearnedCount" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "conversations", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List conversations.", "value": { "conversations": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/number_one.conversation.get": { "post": { "operationId": "number_one_conversation_get", "summary": "Get a conversation's metadata + recent messages.", "x-trustvice-description-key": "actions.number_one.conversation.get.description", "tags": [ "number_one" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "conversationId": { "type": "string", "pattern": "^conv_[a-z0-9]{20,}$" }, "messageLimit": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "workspaceId", "conversationId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read a conversation.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "conversationId": "conv_demo00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversation": { "type": "object", "properties": { "conversationId": { "type": "string", "pattern": "^conv_[a-z0-9]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "mode": { "type": "string", "enum": [ "calculator", "analyst", "admin" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 80 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "lastActivityAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "messageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "factsLearnedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "conversationId", "workspaceId", "mode", "startedAt", "lastActivityAt", "messageCount", "factsLearnedCount" ], "additionalProperties": {} }, "messages": { "type": "array", "items": { "type": "object", "properties": { "messageId": { "type": "string", "pattern": "^msg_[a-z0-9]{20,}$" }, "conversationId": { "type": "string", "pattern": "^conv_[a-z0-9]{20,}$" }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "body": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "citations": { "type": "array", "items": {} }, "intent": { "type": "string" } }, "required": [ "messageId", "conversationId", "role", "body", "createdAt" ], "additionalProperties": false } } }, "required": [ "conversation", "messages" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read a conversation.", "value": { "conversation": { "conversationId": "conv_demo00000000000000000000", "workspaceId": "ws_DEMODEFAULT0000000000", "mode": "analyst", "startedAt": "2026-05-22T12:00:00.000Z", "lastActivityAt": "2026-05-22T12:00:00.000Z", "messageCount": 0, "factsLearnedCount": 0 }, "messages": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/number_one.conversation.delete": { "post": { "operationId": "number_one_conversation_delete", "summary": "Delete a conversation. Memory facts attached to it survive but lose conversation context.", "x-trustvice-description-key": "actions.number_one.conversation.delete.description", "tags": [ "number_one" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "conversationId": { "type": "string", "pattern": "^conv_[a-z0-9]{20,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "conversationId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete a conversation.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "conversationId": "conv_demo00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete a conversation.", "value": { "deleted": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/number_one.message.send": { "post": { "operationId": "number_one_message_send", "summary": "Send a user message in a Number One conversation. Response streams back via SSE.", "x-trustvice-description-key": "actions.number_one.message.send.description", "tags": [ "number_one" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "conversationId": { "type": "string", "pattern": "^conv_[a-z0-9]{20,}$" }, "body": { "type": "string", "minLength": 1, "maxLength": 50000 } }, "required": [ "workspaceId", "conversationId", "body" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Send a message.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "conversationId": "conv_demo00000000000000000000", "body": "What was my Trustvice Receipts usage last week?" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "assistantMessageId": { "type": "string", "pattern": "^msg_[a-z0-9]{20,}$" }, "intent": { "type": "string" }, "confirmationRequired": { "type": "boolean" }, "confirmationUrl": { "type": "string", "format": "uri" } }, "required": [ "assistantMessageId", "confirmationRequired" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Send a message.", "value": { "assistantMessageId": "msg_demo00000000000000000000", "intent": "read", "confirmationRequired": false } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/number_one.message.list": { "post": { "operationId": "number_one_message_list", "summary": "List messages in a conversation.", "x-trustvice-description-key": "actions.number_one.message.list.description", "tags": [ "number_one" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "conversationId": { "type": "string", "pattern": "^conv_[a-z0-9]{20,}$" } }, "required": [ "workspaceId", "conversationId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List messages.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "conversationId": "conv_demo00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "messageId": { "type": "string", "pattern": "^msg_[a-z0-9]{20,}$" }, "conversationId": { "type": "string", "pattern": "^conv_[a-z0-9]{20,}$" }, "role": { "type": "string", "enum": [ "user", "assistant", "system" ] }, "body": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "citations": { "type": "array", "items": {} }, "intent": { "type": "string" } }, "required": [ "messageId", "conversationId", "role", "body", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "messages", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List messages.", "value": { "messages": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/number_one.mode.set": { "post": { "operationId": "number_one_mode_set", "summary": "Switch a conversation's mode (Calculator / Analyst / Admin).", "x-trustvice-description-key": "actions.number_one.mode.set.description", "tags": [ "number_one" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "conversationId": { "type": "string", "pattern": "^conv_[a-z0-9]{20,}$" }, "mode": { "type": "string", "enum": [ "calculator", "analyst", "admin" ] } }, "required": [ "workspaceId", "conversationId", "mode" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Switch to Admin mode (requires step-up auth).", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "conversationId": "conv_demo00000000000000000000", "mode": "admin" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "pattern": "^conv_[a-z0-9]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "mode": { "type": "string", "enum": [ "calculator", "analyst", "admin" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 80 }, "startedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "lastActivityAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "messageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "factsLearnedCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "conversationId", "workspaceId", "mode", "startedAt", "lastActivityAt", "messageCount", "factsLearnedCount" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Switch to Admin mode (requires step-up auth).", "value": { "conversationId": "conv_demo00000000000000000000", "workspaceId": "ws_DEMODEFAULT0000000000", "mode": "admin", "startedAt": "2026-05-22T12:00:00.000Z", "lastActivityAt": "2026-05-22T12:00:00.000Z", "messageCount": 5, "factsLearnedCount": 2 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/number_one.memory.list": { "post": { "operationId": "number_one_memory_list", "summary": "List memory facts pinned in a workspace.", "x-trustvice-description-key": "actions.number_one.memory.list.description", "tags": [ "number_one" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "pinnedOnly": { "default": false, "type": "boolean" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List memory facts.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "facts": { "type": "array", "items": { "type": "object", "properties": { "factId": { "type": "string", "pattern": "^fact_[a-z0-9]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "text": { "type": "string" }, "pinned": { "type": "boolean" }, "learnedFrom": { "type": "string" }, "learnedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "reinforcedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "factId", "workspaceId", "text", "pinned", "learnedFrom", "learnedAt", "reinforcedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "facts", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List memory facts.", "value": { "facts": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/number_one.memory.pin": { "post": { "operationId": "number_one_memory_pin", "summary": "Pin a memory fact so Number One reliably recalls it across conversations.", "x-trustvice-description-key": "actions.number_one.memory.pin.description", "tags": [ "number_one" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "factId": { "type": "string", "pattern": "^fact_[a-z0-9]{20,}$" } }, "required": [ "workspaceId", "factId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Pin a fact.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "factId": "fact_demo00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "factId": { "type": "string", "pattern": "^fact_[a-z0-9]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "text": { "type": "string" }, "pinned": { "type": "boolean" }, "learnedFrom": { "type": "string" }, "learnedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "reinforcedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "factId", "workspaceId", "text", "pinned", "learnedFrom", "learnedAt", "reinforcedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Pin a fact.", "value": { "factId": "fact_demo00000000000000000000", "workspaceId": "ws_DEMODEFAULT0000000000", "text": "Q3 audit is led by Foo & Co LLP", "pinned": true, "learnedFrom": "msg_abc", "learnedAt": "2026-05-22T12:00:00.000Z", "reinforcedAt": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/number_one.memory.unpin": { "post": { "operationId": "number_one_memory_unpin", "summary": "Unpin a memory fact.", "x-trustvice-description-key": "actions.number_one.memory.unpin.description", "tags": [ "number_one" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "factId": { "type": "string", "pattern": "^fact_[a-z0-9]{20,}$" } }, "required": [ "workspaceId", "factId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Unpin.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "factId": "fact_demo00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "factId": { "type": "string", "pattern": "^fact_[a-z0-9]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "text": { "type": "string" }, "pinned": { "type": "boolean" }, "learnedFrom": { "type": "string" }, "learnedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "reinforcedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "factId", "workspaceId", "text", "pinned", "learnedFrom", "learnedAt", "reinforcedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Unpin.", "value": { "factId": "fact_demo00000000000000000000", "workspaceId": "ws_DEMODEFAULT0000000000", "text": "Q3 audit is led by Foo & Co LLP", "pinned": false, "learnedFrom": "msg_abc", "learnedAt": "2026-05-22T12:00:00.000Z", "reinforcedAt": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/number_one.memory.erase": { "post": { "operationId": "number_one_memory_erase", "summary": "Permanently erase a memory fact (cannot be recovered).", "x-trustvice-description-key": "actions.number_one.memory.erase.description", "tags": [ "number_one" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "factId": { "type": "string", "pattern": "^fact_[a-z0-9]{20,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "factId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Erase a fact.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "factId": "fact_demo00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "erased": { "type": "boolean" } }, "required": [ "erased" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Erase a fact.", "value": { "erased": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/number_one.memory.cap.get": { "post": { "operationId": "number_one_memory_cap_get", "summary": "Get the memory cap for the workspace's tier (or unlimited if Infinite Memory add-on is active).", "x-trustvice-description-key": "actions.number_one.memory.cap.get.description", "tags": [ "number_one" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read memory cap.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "capFacts": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "number", "const": -1 } ] }, "usedFacts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "infiniteMemoryActive": { "type": "boolean" } }, "required": [ "capFacts", "usedFacts", "infiniteMemoryActive" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read memory cap.", "value": { "capFacts": 100, "usedFacts": 23, "infiniteMemoryActive": false } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.monitor.http.add": { "post": { "operationId": "entpoind_monitor_http_add", "summary": "Register a new HTTP monitor (1-minute minimum interval).", "x-trustvice-description-key": "actions.entpoind.monitor.http.add.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "url": { "type": "string", "format": "uri" }, "method": { "default": "GET", "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD" ] }, "intervalSeconds": { "default": 300, "type": "integer", "minimum": 30, "maximum": 86400 }, "expectedStatusCodes": { "default": [ 200 ], "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } }, "required": [ "workspaceId", "url" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Register HTTP monitor.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "url": "https://api.example.com/health", "intervalSeconds": 60 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "monitorId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "url": { "type": "string", "format": "uri" }, "method": { "default": "GET", "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD" ] }, "intervalSeconds": { "type": "integer", "minimum": 30, "maximum": 86400 }, "expectedStatusCodes": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "lastCheckAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "lastStatus": { "type": "string", "enum": [ "pass", "fail", "pending" ] } }, "required": [ "monitorId", "workspaceId", "url", "method", "intervalSeconds", "expectedStatusCodes", "enabled", "createdAt", "lastCheckAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Register HTTP monitor.", "value": { "monitorId": "01J9X4P9R7Z2C1A1F2A8VBJYM1", "workspaceId": "ws_DEMODEFAULT0000000000", "url": "https://api.example.com/health", "method": "GET", "intervalSeconds": 60, "expectedStatusCodes": [ 200 ], "enabled": true, "createdAt": "2026-05-22T12:00:00.000Z", "lastCheckAt": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "entpoind.monitor.create" ] }, { "OAuth2": [ "entpoind.monitor.create" ] }, { "WorkspaceApiKey": [ "entpoind.monitor.create" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.monitor.http.list": { "post": { "operationId": "entpoind_monitor_http_list", "summary": "List HTTP monitors in a workspace.", "x-trustvice-description-key": "actions.entpoind.monitor.http.list.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "enabledOnly": { "default": false, "type": "boolean" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List monitors.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "monitors": { "type": "array", "items": { "type": "object", "properties": { "monitorId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "url": { "type": "string", "format": "uri" }, "method": { "default": "GET", "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD" ] }, "intervalSeconds": { "type": "integer", "minimum": 30, "maximum": 86400 }, "expectedStatusCodes": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "lastCheckAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "lastStatus": { "type": "string", "enum": [ "pass", "fail", "pending" ] } }, "required": [ "monitorId", "workspaceId", "url", "method", "intervalSeconds", "expectedStatusCodes", "enabled", "createdAt", "lastCheckAt" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "monitors", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List monitors.", "value": { "monitors": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "entpoind.monitor.view" ] }, { "OAuth2": [ "entpoind.monitor.view" ] }, { "WorkspaceApiKey": [ "entpoind.monitor.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.monitor.http.run-now": { "post": { "operationId": "entpoind_monitor_http_run-now", "summary": "Run a monitor check immediately (bypasses the scheduled interval).", "x-trustvice-description-key": "actions.entpoind.monitor.http.run-now.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "monitorId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "required": [ "workspaceId", "monitorId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Run a monitor check now.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "monitorId": "01J9X4P9R7Z2C1A1F2A8VBJYM1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "statusCode": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "latencyMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "receiptId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "required": [ "statusCode", "latencyMs", "receiptId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Run a monitor check now.", "value": { "statusCode": 200, "latencyMs": 87, "receiptId": "01H8X4P9R7Z2C1A1F2A8VBJYV7" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "entpoind.monitor.create" ] }, { "OAuth2": [ "entpoind.monitor.create" ] }, { "WorkspaceApiKey": [ "entpoind.monitor.create" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.monitor.http.remove": { "post": { "operationId": "entpoind_monitor_http_remove", "summary": "Delete an HTTP monitor.", "x-trustvice-description-key": "actions.entpoind.monitor.http.remove.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "monitorId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "monitorId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete monitor.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "monitorId": "01J9X4P9R7Z2C1A1F2A8VBJYM1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete monitor.", "value": { "deleted": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "entpoind.monitor.delete" ] }, { "OAuth2": [ "entpoind.monitor.delete" ] }, { "WorkspaceApiKey": [ "entpoind.monitor.delete" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.watch.dns.add": { "post": { "operationId": "entpoind_watch_dns_add", "summary": "Register a DNS watch (detects record drift; signs every check as a receipt).", "x-trustvice-description-key": "actions.entpoind.watch.dns.add.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "domain": { "type": "string" }, "recordType": { "type": "string", "enum": [ "A", "AAAA", "CNAME", "MX", "TXT", "NS", "SRV", "CAA" ] }, "intervalSeconds": { "default": 3600, "type": "integer", "minimum": 60, "maximum": 86400 }, "pinExpectedValues": { "default": false, "type": "boolean" } }, "required": [ "workspaceId", "domain", "recordType" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Register DNS watch.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "domain": "example.com", "recordType": "A" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "dnsWatchId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "domain": { "type": "string" }, "recordType": { "type": "string", "enum": [ "A", "AAAA", "CNAME", "MX", "TXT", "NS", "SRV", "CAA" ] }, "expectedValuesHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "intervalSeconds": { "type": "integer", "minimum": 60, "maximum": 86400 }, "enabled": { "type": "boolean" } }, "required": [ "dnsWatchId", "workspaceId", "domain", "recordType", "intervalSeconds", "enabled" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Register DNS watch.", "value": { "dnsWatchId": "01J9X4P9R7Z2C1A1F2A8VBJYD1", "workspaceId": "ws_DEMODEFAULT0000000000", "domain": "example.com", "recordType": "A", "intervalSeconds": 3600, "enabled": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "entpoind.watch.create" ] }, { "OAuth2": [ "entpoind.watch.create" ] }, { "WorkspaceApiKey": [ "entpoind.watch.create" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.watch.dns.list": { "post": { "operationId": "entpoind_watch_dns_list", "summary": "List DNS watches in a workspace.", "x-trustvice-description-key": "actions.entpoind.watch.dns.list.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List DNS watches.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "watches": { "type": "array", "items": { "type": "object", "properties": { "dnsWatchId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "domain": { "type": "string" }, "recordType": { "type": "string", "enum": [ "A", "AAAA", "CNAME", "MX", "TXT", "NS", "SRV", "CAA" ] }, "expectedValuesHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "intervalSeconds": { "type": "integer", "minimum": 60, "maximum": 86400 }, "enabled": { "type": "boolean" } }, "required": [ "dnsWatchId", "workspaceId", "domain", "recordType", "intervalSeconds", "enabled" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "watches", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List DNS watches.", "value": { "watches": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "entpoind.watch.view" ] }, { "OAuth2": [ "entpoind.watch.view" ] }, { "WorkspaceApiKey": [ "entpoind.watch.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.watch.dns.remove": { "post": { "operationId": "entpoind_watch_dns_remove", "summary": "Delete a DNS watch.", "x-trustvice-description-key": "actions.entpoind.watch.dns.remove.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "dnsWatchId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "dnsWatchId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete DNS watch.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "dnsWatchId": "01J9X4P9R7Z2C1A1F2A8VBJYD1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete DNS watch.", "value": { "deleted": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "entpoind.watch.delete" ] }, { "OAuth2": [ "entpoind.watch.delete" ] }, { "WorkspaceApiKey": [ "entpoind.watch.delete" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.watch.tls.add": { "post": { "operationId": "entpoind_watch_tls_add", "summary": "Register a TLS certificate watch (detects cert changes; signs every check).", "x-trustvice-description-key": "actions.entpoind.watch.tls.add.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "host": { "type": "string" }, "port": { "default": 443, "type": "integer", "minimum": 1, "maximum": 65535 }, "intervalSeconds": { "default": 3600, "type": "integer", "minimum": 300, "maximum": 86400 }, "pinFingerprint": { "default": false, "type": "boolean" } }, "required": [ "workspaceId", "host" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Register TLS watch.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "host": "example.com" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tlsWatchId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "host": { "type": "string" }, "port": { "default": 443, "type": "integer", "minimum": 1, "maximum": 65535 }, "expectedFingerprintSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "intervalSeconds": { "type": "integer", "minimum": 60, "maximum": 86400 }, "enabled": { "type": "boolean" } }, "required": [ "tlsWatchId", "workspaceId", "host", "port", "intervalSeconds", "enabled" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Register TLS watch.", "value": { "tlsWatchId": "01J9X4P9R7Z2C1A1F2A8VBJYT1", "workspaceId": "ws_DEMODEFAULT0000000000", "host": "example.com", "port": 443, "intervalSeconds": 3600, "enabled": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "entpoind.watch.create" ] }, { "OAuth2": [ "entpoind.watch.create" ] }, { "WorkspaceApiKey": [ "entpoind.watch.create" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.watch.tls.list": { "post": { "operationId": "entpoind_watch_tls_list", "summary": "List TLS watches in a workspace.", "x-trustvice-description-key": "actions.entpoind.watch.tls.list.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List TLS watches.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "watches": { "type": "array", "items": { "type": "object", "properties": { "tlsWatchId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "host": { "type": "string" }, "port": { "default": 443, "type": "integer", "minimum": 1, "maximum": 65535 }, "expectedFingerprintSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "intervalSeconds": { "type": "integer", "minimum": 60, "maximum": 86400 }, "enabled": { "type": "boolean" } }, "required": [ "tlsWatchId", "workspaceId", "host", "port", "intervalSeconds", "enabled" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "watches", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List TLS watches.", "value": { "watches": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "entpoind.watch.view" ] }, { "OAuth2": [ "entpoind.watch.view" ] }, { "WorkspaceApiKey": [ "entpoind.watch.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.watch.tls.remove": { "post": { "operationId": "entpoind_watch_tls_remove", "summary": "Delete a TLS watch.", "x-trustvice-description-key": "actions.entpoind.watch.tls.remove.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "tlsWatchId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "tlsWatchId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete TLS watch.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "tlsWatchId": "01J9X4P9R7Z2C1A1F2A8VBJYT1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete TLS watch.", "value": { "deleted": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "entpoind.watch.delete" ] }, { "OAuth2": [ "entpoind.watch.delete" ] }, { "WorkspaceApiKey": [ "entpoind.watch.delete" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.receipt.list": { "post": { "operationId": "entpoind_receipt_list", "summary": "List Trustvice receipts for a workspace.", "x-trustvice-description-key": "actions.entpoind.receipt.list.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "kind": { "type": "string", "enum": [ "agent.call", "content.attest", "llm.attest", "commit.attest", "webhook.deliver", "monitor.http", "dns.watch", "tls.watch" ] }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List receipts.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "kind": "agent.call" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "receipts": { "type": "array", "items": { "type": "object", "properties": { "receiptId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "kind": { "type": "string", "enum": [ "agent.call", "content.attest", "llm.attest", "commit.attest", "webhook.deliver", "monitor.http", "dns.watch", "tls.watch" ] }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "signature": { "type": "string" }, "signatureKeyId": { "type": "string", "pattern": "^[a-z0-9-]{4,64}$" }, "body": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "receiptId", "workspaceId", "kind", "issuedAt", "signature", "signatureKeyId", "body" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "receipts", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List receipts.", "value": { "receipts": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "entpoind.receipt.view" ] }, { "OAuth2": [ "entpoind.receipt.view" ] }, { "WorkspaceApiKey": [ "entpoind.receipt.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.receipt.get": { "post": { "operationId": "entpoind_receipt_get", "summary": "Get a single receipt with full body.", "x-trustvice-description-key": "actions.entpoind.receipt.get.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "receiptId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "required": [ "workspaceId", "receiptId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read a receipt.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "receiptId": "01H8X4P9R7Z2C1A1F2A8VBJYV2" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "receiptId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "kind": { "type": "string", "enum": [ "agent.call", "content.attest", "llm.attest", "commit.attest", "webhook.deliver", "monitor.http", "dns.watch", "tls.watch" ] }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "signature": { "type": "string" }, "signatureKeyId": { "type": "string", "pattern": "^[a-z0-9-]{4,64}$" }, "body": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "receiptId", "workspaceId", "kind", "issuedAt", "signature", "signatureKeyId", "body" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read a receipt.", "value": { "receiptId": "01H8X4P9R7Z2C1A1F2A8VBJYV2", "workspaceId": "ws_DEMODEFAULT0000000000", "kind": "agent.call", "issuedAt": "2026-05-22T12:00:00.000Z", "signature": "...", "signatureKeyId": "entpoind-2026-q2-enam", "body": {} } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "entpoind.receipt.view" ] }, { "OAuth2": [ "entpoind.receipt.view" ] }, { "WorkspaceApiKey": [ "entpoind.receipt.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.receipt.verify": { "post": { "operationId": "entpoind_receipt_verify", "summary": "Verify a receipt's Ed25519 signature against the published public key. Cannot be disabled.", "x-trustvice-description-key": "actions.entpoind.receipt.verify.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "receipt": { "type": "object", "properties": { "receiptId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "kind": { "type": "string", "enum": [ "agent.call", "content.attest", "llm.attest", "commit.attest", "webhook.deliver", "monitor.http", "dns.watch", "tls.watch" ] }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "signature": { "type": "string" }, "signatureKeyId": { "type": "string", "pattern": "^[a-z0-9-]{4,64}$" }, "body": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "receiptId", "workspaceId", "kind", "issuedAt", "signature", "signatureKeyId", "body" ], "additionalProperties": {} } }, "required": [ "receipt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify a receipt.", "value": { "receipt": { "receiptId": "01H8X4P9R7Z2C1A1F2A8VBJYV2", "workspaceId": "ws_DEMODEFAULT0000000000", "kind": "agent.call", "issuedAt": "2026-05-22T12:00:00.000Z", "signature": "...", "signatureKeyId": "entpoind-2026-q2-enam", "body": {} } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "signedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "signatureKeyId": { "type": "string" } }, "required": [ "ok", "signedAt", "signatureKeyId" ], "additionalProperties": {} }, { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "reason": { "type": "string", "enum": [ "bad_signature", "unknown_key", "malformed_envelope" ] } }, "required": [ "ok", "reason" ], "additionalProperties": {} } ] }, "examples": { "example_0": { "summary": "Verify a receipt.", "value": { "ok": true, "signedAt": "2026-05-22T12:00:00.000Z", "signatureKeyId": "thLmyHDzi6rkbTb0KkPzmA" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.usage.current": { "post": { "operationId": "entpoind_usage_current", "summary": "Get current-period Trustvice Receipts usage for a workspace (calls per primitive + budget consumed).", "x-trustvice-description-key": "actions.entpoind.usage.current.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read current usage.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "totalCalls": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "perPrimitive": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "monthlyAllowance": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "periodEnd": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "totalCalls", "perPrimitive", "monthlyAllowance", "periodEnd" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read current usage.", "value": { "totalCalls": 12345, "perPrimitive": { "agent.call": 10000, "content.attest": 2345 }, "monthlyAllowance": 100000, "periodEnd": "2026-06-01T00:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "entpoind.usage.view" ] }, { "OAuth2": [ "entpoind.usage.view" ] }, { "WorkspaceApiKey": [ "entpoind.usage.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.usage.historical": { "post": { "operationId": "entpoind_usage_historical", "summary": "Get historical Trustvice Receipts usage (per-day breakdown for a date range).", "x-trustvice-description-key": "actions.entpoind.usage.historical.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "until": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "workspaceId", "since" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read historical usage.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "since": "2026-05-01T00:00:00.000Z" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "daily": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "totalCalls": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "perPrimitive": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "required": [ "date", "totalCalls", "perPrimitive" ], "additionalProperties": false } } }, "required": [ "daily" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read historical usage.", "value": { "daily": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "entpoind.usage.view" ] }, { "OAuth2": [ "entpoind.usage.view" ] }, { "WorkspaceApiKey": [ "entpoind.usage.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.subscription.get": { "post": { "operationId": "entpoind_subscription_get", "summary": "Get workspace Trustvice Receipts subscription state.", "x-trustvice-description-key": "actions.entpoind.subscription.get.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read subscription state.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "enabled": { "type": "boolean" }, "tier": { "type": [ "string", "null" ] }, "abuseStatus": { "type": "string" }, "autoOverageEnabled": { "type": "boolean" }, "billingMode": { "type": "string" } }, "required": [ "enabled", "tier", "abuseStatus", "autoOverageEnabled", "billingMode" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read subscription state.", "value": { "enabled": true, "tier": "team", "abuseStatus": "clean", "autoOverageEnabled": true, "billingMode": "combined" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "entpoind.subscription.view" ] }, { "OAuth2": [ "entpoind.subscription.view" ] }, { "WorkspaceApiKey": [ "entpoind.subscription.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.subscription.cancel": { "post": { "operationId": "entpoind_subscription_cancel", "summary": "Cancel the Trustvice Receipts subscription at the next billing period. Workspace's existing receipts remain accessible.", "x-trustvice-description-key": "actions.entpoind.subscription.cancel.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "reason" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Cancel Trustvice Receipts subscription.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "reason": "Migrating to alternative receipt provider" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "canceled": { "type": "boolean" }, "effectiveAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "canceled", "effectiveAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Cancel Trustvice Receipts subscription.", "value": { "canceled": true, "effectiveAt": "2026-06-22T00:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "billing.change_plan" ] }, { "OAuth2": [ "billing.change_plan" ] }, { "WorkspaceApiKey": [ "billing.change_plan" ] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "billing", "x-trustvice-audit-kind": "plan.changed", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.abuse-status.get": { "post": { "operationId": "entpoind_abuse-status_get", "summary": "Get the current Trustvice Receipts abuse status for a workspace.", "x-trustvice-description-key": "actions.entpoind.abuse-status.get.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read abuse status.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "status": { "type": "string", "enum": [ "clean", "flagged", "under_review", "suspended" ] }, "flaggedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "suspendedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "reason": { "type": [ "string", "null" ] }, "latestAppeal": { "anyOf": [ { "type": "object", "properties": { "appealId": { "type": "string" }, "submittedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "status": { "type": "string", "enum": [ "pending", "accepted", "rejected" ] } }, "required": [ "appealId", "submittedAt", "status" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "workspaceId", "status", "flaggedAt", "suspendedAt", "reason", "latestAppeal" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read abuse status.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "status": "clean", "flaggedAt": null, "suspendedAt": null, "reason": null, "latestAppeal": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "entpoind.abuse.view" ] }, { "OAuth2": [ "entpoind.abuse.view" ] }, { "WorkspaceApiKey": [ "entpoind.abuse.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.abuse-status.appeal": { "post": { "operationId": "entpoind_abuse-status_appeal", "summary": "Submit an appeal against an abuse-status flag or suspension.", "x-trustvice-description-key": "actions.entpoind.abuse-status.appeal.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "appealText": { "type": "string", "minLength": 50, "maxLength": 5000 } }, "required": [ "workspaceId", "appealText" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Submit abuse appeal.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "appealText": "Our agent's traffic spike was a planned load test; here are the details + timestamps + IP CIDRs ..." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appealId": { "type": "string" }, "submittedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "appealId", "submittedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Submit abuse appeal.", "value": { "appealId": "app_abc", "submittedAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "entpoind.abuse.appeal" ] }, { "OAuth2": [ "entpoind.abuse.appeal" ] }, { "WorkspaceApiKey": [ "entpoind.abuse.appeal" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.abuse-status.appeal.list": { "post": { "operationId": "entpoind_abuse-status_appeal_list", "summary": "List this workspace's abuse appeals and their decisions.", "x-trustvice-description-key": "actions.entpoind.abuse-status.appeal.list.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read this workspace's appeals.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "appeals": { "type": "array", "items": { "type": "object", "properties": { "appealId": { "type": "string" }, "submittedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "status": { "type": "string", "enum": [ "pending", "accepted", "rejected" ] }, "appealText": { "type": "string" } }, "required": [ "appealId", "submittedAt", "status", "appealText" ], "additionalProperties": false } } }, "required": [ "workspaceId", "appeals" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read this workspace's appeals.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "appeals": [ { "appealId": "app_abc", "appealText": "Our agent's traffic spike was a planned load test ...", "submittedAt": "2026-05-22T12:00:00.000Z", "status": "pending" } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "entpoind.abuse.view" ] }, { "OAuth2": [ "entpoind.abuse.view" ] }, { "WorkspaceApiKey": [ "entpoind.abuse.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.signing-key.get": { "post": { "operationId": "entpoind_signing-key_get", "summary": "Get the current active Trustvice Receipts signing key id for the workspace's jurisdiction.", "x-trustvice-description-key": "actions.entpoind.signing-key.get.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read signing key id.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "signingKeyId": { "type": "string", "pattern": "^[a-z0-9-]{4,64}$" }, "jurisdiction": { "type": "string", "enum": [ "WEUR", "ENAM" ] }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "publishedAtUrl": { "type": "string", "format": "uri" } }, "required": [ "signingKeyId", "jurisdiction", "issuedAt", "expiresAt", "publishedAtUrl" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read signing key id.", "value": { "signingKeyId": "entpoind-2026-q2-enam", "jurisdiction": "ENAM", "issuedAt": "2026-04-01T00:00:00.000Z", "expiresAt": "2027-04-01T00:00:00.000Z", "publishedAtUrl": "https://api.trustvice.com/.well-known/entpoind-keys.json" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "entpoind.subscription.view" ] }, { "OAuth2": [ "entpoind.subscription.view" ] }, { "WorkspaceApiKey": [ "entpoind.subscription.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.signing-key.list": { "post": { "operationId": "entpoind_signing-key_list", "summary": "List all signing keys (active + historical) usable to verify the workspace's receipts.", "x-trustvice-description-key": "actions.entpoind.signing-key.list.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List signing keys.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "signingKeyId": { "type": "string", "pattern": "^[a-z0-9-]{4,64}$" }, "jurisdiction": { "type": "string", "enum": [ "WEUR", "ENAM" ] }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "active": { "type": "boolean" } }, "required": [ "signingKeyId", "jurisdiction", "issuedAt", "expiresAt", "active" ], "additionalProperties": false } } }, "required": [ "keys" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List signing keys.", "value": { "keys": [ { "signingKeyId": "entpoind-2026-q2-enam", "jurisdiction": "ENAM", "issuedAt": "2026-04-01T00:00:00.000Z", "expiresAt": "2027-04-01T00:00:00.000Z", "active": true } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "entpoind.subscription.view" ] }, { "OAuth2": [ "entpoind.subscription.view" ] }, { "WorkspaceApiKey": [ "entpoind.subscription.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.signing-key.rotate-request.list": { "post": { "operationId": "entpoind_signing-key_rotate-request_list", "summary": "List this workspace's signing-key rotation requests and their outcomes.", "x-trustvice-description-key": "actions.entpoind.signing-key.rotate-request.list.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read this workspace's rotation requests.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "requests": { "type": "array", "items": { "type": "object", "properties": { "requestId": { "type": "string" }, "reason": { "type": "string" }, "status": { "type": "string", "enum": [ "requested", "fulfilled", "declined" ] }, "requestedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "estimatedRotationAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "fulfilledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "requestId", "reason", "status", "requestedAt", "estimatedRotationAt", "fulfilledAt" ], "additionalProperties": false } } }, "required": [ "workspaceId", "requests" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read this workspace's rotation requests.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "requests": [ { "requestId": "rot_abc", "reason": "Q4 scheduled rotation per our internal policy", "status": "requested", "requestedAt": "2026-05-18T00:00:00.000Z", "estimatedRotationAt": "2026-06-01T00:00:00.000Z", "fulfilledAt": null } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "entpoind.subscription.view" ] }, { "OAuth2": [ "entpoind.subscription.view" ] }, { "WorkspaceApiKey": [ "entpoind.subscription.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.signing-key.public.get": { "post": { "operationId": "entpoind_signing-key_public_get", "summary": "Get the public-key JWK for a specific signing key id (for offline verification).", "x-trustvice-description-key": "actions.entpoind.signing-key.public.get.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "signingKeyId": { "type": "string", "pattern": "^[a-z0-9-]{4,64}$" } }, "required": [ "signingKeyId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read public key JWK.", "value": { "signingKeyId": "entpoind-2026-q2-enam" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "jwk": {}, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "jwk", "issuedAt", "expiresAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read public key JWK.", "value": { "jwk": { "kty": "OKP", "crv": "Ed25519", "x": "..." }, "issuedAt": "2026-04-01T00:00:00.000Z", "expiresAt": "2027-04-01T00:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.status.get": { "post": { "operationId": "entpoind_status_get", "summary": "Get the Trustvice Receipts subsystem health (per-jurisdiction Worker uptime, per-primitive error rate, last self-attestation receipt).", "x-trustvice-description-key": "actions.entpoind.status.get.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read Trustvice Receipts health.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "jurisdictions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "WEUR", "ENAM" ] }, "uptimePercent": { "type": "number", "minimum": 0, "maximum": 100 }, "errorRatePercent": { "type": "number", "minimum": 0, "maximum": 100 }, "lastSelfAttestationAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "id", "uptimePercent", "errorRatePercent", "lastSelfAttestationAt" ], "additionalProperties": false } } }, "required": [ "jurisdictions" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read Trustvice Receipts health.", "value": { "jurisdictions": [ { "id": "ENAM", "uptimePercent": 99.95, "errorRatePercent": 0.02, "lastSelfAttestationAt": "2026-05-22T11:00:00.000Z" } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "entpoind.subscription.view" ] }, { "OAuth2": [ "entpoind.subscription.view" ] }, { "WorkspaceApiKey": [ "entpoind.subscription.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.attestation-feed.get": { "post": { "operationId": "entpoind_attestation-feed_get", "summary": "Get the daily Trustvice Receipts self-attestation receipt feed (Trustvice attesting to its own platform integrity).", "x-trustvice-description-key": "actions.entpoind.attestation-feed.get.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read self-attestation feed.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "attestations": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "receiptId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "signature": { "type": "string" } }, "required": [ "date", "receiptId", "signature" ], "additionalProperties": false } } }, "required": [ "attestations" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read self-attestation feed.", "value": { "attestations": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.compliance.regimes.list": { "post": { "operationId": "entpoind_compliance_regimes_list", "summary": "List every compliance regime the registry models, with what is in force today and what is not yet.", "x-trustvice-description-key": "actions.entpoind.compliance.regimes.list.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read the regime catalogue.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "asOf": { "type": "string" }, "regimes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "citation": { "type": "string" }, "jurisdiction": { "type": "string" }, "appliesFrom": { "type": [ "string", "null" ] }, "expiresOn": { "type": [ "string", "null" ] }, "inForceToday": { "type": "boolean" }, "obligationKinds": { "type": "array", "items": { "type": "string" } }, "unsettled": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "label", "citation", "jurisdiction", "appliesFrom", "expiresOn", "inForceToday", "obligationKinds", "unsettled" ], "additionalProperties": {} } }, "obligationKinds": { "type": "array", "items": { "type": "string" } }, "evidencePrimitives": { "type": "array", "items": { "type": "string" } } }, "required": [ "asOf", "regimes", "obligationKinds", "evidencePrimitives" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read the regime catalogue.", "value": { "asOf": "2026-08-11", "regimes": [], "obligationKinds": [], "evidencePrimitives": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.compliance.obligations.get": { "post": { "operationId": "entpoind_compliance_obligations_get", "summary": "Given a declared position, return the merged duty list across every governing regime — strictest timing wins, and regimes that wanted it looser are recorded.", "x-trustvice-description-key": "actions.entpoind.compliance.obligations.get.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "regimes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "operatorRegisteredIn": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "audienceRegions": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 32 } }, "context": { "type": "string", "minLength": 1, "maxLength": 64 }, "employeeCount": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "monthlyUsers": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "asOf": { "type": "string", "minLength": 4, "maxLength": 32 }, "primitive": { "type": "string", "minLength": 1, "maxLength": 64 } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Ask what an EU-facing operator owes.", "value": { "operatorRegisteredIn": [ "eu-ai-act" ], "audienceRegions": [ "eu" ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "selection": { "type": "object", "properties": { "regimes": { "type": "array", "items": { "type": "string" } }, "asOf": { "type": [ "string", "null" ] }, "notYetInForce": { "type": "array", "items": { "type": "string" } }, "expired": { "type": "array", "items": { "type": "string" } }, "inForceNotYetEnforced": { "type": "array", "items": { "type": "string" } }, "basis": { "type": "string" }, "unsettled": { "type": "array", "items": { "type": "string" } }, "dutyFallsOnCustomerOnly": { "type": "boolean" } }, "required": [ "regimes", "asOf", "notYetInForce", "expired", "inForceNotYetEnforced", "basis", "unsettled", "dutyFallsOnCustomerOnly" ], "additionalProperties": {} }, "obligations": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "timing": { "type": "string" }, "authority": { "type": "string" }, "requiresFirstPartyDelivery": { "type": "boolean" }, "hasNonStatutoryContributor": { "type": "boolean" }, "contributors": { "type": "array", "items": { "type": "object", "properties": { "regime": { "type": "string" }, "provision": { "type": "string" } }, "required": [ "regime", "provision" ], "additionalProperties": {} } }, "loosenedFrom": { "type": "array", "items": { "type": "string" } }, "basis": { "type": "string" } }, "required": [ "kind", "timing", "authority", "requiresFirstPartyDelivery", "hasNonStatutoryContributor", "contributors", "loosenedFrom", "basis" ], "additionalProperties": {} } }, "requiresFirstPartyDelivery": { "type": "boolean" }, "advisory": { "type": "boolean" } }, "required": [ "selection", "obligations", "requiresFirstPartyDelivery", "advisory" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Ask what an EU-facing operator owes.", "value": { "selection": { "regimes": [ "eu-ai-act" ], "asOf": null, "notYetInForce": [], "expired": [], "inForceNotYetEnforced": [], "basis": "", "unsettled": [], "dutyFallsOnCustomerOnly": true }, "obligations": [], "requiresFirstPartyDelivery": false, "advisory": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/entpoind.compliance.posture.get": { "post": { "operationId": "entpoind_compliance_posture_get", "summary": "Conformity Live: which clauses the workspace's own signed receipts actually discharge, each with the receipt ids behind it.", "x-trustvice-description-key": "actions.entpoind.compliance.posture.get.description", "tags": [ "entpoind" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "regimes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "operatorRegisteredIn": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "audienceRegions": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 32 } }, "context": { "type": "string", "minLength": 1, "maxLength": 64 }, "employeeCount": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "monthlyUsers": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "asOf": { "type": "string", "minLength": 4, "maxLength": 32 } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Ask what the workspace's receipts actually discharge.", "value": { "operatorRegisteredIn": [ "eu-ai-act" ], "audienceRegions": [ "eu" ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "evaluatedAt": { "type": "string" }, "regimes": { "type": "array", "items": { "type": "string" } }, "selectionBasis": { "type": "string" }, "clauses": { "type": "array", "items": { "type": "object", "properties": { "regimeId": { "type": "string" }, "regime": { "type": "string" }, "provision": { "type": "string" }, "kind": { "type": "string" }, "timing": { "type": "string" }, "status": { "type": "string", "enum": [ "satisfied", "unsatisfied", "expired", "not_evidenced_here", "not_yet_applicable", "indeterminate" ] }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "receiptId": { "type": "string" }, "primitive": { "type": "string" }, "issuedAt": { "type": "string" } }, "required": [ "receiptId", "primitive", "issuedAt" ], "additionalProperties": {} } }, "reason": { "type": "string" } }, "required": [ "regimeId", "regime", "provision", "kind", "timing", "status", "evidence", "reason" ], "additionalProperties": {} } }, "tally": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "coverage": { "type": [ "number", "null" ] }, "evidenceComplete": { "type": "boolean" }, "receiptsRead": { "type": "number" }, "complianceReceiptsUsed": { "type": "number" }, "notes": { "type": "array", "items": { "type": "string" } }, "advisory": { "type": "string" } }, "required": [ "evaluatedAt", "regimes", "selectionBasis", "clauses", "tally", "coverage", "evidenceComplete", "receiptsRead", "complianceReceiptsUsed", "notes", "advisory" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Ask what the workspace's receipts actually discharge.", "value": { "evaluatedAt": "2026-09-04T00:00:00.000Z", "regimes": [ "eu-ai-act" ], "selectionBasis": "", "clauses": [], "tally": {}, "coverage": null, "evidenceComplete": true, "receiptsRead": 0, "complianceReceiptsUsed": 0, "notes": [], "advisory": "Advisory." } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/privacy.dsr.submit": { "post": { "operationId": "privacy_dsr_submit", "summary": "Submit a data-subject request (GDPR / CCPA). Cannot be disabled — statutory right.", "x-trustvice-description-key": "actions.privacy.dsr.submit.description", "tags": [ "privacy" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "kind": { "type": "string", "enum": [ "access", "erasure", "restriction", "portability", "objection", "rectification" ] }, "subjectEmail": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 }, "contactEmail": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "kind", "subjectEmail" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "File an Art. 15 access request.", "value": { "kind": "access", "subjectEmail": "alice@example.com" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "dsrId": { "type": "string" }, "kind": { "type": "string", "enum": [ "access", "erasure", "restriction", "portability", "objection", "rectification" ] }, "subjectEmail": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "submittedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "status": { "type": "string", "enum": [ "received", "verifying-identity", "in-progress", "completed", "rejected" ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "receiptUrl": { "type": "string", "format": "uri" } }, "required": [ "dsrId", "kind", "subjectEmail", "submittedAt", "status", "completedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "File an Art. 15 access request.", "value": { "dsrId": "dsr_abc", "kind": "access", "subjectEmail": "alice@example.com", "submittedAt": "2026-05-22T12:00:00.000Z", "status": "received", "completedAt": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "admin.action", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/privacy.dsr.status": { "post": { "operationId": "privacy_dsr_status", "summary": "Check status of a submitted DSR. Cannot be disabled — statutory right.", "x-trustvice-description-key": "actions.privacy.dsr.status.description", "tags": [ "privacy" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "dsrId": { "type": "string" } }, "required": [ "dsrId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Status check.", "value": { "dsrId": "dsr_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "dsrId": { "type": "string" }, "kind": { "type": "string", "enum": [ "access", "erasure", "restriction", "portability", "objection", "rectification" ] }, "subjectEmail": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "submittedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "status": { "type": "string", "enum": [ "received", "verifying-identity", "in-progress", "completed", "rejected" ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "receiptUrl": { "type": "string", "format": "uri" } }, "required": [ "dsrId", "kind", "subjectEmail", "submittedAt", "status", "completedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Status check.", "value": { "dsrId": "dsr_abc", "kind": "access", "subjectEmail": "alice@example.com", "submittedAt": "2026-05-22T12:00:00.000Z", "status": "in-progress", "completedAt": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/privacy.dsr.list": { "post": { "operationId": "privacy_dsr_list", "summary": "List all DSRs filed for this account / workspace.", "x-trustvice-description-key": "actions.privacy.dsr.list.description", "tags": [ "privacy" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "status": { "type": "string", "enum": [ "received", "verifying-identity", "in-progress", "completed", "rejected" ] } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "List your filed DSRs.", "value": { "limit": 25 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "dsrs": { "type": "array", "items": { "type": "object", "properties": { "dsrId": { "type": "string" }, "kind": { "type": "string", "enum": [ "access", "erasure", "restriction", "portability", "objection", "rectification" ] }, "subjectEmail": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "submittedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "status": { "type": "string", "enum": [ "received", "verifying-identity", "in-progress", "completed", "rejected" ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "receiptUrl": { "type": "string", "format": "uri" } }, "required": [ "dsrId", "kind", "subjectEmail", "submittedAt", "status", "completedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "dsrs", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List your filed DSRs.", "value": { "dsrs": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/privacy.export.request": { "post": { "operationId": "privacy_export_request", "summary": "Request a personal-data export (GDPR Art. 20 — data portability). Cannot be disabled.", "x-trustvice-description-key": "actions.privacy.export.request.description", "tags": [ "privacy" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "format": { "default": "portable-archive", "type": "string", "enum": [ "json", "csv", "portable-archive" ] } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Art. 20 portability export.", "value": { "format": "portable-archive" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "exportId": { "type": "string" }, "estimatedReadyAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "format": { "type": "string" } }, "required": [ "exportId", "estimatedReadyAt", "format" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Art. 20 portability export.", "value": { "exportId": "exp_pii_abc", "estimatedReadyAt": "2026-05-22T13:00:00.000Z", "format": "portable-archive" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": "export.requested", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/privacy.export.download": { "post": { "operationId": "privacy_export_download", "summary": "Get a signed download URL for a completed personal-data export.", "x-trustvice-description-key": "actions.privacy.export.download.description", "tags": [ "privacy" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "exportId": { "type": "string" } }, "required": [ "exportId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Download your export.", "value": { "exportId": "exp_pii_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "sha256": { "type": "string" } }, "required": [ "url", "expiresAt", "sha256" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Download your export.", "value": { "url": "https://r2.trustvice.com/exports/abc", "expiresAt": "2026-05-22T13:30:00.000Z", "sha256": "abcd..." } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "export.completed", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/privacy.receipt.get": { "post": { "operationId": "privacy_receipt_get", "summary": "Get the Ed25519-signed completion receipt for a DSR (verifiable offline).", "x-trustvice-description-key": "actions.privacy.receipt.get.description", "tags": [ "privacy" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "dsrId": { "type": "string" } }, "required": [ "dsrId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Receipt for offline verification.", "value": { "dsrId": "dsr_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "receipt": {}, "signingKeyId": { "type": "string" }, "publicKeyUrl": { "type": "string", "format": "uri" } }, "required": [ "receipt", "signingKeyId", "publicKeyUrl" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Receipt for offline verification.", "value": { "receipt": {}, "signingKeyId": "privacy-2026-q2-enam", "publicKeyUrl": "https://api.trustvice.com/.well-known/privacy-receipt-keys.json" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/privacy.receipt.verify": { "post": { "operationId": "privacy_receipt_verify", "summary": "Verify a DSR receipt's Ed25519 signature + OTS proof against published public keys.", "x-trustvice-description-key": "actions.privacy.receipt.verify.description", "tags": [ "privacy" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "receipt": {} }, "required": [ "receipt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify offline-style.", "value": { "receipt": {} } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "valid": { "type": "boolean" }, "signatureValid": { "type": "boolean" }, "otsValid": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "valid", "signatureValid", "otsValid", "errors" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify offline-style.", "value": { "valid": true, "signatureValid": true, "otsValid": true, "errors": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/privacy.subject-rights.list": { "post": { "operationId": "privacy_subject-rights_list", "summary": "List the data-subject rights Trustvice honours (GDPR, CCPA, LGPD) + the legal references.", "x-trustvice-description-key": "actions.privacy.subject-rights.list.description", "tags": [ "privacy" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read supported rights.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "rights": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "access", "erasure", "restriction", "portability", "objection", "rectification" ] }, "legalRef": { "type": "string" }, "description": { "type": "string" } }, "required": [ "kind", "legalRef", "description" ], "additionalProperties": false } } }, "required": [ "rights" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read supported rights.", "value": { "rights": [ { "kind": "access", "legalRef": "GDPR Art. 15", "description": "Right to access your personal data." } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/support.tickets.list": { "post": { "operationId": "support_tickets_list", "summary": "List your support tickets.", "x-trustvice-description-key": "actions.support.tickets.list.description", "tags": [ "support" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "status": { "type": "string", "enum": [ "open", "in-progress", "waiting-customer", "resolved", "closed" ] } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "List your tickets.", "value": { "limit": 25 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tickets": { "type": "array", "items": { "type": "object", "properties": { "ticketId": { "type": "string" }, "subject": { "type": "string", "minLength": 1, "maxLength": 80 }, "status": { "type": "string", "enum": [ "open", "in-progress", "waiting-customer", "resolved", "closed" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "resolvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "ticketId", "subject", "status", "priority", "createdAt", "updatedAt", "resolvedAt" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "tickets", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List your tickets.", "value": { "tickets": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/support.tickets.create": { "post": { "operationId": "support_tickets_create", "summary": "Open a new support ticket.", "x-trustvice-description-key": "actions.support.tickets.create.description", "tags": [ "support" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 80 }, "body": { "type": "string", "minLength": 20, "maxLength": 50000 }, "priority": { "default": "normal", "type": "string", "enum": [ "low", "normal", "high", "urgent" ] } }, "required": [ "subject", "body" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Open a new ticket.", "value": { "subject": "Issue with Trustvice receipt verification", "body": "Hi — I'm seeing a signature_invalid error when verifying receipts from workspace ws_X. Could you take a look?", "priority": "normal" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ticketId": { "type": "string" }, "subject": { "type": "string", "minLength": 1, "maxLength": 80 }, "status": { "type": "string", "enum": [ "open", "in-progress", "waiting-customer", "resolved", "closed" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "resolvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "ticketId", "subject", "status", "priority", "createdAt", "updatedAt", "resolvedAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Open a new ticket.", "value": { "ticketId": "tkt_abc", "subject": "Issue with Trustvice receipt verification", "status": "open", "priority": "normal", "createdAt": "2026-05-22T12:00:00.000Z", "updatedAt": "2026-05-22T12:00:00.000Z", "resolvedAt": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/support.tickets.get": { "post": { "operationId": "support_tickets_get", "summary": "Get a ticket's details + reply thread.", "x-trustvice-description-key": "actions.support.tickets.get.description", "tags": [ "support" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ticketId": { "type": "string" } }, "required": [ "ticketId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read ticket + thread.", "value": { "ticketId": "tkt_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ticket": { "type": "object", "properties": { "ticketId": { "type": "string" }, "subject": { "type": "string", "minLength": 1, "maxLength": 80 }, "status": { "type": "string", "enum": [ "open", "in-progress", "waiting-customer", "resolved", "closed" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "resolvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "ticketId", "subject", "status", "priority", "createdAt", "updatedAt", "resolvedAt" ], "additionalProperties": {} }, "replies": { "type": "array", "items": { "type": "object", "properties": { "replyId": { "type": "string" }, "ticketId": { "type": "string" }, "author": { "type": "string", "enum": [ "customer", "trustvice-support" ] }, "body": { "type": "string", "maxLength": 50000 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "replyId", "ticketId", "author", "body", "createdAt" ], "additionalProperties": false } } }, "required": [ "ticket", "replies" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read ticket + thread.", "value": { "ticket": { "ticketId": "tkt_abc", "subject": "Issue", "status": "open", "priority": "normal", "createdAt": "2026-05-22T12:00:00.000Z", "updatedAt": "2026-05-22T12:00:00.000Z", "resolvedAt": null }, "replies": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/support.tickets.reply": { "post": { "operationId": "support_tickets_reply", "summary": "Post a reply to a ticket.", "x-trustvice-description-key": "actions.support.tickets.reply.description", "tags": [ "support" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ticketId": { "type": "string" }, "body": { "type": "string", "minLength": 1, "maxLength": 50000 } }, "required": [ "ticketId", "body" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Reply to a ticket.", "value": { "ticketId": "tkt_abc", "body": "Thanks — here's the receipt hash from the failing verify call." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "replyId": { "type": "string" }, "ticketId": { "type": "string" }, "author": { "type": "string", "enum": [ "customer", "trustvice-support" ] }, "body": { "type": "string", "maxLength": 50000 }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "replyId", "ticketId", "author", "body", "createdAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Reply to a ticket.", "value": { "replyId": "rep_abc", "ticketId": "tkt_abc", "author": "customer", "body": "Thanks — here's the receipt hash from the failing verify call.", "createdAt": "2026-05-22T12:05:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/support.tickets.close": { "post": { "operationId": "support_tickets_close", "summary": "Close a ticket (optionally with a reason).", "x-trustvice-description-key": "actions.support.tickets.close.description", "tags": [ "support" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ticketId": { "type": "string" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "ticketId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Close a ticket.", "value": { "ticketId": "tkt_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ticketId": { "type": "string" }, "subject": { "type": "string", "minLength": 1, "maxLength": 80 }, "status": { "type": "string", "enum": [ "open", "in-progress", "waiting-customer", "resolved", "closed" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "resolvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "ticketId", "subject", "status", "priority", "createdAt", "updatedAt", "resolvedAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Close a ticket.", "value": { "ticketId": "tkt_abc", "subject": "Issue", "status": "closed", "priority": "normal", "createdAt": "2026-05-22T12:00:00.000Z", "updatedAt": "2026-05-22T12:10:00.000Z", "resolvedAt": "2026-05-22T12:10:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/support.satisfaction.rate": { "post": { "operationId": "support_satisfaction_rate", "summary": "Rate the support experience after a ticket closes.", "x-trustvice-description-key": "actions.support.satisfaction.rate.description", "tags": [ "support" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ticketId": { "type": "string" }, "speed": { "type": "integer", "minimum": 1, "maximum": 5 }, "knowledge": { "type": "integer", "minimum": 1, "maximum": 5 }, "friendliness": { "type": "integer", "minimum": 1, "maximum": 5 }, "followThrough": { "type": "integer", "minimum": 1, "maximum": 5 }, "outcome": { "type": "integer", "minimum": 1, "maximum": 5 }, "comment": { "type": "string", "maxLength": 500 } }, "required": [ "ticketId", "speed", "knowledge", "friendliness", "followThrough", "outcome" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Rate all five dimensions 5/5. Any dimension <= 2 sets rebuildTriggered.", "value": { "ticketId": "tkt_abc", "speed": 5, "knowledge": 5, "friendliness": 5, "followThrough": 5, "outcome": 5 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "recorded": { "type": "boolean" }, "rebuildTriggered": { "type": "boolean" } }, "required": [ "recorded", "rebuildTriggered" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Rate all five dimensions 5/5. Any dimension <= 2 sets rebuildTriggered.", "value": { "recorded": true, "rebuildTriggered": false } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/discovery.capabilities.get": { "post": { "operationId": "discovery_capabilities_get", "summary": "Get the full action registry catalogue (machine-readable). Same content as `/v1/actions.json`.", "x-trustvice-description-key": "actions.discovery.capabilities.get.description", "tags": [ "discovery" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "domainFilter": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Discover all actions.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "actions": { "type": "array", "items": {} }, "generatedAt": { "type": "string" } }, "required": [ "actions", "generatedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Discover all actions.", "value": { "actions": [], "generatedAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/discovery.version.get": { "post": { "operationId": "discovery_version_get", "summary": "Get the platform version + contracts package version + supported MCP / OpenAPI spec versions.", "x-trustvice-description-key": "actions.discovery.version.get.description", "tags": [ "discovery" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read all version + spec info.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "platform": { "type": "string" }, "contracts": { "type": "string" }, "mcpSpecVersion": { "type": "string" }, "openapiVersion": { "type": "string" }, "asyncapiVersion": { "type": "string" } }, "required": [ "platform", "contracts", "mcpSpecVersion", "openapiVersion", "asyncapiVersion" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read all version + spec info.", "value": { "platform": "trustvice/1.0.0", "contracts": "0.1.23", "mcpSpecVersion": "2025-06-18", "openapiVersion": "3.1.0", "asyncapiVersion": "3.0.0" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/discovery.schema.get": { "post": { "operationId": "discovery_schema_get", "summary": "Get the JSON Schema for a specific action's input or output.", "x-trustvice-description-key": "actions.discovery.schema.get.description", "tags": [ "discovery" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "actionId": { "type": "string" }, "shape": { "type": "string", "enum": [ "input", "output" ] } }, "required": [ "actionId", "shape" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Get an action's JSON Schema.", "value": { "actionId": "workspace.create", "shape": "input" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "schema": {} }, "required": [ "schema" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Get an action's JSON Schema.", "value": { "schema": {} } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/discovery.locales.list": { "post": { "operationId": "discovery_locales_list", "summary": "List supported user-facing locales.", "x-trustvice-description-key": "actions.discovery.locales.list.description", "tags": [ "discovery" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Six supported locales.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "locales": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "en", "es", "fr", "de", "de-du", "zh" ] }, "name": { "type": "string" }, "nativeName": { "type": "string" } }, "required": [ "id", "name", "nativeName" ], "additionalProperties": false } } }, "required": [ "locales" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Six supported locales.", "value": { "locales": [ { "id": "en", "name": "English", "nativeName": "English" }, { "id": "de", "name": "German", "nativeName": "Deutsch" } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/discovery.plans.list": { "post": { "operationId": "discovery_plans_list", "summary": "List the Trustvice 360 subscription plans.", "x-trustvice-description-key": "actions.discovery.plans.list.description", "tags": [ "discovery" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "product": { "default": "all", "type": "string", "enum": [ "trustvice", "entpoind", "all" ] } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "List all plans.", "value": { "product": "all" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "product": { "type": "string", "enum": [ "trustvice", "entpoind" ] }, "name": { "type": "string" }, "priceUsdMinor": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "features": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "product", "name", "priceUsdMinor", "features" ], "additionalProperties": false } } }, "required": [ "plans" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List all plans.", "value": { "plans": [ { "id": "free", "product": "trustvice", "name": "Free", "priceUsdMinor": 0, "features": [ "1 workspace", "1k runs/mo" ] } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/discovery.regions.list": { "post": { "operationId": "discovery_regions_list", "summary": "List the data-residency regions a workspace can be bound to: the seven base regions and the extended AWS locations.", "x-trustvice-description-key": "actions.discovery.regions.list.description", "tags": [ "discovery" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "euOnly": { "default": false, "type": "boolean" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "List all 33 regions (7 Cloudflare + 26 AWS Aurora).", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "regions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string", "enum": [ "cloudflare-d1", "aws-aurora" ] }, "label": { "type": "string" }, "countryCode": { "type": "string" }, "euJurisdictionBound": { "type": "boolean" } }, "required": [ "id", "provider", "label", "countryCode", "euJurisdictionBound" ], "additionalProperties": false } } }, "required": [ "regions" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List all 33 regions (7 Cloudflare + 26 AWS Aurora).", "value": { "regions": [ { "id": "cloudflare-d1:weur-1", "provider": "cloudflare-d1", "label": "Europe Central", "countryCode": "EU", "euJurisdictionBound": true } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/discovery.confirmation.token.verify": { "post": { "operationId": "discovery_confirmation_token_verify", "summary": "Verify a confirmation token is well-formed + still valid (cannot be disabled — safety floor).", "x-trustvice-description-key": "actions.discovery.confirmation.token.verify.description", "tags": [ "discovery" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify confirmation token.", "value": { "token": "..." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "valid": { "type": "boolean" }, "actionId": { "type": "string" }, "expiresAt": { "type": "string" } }, "required": [ "valid" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify confirmation token.", "value": { "valid": true, "actionId": "workspace.delete.schedule", "expiresAt": "2026-05-22T12:01:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/agents.delegations.list": { "post": { "operationId": "agents_delegations_list", "summary": "List the A2A delegations this workspace has issued — the edges of the delegation graph (who delegated what to whom).", "x-trustvice-description-key": "actions.agents.delegations.list.description", "tags": [ "agents" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read the delegation edges — the input kill-chain and Muster both need.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "delegations": { "type": "array", "items": { "type": "object", "properties": { "delegationHandle": { "type": "string" }, "vcId": { "type": "string" }, "fromAgentDid": { "type": "string" }, "toRemoteDid": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "maxSpendUsdFractional": { "type": [ "number", "null" ] }, "purpose": { "type": "string" }, "issuedAt": { "type": "string" }, "expiresAt": { "type": "string" }, "revokedAt": { "type": [ "string", "null" ] } }, "required": [ "delegationHandle", "vcId", "fromAgentDid", "toRemoteDid", "scopes", "maxSpendUsdFractional", "purpose", "issuedAt", "expiresAt", "revokedAt" ], "additionalProperties": {} } } }, "required": [ "delegations" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read the delegation edges — the input kill-chain and Muster both need.", "value": { "delegations": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/agents.identity.enroll": { "post": { "operationId": "agents_identity_enroll", "summary": "Enroll a new W3C DID Web agent identity under your principal.", "x-trustvice-description-key": "actions.agents.identity.enroll.description", "tags": [ "agents" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 80 }, "scopeKind": { "type": "string", "enum": [ "account", "workspace", "organization" ] }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "organizationId": { "type": "string", "pattern": "^org_[0-9A-Z]{20,}$" }, "description": { "type": "string", "maxLength": 500 }, "alg": { "default": "EdDSA", "type": "string", "enum": [ "EdDSA", "ES256" ] } }, "required": [ "displayName", "scopeKind" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Enroll a workspace-scoped agent DID for CI signing.", "value": { "displayName": "GitHub Actions release attestor", "scopeKind": "workspace", "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "did": { "type": "string", "pattern": "^did:web:[A-Za-z0-9.\\-_:%]+$" }, "documentUrl": { "type": "string", "format": "uri" }, "enrollmentCredential": { "type": "string" }, "privateKeyRecoveryEnvelope": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "did", "documentUrl", "enrollmentCredential", "privateKeyRecoveryEnvelope", "createdAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Enroll a workspace-scoped agent DID for CI signing.", "value": { "did": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000:github-actions-release-attestor", "documentUrl": "https://api.trustvice.com/.well-known/agents/ws_DEMODEFAULT0000000000/github-actions-release-attestor/did.json", "enrollmentCredential": "eyJhbGciOiJFZERTQSJ9…", "privateKeyRecoveryEnvelope": "v1:AES-256-GCM:…", "createdAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "workspaces.view" ] }, { "OAuth2": [ "workspaces.view" ] }, { "WorkspaceApiKey": [ "workspaces.view" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent.identity.enrolled", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/agents.identity.list": { "post": { "operationId": "agents_identity_list", "summary": "List enrolled agent DIDs visible to the principal.", "x-trustvice-description-key": "actions.agents.identity.list.description", "tags": [ "agents" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "organizationId": { "type": "string", "pattern": "^org_[0-9A-Z]{20,}$" }, "includeDeactivated": { "default": false, "type": "boolean" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "List workspace-scoped agents.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "object", "properties": { "did": { "type": "string", "pattern": "^did:web:[A-Za-z0-9.\\-_:%]+$" }, "displayName": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "scopeKind": { "type": "string", "enum": [ "account", "workspace", "organization" ] }, "workspaceId": { "anyOf": [ { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, { "type": "null" } ] }, "organizationId": { "anyOf": [ { "type": "string", "pattern": "^org_[0-9A-Z]{20,}$" }, { "type": "null" } ] }, "alg": { "type": "string", "enum": [ "EdDSA", "ES256" ] }, "activeMethodId": { "type": [ "string", "null" ] }, "enrolledAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "deactivatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "lastSeenAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "rotationsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastTrustBundleSignedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "did", "displayName", "description", "scopeKind", "workspaceId", "organizationId", "alg", "activeMethodId", "enrolledAt", "deactivatedAt", "lastSeenAt", "rotationsCount", "lastTrustBundleSignedAt" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "agents", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List workspace-scoped agents.", "value": { "agents": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "workspaces.view" ] }, { "OAuth2": [ "workspaces.view" ] }, { "WorkspaceApiKey": [ "workspaces.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/agents.identity.get": { "post": { "operationId": "agents_identity_get", "summary": "Get one enrolled agent DID with full document + rotation history.", "x-trustvice-description-key": "actions.agents.identity.get.description", "tags": [ "agents" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "did": { "type": "string", "pattern": "^did:web:[A-Za-z0-9.\\-_:%]+$" } }, "required": [ "did" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read one agent DID.", "value": { "did": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "record": { "type": "object", "properties": { "did": { "type": "string", "pattern": "^did:web:[A-Za-z0-9.\\-_:%]+$" }, "displayName": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "scopeKind": { "type": "string", "enum": [ "account", "workspace", "organization" ] }, "workspaceId": { "anyOf": [ { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, { "type": "null" } ] }, "organizationId": { "anyOf": [ { "type": "string", "pattern": "^org_[0-9A-Z]{20,}$" }, { "type": "null" } ] }, "alg": { "type": "string", "enum": [ "EdDSA", "ES256" ] }, "activeMethodId": { "type": [ "string", "null" ] }, "enrolledAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "deactivatedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "lastSeenAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "rotationsCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "lastTrustBundleSignedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "did", "displayName", "description", "scopeKind", "workspaceId", "organizationId", "alg", "activeMethodId", "enrolledAt", "deactivatedAt", "lastSeenAt", "rotationsCount", "lastTrustBundleSignedAt" ], "additionalProperties": {} }, "document": {}, "rotationHistory": { "type": "array", "items": {} } }, "required": [ "record", "document", "rotationHistory" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read one agent DID.", "value": { "record": { "did": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc", "displayName": "GitHub Actions release attestor", "description": null, "scopeKind": "workspace", "workspaceId": "ws_DEMODEFAULT0000000000", "organizationId": null, "alg": "EdDSA", "activeMethodId": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc#key-1", "enrolledAt": "2026-05-22T12:00:00.000Z", "deactivatedAt": null, "lastSeenAt": null, "rotationsCount": 0, "lastTrustBundleSignedAt": null }, "document": {}, "rotationHistory": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "workspaces.view" ] }, { "OAuth2": [ "workspaces.view" ] }, { "WorkspaceApiKey": [ "workspaces.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/agents.identity.rotate": { "post": { "operationId": "agents_identity_rotate", "summary": "Rotate the signing key for an agent DID. Old key kept active for a cooldown period.", "x-trustvice-description-key": "actions.agents.identity.rotate.description", "tags": [ "agents" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "did": { "type": "string", "pattern": "^did:web:[A-Za-z0-9.\\-_:%]+$" }, "reason": { "type": "string", "enum": [ "scheduled", "incident", "compromise", "operator_request", "policy_required" ] }, "rationale": { "type": "string", "minLength": 10, "maxLength": 500 }, "alg": { "type": "string", "enum": [ "EdDSA", "ES256" ] }, "cooldownSeconds": { "default": 3600, "type": "integer", "minimum": 60, "maximum": 86400 } }, "required": [ "did", "reason" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Quarterly key rotation.", "value": { "did": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc", "reason": "scheduled" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "did": { "type": "string", "pattern": "^did:web:[A-Za-z0-9.\\-_:%]+$" }, "newMethodId": { "type": "string" }, "oldMethodRetiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "privateKeyRecoveryEnvelope": { "type": "string" } }, "required": [ "did", "newMethodId", "oldMethodRetiresAt", "privateKeyRecoveryEnvelope" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Quarterly key rotation.", "value": { "did": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc", "newMethodId": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc#key-2", "oldMethodRetiresAt": "2026-05-22T13:00:00.000Z", "privateKeyRecoveryEnvelope": "v1:AES-256-GCM:…" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "workspaces.view" ] }, { "OAuth2": [ "workspaces.view" ] }, { "WorkspaceApiKey": [ "workspaces.view" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent.identity.rotated", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/agents.identity.revoke": { "post": { "operationId": "agents_identity_revoke", "summary": "Permanently revoke an agent DID. Cannot be undone; the DID id cannot be re-enrolled.", "x-trustvice-description-key": "actions.agents.identity.revoke.description", "tags": [ "agents" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "did": { "type": "string", "pattern": "^did:web:[A-Za-z0-9.\\-_:%]+$" }, "reason": { "type": "string", "enum": [ "scheduled", "incident", "compromise", "operator_request", "policy_required" ] }, "rationale": { "type": "string", "minLength": 10, "maxLength": 500 }, "irreversibleAcknowledged": { "type": "boolean", "const": true } }, "required": [ "did", "reason", "irreversibleAcknowledged" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Compromise-recovery revoke.", "value": { "did": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc", "reason": "compromise", "irreversibleAcknowledged": true } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "did": { "type": "string", "pattern": "^did:web:[A-Za-z0-9.\\-_:%]+$" }, "deactivatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "auditEntryId": { "type": "string" } }, "required": [ "did", "deactivatedAt", "auditEntryId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Compromise-recovery revoke.", "value": { "did": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc", "deactivatedAt": "2026-05-22T12:00:00.000Z", "auditEntryId": "aud_DEMO00000000000000000000" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "workspaces.view" ] }, { "OAuth2": [ "workspaces.view" ] }, { "WorkspaceApiKey": [ "workspaces.view" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent.identity.revoked", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/agents.identity.did.resolve": { "post": { "operationId": "agents_identity_did_resolve", "summary": "Resolve any DID (did:web, did:key, did:peer) and return the resolution result envelope.", "x-trustvice-description-key": "actions.agents.identity.did.resolve.description", "tags": [ "agents" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "did": { "type": "string", "pattern": "^did:(web|key|peer):[A-Za-z0-9.\\-_:%]+$" } }, "required": [ "did" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Resolve a DID to its document.", "value": { "did": "did:web:trustvice.com:agents:mandate-issuer" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "didDocument": {}, "didResolutionMetadata": {}, "didDocumentMetadata": {} }, "required": [ "didDocument", "didResolutionMetadata", "didDocumentMetadata" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Resolve a DID to its document.", "value": { "didDocument": { "id": "did:web:trustvice.com:agents:mandate-issuer" }, "didResolutionMetadata": { "resolutionSource": "live", "resolvedAt": "2026-05-22T12:00:00.000Z" }, "didDocumentMetadata": {} } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/agents.passport.verify": { "post": { "operationId": "agents_passport_verify", "summary": "Verify an Agent Passport presented at an org boundary — offline checks, plus what offline cannot establish.", "x-trustvice-description-key": "actions.agents.passport.verify.description", "tags": [ "agents" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "passport": { "type": "object", "properties": { "agentDid": { "type": "string", "pattern": "^did:(web|key|peer):[A-Za-z0-9.\\-_:%]+$" }, "displayName": { "type": "string", "maxLength": 256 }, "issuerDid": { "type": "string", "pattern": "^did:(web|key|peer):[A-Za-z0-9.\\-_:%]+$" }, "mandates": { "type": "array", "items": { "type": "object", "properties": { "mandateId": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "minLength": 1 }, "autonomyCeiling": { "type": "string", "enum": [ "read", "mutation", "billing_impacting", "destructive" ] } }, "required": [ "mandateId", "scope", "autonomyCeiling" ], "additionalProperties": false } }, "actorScore": { "type": [ "number", "null" ] }, "spiffeId": { "type": [ "string", "null" ] }, "conductAnchorRef": { "type": [ "string", "null" ] }, "issuedFor": { "type": "string", "maxLength": 256 }, "issuedAt": { "type": "string", "minLength": 1 }, "expiresAt": { "type": [ "string", "null" ] } }, "required": [ "agentDid", "issuerDid", "mandates", "issuedAt" ], "additionalProperties": false }, "signature": { "type": "string", "minLength": 1 }, "issuerKey": { "type": "object", "properties": { "kty": { "type": "string", "const": "OKP" }, "crv": { "type": "string", "const": "Ed25519" }, "x": { "type": "string", "minLength": 1 } }, "required": [ "kty", "crv", "x" ], "additionalProperties": {} }, "expectedSubjectDid": { "type": "string", "pattern": "^did:(web|key|peer):[A-Za-z0-9.\\-_:%]+$" }, "maxStalenessSeconds": { "type": "number", "minimum": 0 } }, "required": [ "passport" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "With no key, the signature is unchecked — and an unchecked signature never reads as a passed one.", "value": { "passport": { "agentDid": "did:web:other-org.example:agents:a1", "issuerDid": "did:web:other-org.example", "mandates": [], "issuedAt": "2026-09-03T00:00:00.000Z" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "verification": { "type": "object", "properties": { "agentDid": { "type": "string" }, "verdict": { "type": "string", "enum": [ "checks_passed_offline", "failed", "expired" ] }, "checks": { "type": "array", "items": { "type": "object", "properties": { "check": { "type": "string" }, "outcome": { "type": "string", "enum": [ "passed", "failed", "not_checkable_offline" ] }, "detail": { "type": "string" } }, "required": [ "check", "outcome", "detail" ], "additionalProperties": {} } }, "stalenessSeconds": { "type": "number" }, "assertedCeiling": { "anyOf": [ { "type": "string", "enum": [ "read", "mutation", "billing_impacting", "destructive" ] }, { "type": "null" } ] }, "issuerAsserted": { "type": "array", "items": { "type": "string" } }, "cannotEstablish": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "agentDid", "verdict", "checks", "stalenessSeconds", "assertedCeiling", "issuerAsserted", "cannotEstablish", "notes" ], "additionalProperties": {} }, "signature": { "type": "object", "properties": { "verified": { "type": "boolean" }, "keySource": { "type": "string", "enum": [ "did_key", "receiver_supplied", "none" ] }, "keyConflict": { "type": "boolean" }, "detail": { "type": "string" } }, "required": [ "verified", "keySource", "keyConflict", "detail" ], "additionalProperties": {} }, "registry": { "anyOf": [ { "type": "object", "properties": { "did": { "type": "string" }, "status": { "type": "string" }, "revokedAt": { "type": [ "string", "null" ] }, "online": { "type": "boolean", "const": true }, "detail": { "type": "string" } }, "required": [ "did", "status", "revokedAt", "online", "detail" ], "additionalProperties": {} }, { "type": "null" } ] }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "verification", "signature", "registry", "notes" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "With no key, the signature is unchecked — and an unchecked signature never reads as a passed one.", "value": { "verification": { "agentDid": "did:web:other-org.example:agents:a1", "verdict": "failed", "checks": [], "stalenessSeconds": 86400, "assertedCeiling": null, "issuerAsserted": [], "cannotEstablish": [], "notes": [] }, "signature": { "verified": false, "keySource": "none", "keyConflict": false, "detail": "No verifying key." }, "registry": null, "notes": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/agents.handshake.notarize": { "post": { "operationId": "agents_handshake_notarize", "summary": "Run the A2A attestation ceremony: verify both parties' identity, mandate and SPIFFE, then scope-match the capabilities.", "x-trustvice-description-key": "actions.agents.handshake.notarize.description", "tags": [ "agents" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "handshakeRef": { "type": "string", "minLength": 1, "maxLength": 128 }, "initiator": { "type": "object", "properties": { "did": { "type": "string", "pattern": "^did:(web|key|peer):[A-Za-z0-9.\\-_:%]+$" }, "mandateHandle": { "type": "string", "minLength": 1, "maxLength": 128 }, "spiffeId": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "did" ], "additionalProperties": false }, "responder": { "type": "object", "properties": { "did": { "type": "string", "pattern": "^did:(web|key|peer):[A-Za-z0-9.\\-_:%]+$" }, "mandateHandle": { "type": "string", "minLength": 1, "maxLength": 128 }, "spiffeId": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "did" ], "additionalProperties": false }, "requestedCapabilities": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 } } }, "required": [ "workspaceId", "handshakeRef", "initiator", "responder", "requestedCapabilities" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "No mandates presented, so neither side licenses anything and the handshake declines.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "handshakeRef": "hs_DEMO0000", "initiator": { "did": "did:web:example.com:agents:ws:a" }, "responder": { "did": "did:web:other.example:agents:b" }, "requestedCapabilities": [ "billing.invoice.list" ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "attestation": { "type": "object", "properties": { "handshakeRef": { "type": "string" }, "outcome": { "type": "string", "enum": [ "accepted", "declined" ] }, "parties": { "type": "array", "items": { "type": "object", "properties": { "did": { "type": "string" }, "nonRepudiable": { "type": "boolean" }, "unverified": { "type": "array", "items": { "type": "string" } }, "failed": { "type": "array", "items": { "type": "string" } }, "reason": { "type": "string" } }, "required": [ "did", "nonRepudiable", "unverified", "failed", "reason" ], "additionalProperties": {} } }, "capabilities": { "type": "array", "items": { "type": "object", "properties": { "capability": { "type": "string" }, "matched": { "type": "boolean" }, "missingFor": { "type": "array", "items": { "type": "string" } } }, "required": [ "capability", "matched", "missingFor" ], "additionalProperties": {} } }, "unmatchedCapabilities": { "type": "array", "items": { "type": "string" } }, "effectiveCeiling": { "anyOf": [ { "type": "string", "enum": [ "read", "mutation", "billing_impacting", "destructive" ] }, { "type": "null" } ] }, "nonRepudiable": { "type": "boolean" }, "declineReasons": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "handshakeRef", "outcome", "parties", "capabilities", "unmatchedCapabilities", "effectiveCeiling", "nonRepudiable", "declineReasons", "notes" ], "additionalProperties": {} }, "performed": { "type": "object", "properties": { "initiator": {}, "responder": {} }, "required": [ "initiator", "responder" ], "additionalProperties": {} }, "mint": { "type": "object", "properties": { "kind": { "type": "string", "const": "handshake-notary" }, "source": {} }, "required": [ "kind", "source" ], "additionalProperties": {} }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "attestation", "performed", "mint", "notes" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "No mandates presented, so neither side licenses anything and the handshake declines.", "value": { "attestation": { "handshakeRef": "hs_DEMO0000", "outcome": "declined", "parties": [], "capabilities": [], "unmatchedCapabilities": [ "billing.invoice.list" ], "effectiveCeiling": null, "nonRepudiable": false, "declineReasons": [], "notes": [] }, "performed": { "initiator": {}, "responder": {} }, "mint": { "kind": "handshake-notary", "source": {} }, "notes": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/agents.marketplace.rank": { "post": { "operationId": "agents_marketplace_rank", "summary": "Rank mandate templates by standing then narrowest scope — never by adoption.", "x-trustvice-description-key": "actions.agents.marketplace.rank.description", "tags": [ "agents" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entries": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "template": { "type": "object", "properties": { "templateId": { "type": "string", "minLength": 1, "maxLength": 128 }, "publisher": { "type": "string", "minLength": 1, "maxLength": 512 }, "label": { "type": "string", "maxLength": 256 }, "allowedActionIds": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 } }, "maxSafetyLevel": { "type": "string", "enum": [ "read", "mutation", "billing_impacting", "destructive" ] }, "maxSpendFractional": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "templateId", "publisher", "allowedActionIds", "maxSafetyLevel", "maxSpendFractional" ], "additionalProperties": false }, "record": { "type": "object", "properties": { "deployments": { "type": "number", "minimum": 0 }, "runs": { "type": "number", "minimum": 0 }, "incidents": { "type": "number", "minimum": 0 }, "mandateViolations": { "type": "number", "minimum": 0 }, "refusals": { "type": "number", "minimum": 0 } }, "required": [ "deployments", "runs", "incidents", "mandateViolations", "refusals" ], "additionalProperties": false } }, "required": [ "template", "record" ], "additionalProperties": false } } }, "required": [ "entries" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Standing, then narrowest scope. Never adoption.", "value": { "entries": [ { "template": { "templateId": "narrow", "publisher": "did:web:pub", "allowedActionIds": [ "billing.invoice.list" ], "maxSafetyLevel": "read", "maxSpendFractional": 1000 }, "record": { "deployments": 50, "runs": 10000, "incidents": 0, "mandateViolations": 0, "refusals": 40 } } ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "view": { "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "template": {}, "standing": { "type": "string", "enum": [ "proven", "insufficient_history", "unproven" ] }, "scopeBreadth": { "type": "number" }, "incidentRate": { "type": [ "number", "null" ] }, "refusalRate": { "type": [ "number", "null" ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "reason": { "type": "string" } }, "required": [ "template", "standing", "scopeBreadth", "incidentRate", "refusalRate", "warnings", "reason" ], "additionalProperties": {} } }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "templates", "notes" ], "additionalProperties": {} }, "historyFloor": { "type": "object", "properties": { "deployments": { "type": "number" }, "runs": { "type": "number" } }, "required": [ "deployments", "runs" ], "additionalProperties": {} }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "view", "historyFloor", "notes" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Standing, then narrowest scope. Never adoption.", "value": { "view": { "templates": [], "notes": [] }, "historyFloor": { "deployments": 5, "runs": 250 }, "notes": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/agents.identity.delegate": { "post": { "operationId": "agents_identity_delegate", "summary": "Issue an A2A delegation token granting a remote partner DID a scope subset on your behalf.", "x-trustvice-description-key": "actions.agents.identity.delegate.description", "tags": [ "agents" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "fromAgentDid": { "type": "string", "pattern": "^did:web:[A-Za-z0-9.\\-_:%]+$" }, "toRemoteDid": { "type": "string", "pattern": "^did:(web|key|peer):[A-Za-z0-9.\\-_:%]+$" }, "scopes": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "maxSpendUsdFractional": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "validForDays": { "default": 7, "type": "integer", "minimum": 1, "maximum": 90 }, "purposeReason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "fromAgentDid", "toRemoteDid", "scopes", "purposeReason" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Issue A2A delegation.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "fromAgentDid": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc", "toRemoteDid": "did:web:partner.example.com:agents:bot", "scopes": [ "read:audit" ], "validForDays": 7, "purposeReason": "Partner integration handoff" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "delegationVcSerialized": { "type": "string" }, "delegationHandle": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "delegationVcSerialized", "delegationHandle", "expiresAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Issue A2A delegation.", "value": { "delegationVcSerialized": "eyJhbGciOiJFZERTQSJ9…", "delegationHandle": "delg_demo00000000000000000000", "expiresAt": "2026-05-29T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "workspaces.view" ] }, { "OAuth2": [ "workspaces.view" ] }, { "WorkspaceApiKey": [ "workspaces.view" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent.delegation.issued", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/agents.identity.delegate.revoke": { "post": { "operationId": "agents_identity_delegate_revoke", "summary": "Revoke an issued A2A delegation. Flips its bit in the published BitstringStatusList; listRevocable is false for delegations that predate the list.", "x-trustvice-description-key": "actions.agents.identity.delegate.revoke.description", "tags": [ "agents" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "delegationHandle": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "delegationHandle" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Withdraw a delegation.", "value": { "delegationHandle": "delg_demo00000000000000000000", "reason": "Partnership ended" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "revokedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "listRevocable": { "type": "boolean" } }, "required": [ "revokedAt", "listRevocable" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Withdraw a delegation.", "value": { "revokedAt": "2026-05-22T12:00:00.000Z", "listRevocable": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "workspaces.view" ] }, { "OAuth2": [ "workspaces.view" ] }, { "WorkspaceApiKey": [ "workspaces.view" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent.delegation.revoked", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/agents.mandate.issue": { "post": { "operationId": "agents_mandate_issue", "summary": "Issue an AP2 Verifiable Credential mandate authorising an agent up to spend / volume limits.", "x-trustvice-description-key": "actions.agents.mandate.issue.description", "tags": [ "agents" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "agentDid": { "type": "string", "pattern": "^did:(web|key|peer):[A-Za-z0-9.\\-_:%]+$" }, "allowedActionIds": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "maxSafetyLevel": { "type": "string", "enum": [ "read", "mutation", "destructive", "billing_impacting" ] }, "workspaceIds": { "minItems": 1, "type": "array", "items": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "maxSpendUsdFractional": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "maxInvocations": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "validForDays": { "default": 30, "type": "integer", "minimum": 1, "maximum": 365 } }, "required": [ "label", "agentDid", "allowedActionIds", "maxSafetyLevel", "workspaceIds" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Issue an AP2 mandate.", "value": { "label": "Stripe refund bot — Q3", "agentDid": "did:web:trustvice.com:agents:refund-bot", "allowedActionIds": [ "billing.subscription.upgrade", "entpoind.attest.agent-call" ], "maxSafetyLevel": "billing_impacting", "workspaceIds": [ "ws_DEMODEFAULT0000000000" ], "maxSpendUsdFractional": 50000, "maxInvocations": 100, "validForDays": 30 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "mandateHandle": { "type": "string", "pattern": "^mandate_[0-9A-Z]{20,}$" }, "vcId": { "type": "string", "pattern": "^urn:uuid:[0-9a-f-]{36}$" }, "sdJwtVcSerialized": { "type": "string" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "issuerDid": { "type": "string" } }, "required": [ "mandateHandle", "vcId", "sdJwtVcSerialized", "validUntil", "issuerDid" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Issue an AP2 mandate.", "value": { "mandateHandle": "mandate_DEMO00000000000000000000", "vcId": "urn:uuid:11111111-2222-3333-4444-555555555555", "sdJwtVcSerialized": "eyJhbGciOiJFZERTQSJ9…~WyJzYWx0Iiw…~", "validUntil": "2026-06-21T12:00:00.000Z", "issuerDid": "did:web:trustvice.com:agents:mandate-issuer" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "workspaces.view" ] }, { "OAuth2": [ "workspaces.view" ] }, { "WorkspaceApiKey": [ "workspaces.view" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent.mandate.issued", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/agents.mandate.list": { "post": { "operationId": "agents_mandate_list", "summary": "List mandates issued under the principal.", "x-trustvice-description-key": "actions.agents.mandate.list.description", "tags": [ "agents" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "activeOnly": { "default": false, "type": "boolean" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "List mandates.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "mandates": { "type": "array", "items": { "type": "object", "properties": { "mandateHandle": { "type": "string", "pattern": "^mandate_[0-9A-Z]{20,}$" }, "vcId": { "type": "string", "pattern": "^urn:uuid:[0-9a-f-]{36}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "agentDid": { "type": "string", "pattern": "^did:(web|key|peer):[A-Za-z0-9.\\-_:%]+$" }, "agentDisplayName": { "type": "string" }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "validUntil": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "revocationReason": { "type": [ "string", "null" ] } }, "required": [ "mandateHandle", "vcId", "label", "agentDid", "agentDisplayName", "issuedAt", "validUntil", "revokedAt", "revocationReason" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "mandates", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List mandates.", "value": { "mandates": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "workspaces.view" ] }, { "OAuth2": [ "workspaces.view" ] }, { "WorkspaceApiKey": [ "workspaces.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/agents.mandate.verify": { "post": { "operationId": "agents_mandate_verify", "summary": "Verify a presented mandate VC against an action request. Returns ok or a structured reason.", "x-trustvice-description-key": "actions.agents.mandate.verify.description", "tags": [ "agents" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "presentationSerialized": { "type": "string" }, "requestedActionId": { "type": "string" }, "estimatedSpendUsdFractional": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "audience": { "type": "string", "format": "uri" }, "nonce": { "type": "string", "minLength": 8 } }, "required": [ "presentationSerialized", "requestedActionId", "audience", "nonce" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify a mandate.", "value": { "presentationSerialized": "eyJhbGciOiJFZERTQSJ9.eyJleGFtcGxlIjp0cnVlfQ.c2lnbmF0dXJlLWV4YW1wbGU", "requestedActionId": "billing.subscription.upgrade", "audience": "https://api.trustvice.com", "nonce": "abc123abc123" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "mandateHandle": { "type": "string", "pattern": "^mandate_[0-9A-Z]{20,}$" }, "vcId": { "type": "string", "pattern": "^urn:uuid:[0-9a-f-]{36}$" }, "remainingSpendUsdFractional": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "remainingInvocations": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "issuerResolutionSource": { "type": "string", "enum": [ "live", "cache", "ots-anchored-cold" ] } }, "required": [ "ok", "mandateHandle", "vcId", "issuerResolutionSource" ], "additionalProperties": false }, { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "reason": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "ok", "reason" ], "additionalProperties": false } ] }, "examples": { "example_0": { "summary": "Verify a mandate.", "value": { "ok": true, "mandateHandle": "mandate_DEMO00000000000000000000", "vcId": "urn:uuid:11111111-2222-3333-4444-555555555555", "remainingSpendUsdFractional": 25000, "remainingInvocations": 50, "issuerResolutionSource": "live" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/agents.mandate.revoke": { "post": { "operationId": "agents_mandate_revoke", "summary": "Revoke a mandate. Goes into the BitstringStatusList revocation register immediately.", "x-trustvice-description-key": "actions.agents.mandate.revoke.description", "tags": [ "agents" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "mandateHandle": { "type": "string", "pattern": "^mandate_[0-9A-Z]{20,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "mandateHandle" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Revoke a mandate.", "value": { "mandateHandle": "mandate_DEMO00000000000000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "revokedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "revokedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Revoke a mandate.", "value": { "revokedAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "workspaces.view" ] }, { "OAuth2": [ "workspaces.view" ] }, { "WorkspaceApiKey": [ "workspaces.view" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent.mandate.revoked", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/agents.spiffe.bind": { "post": { "operationId": "agents_spiffe_bind", "summary": "Bind a SPIFFE ID to an agent DID so SVIDs (X.509 or JWT) can attest as that agent.", "x-trustvice-description-key": "actions.agents.spiffe.bind.description", "tags": [ "agents" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentDid": { "type": "string", "pattern": "^did:web:[A-Za-z0-9.\\-_:%]+$" }, "spiffeId": { "type": "string", "pattern": "^spiffe:\\/\\/[A-Za-z0-9.\\-]+(\\/[A-Za-z0-9._\\-/]*)?$" }, "svidType": { "type": "string", "enum": [ "x509", "jwt" ] } }, "required": [ "agentDid", "spiffeId", "svidType" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Bind SPIFFE workload to agent.", "value": { "agentDid": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc", "spiffeId": "spiffe://corp.example.com/svc/billing", "svidType": "jwt" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentDid": { "type": "string", "pattern": "^did:web:[A-Za-z0-9.\\-_:%]+$" }, "spiffeId": { "type": "string", "pattern": "^spiffe:\\/\\/[A-Za-z0-9.\\-]+(\\/[A-Za-z0-9._\\-/]*)?$" }, "boundAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "agentDid", "spiffeId", "boundAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Bind SPIFFE workload to agent.", "value": { "agentDid": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc", "spiffeId": "spiffe://corp.example.com/svc/billing", "boundAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "workspaces.view" ] }, { "OAuth2": [ "workspaces.view" ] }, { "WorkspaceApiKey": [ "workspaces.view" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent.spiffe.bound", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/agents.spiffe.workload.attest": { "post": { "operationId": "agents_spiffe_workload_attest", "summary": "Exchange a SPIFFE SVID for a short-lived DPoP-bound Trustvice session.", "x-trustvice-description-key": "actions.agents.spiffe.workload.attest.description", "tags": [ "agents" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "svid": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "x509" }, "certificatesPem": { "type": "string" } }, "required": [ "type", "certificatesPem" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "jwt" }, "token": { "type": "string" } }, "required": [ "type", "token" ] } ] }, "dpopKey": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "svid", "dpopKey" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Workload exchange.", "value": { "svid": { "type": "jwt", "token": "eyJhbGciOiJFZERTQSJ9.eyJleGFtcGxlIjp0cnVlfQ.c2lnbmF0dXJlLWV4YW1wbGU" }, "dpopKey": { "kty": "OKP", "crv": "Ed25519", "x": "" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sessionToken": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "agentDid": { "type": "string", "pattern": "^did:web:[A-Za-z0-9.\\-_:%]+$" }, "effectiveScopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "sessionToken", "expiresAt", "agentDid", "effectiveScopes" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Workload exchange.", "value": { "sessionToken": "tv_sess_demo…", "expiresAt": "2026-05-22T12:05:00.000Z", "agentDid": "did:web:trustvice.com:agents:ws_DEMODEFAULT0000000000-abc", "effectiveScopes": [ "read:audit" ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/agents.trusted-roots.list": { "post": { "operationId": "agents_trusted-roots_list", "summary": "List partner organization DIDs the workspace accepts as A2A federation roots.", "x-trustvice-description-key": "actions.agents.trusted-roots.list.description", "tags": [ "agents" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List trusted A2A roots.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "roots": { "type": "array", "items": { "type": "object", "properties": { "did": { "type": "string", "pattern": "^did:web:[A-Za-z0-9.\\-_:%]+$" }, "organizationName": { "type": "string" }, "trustedSince": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "maxAcceptedSafetyLevel": { "type": "string", "enum": [ "read", "mutation", "destructive", "billing_impacting" ] }, "allowsFederation": { "type": "boolean" } }, "required": [ "did", "organizationName", "trustedSince", "maxAcceptedSafetyLevel", "allowsFederation" ], "additionalProperties": false } } }, "required": [ "roots" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List trusted A2A roots.", "value": { "roots": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "workspaces.view" ] }, { "OAuth2": [ "workspaces.view" ] }, { "WorkspaceApiKey": [ "workspaces.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/agents.trusted-roots.add": { "post": { "operationId": "agents_trusted-roots_add", "summary": "Add a partner organization DID to the trusted-roots list for this workspace.", "x-trustvice-description-key": "actions.agents.trusted-roots.add.description", "tags": [ "agents" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "did": { "type": "string", "pattern": "^did:web:[A-Za-z0-9.\\-_:%]+$" }, "organizationName": { "type": "string", "minLength": 1, "maxLength": 80 }, "maxAcceptedSafetyLevel": { "default": "mutation", "type": "string", "enum": [ "read", "mutation", "destructive", "billing_impacting" ] }, "allowsFederation": { "default": false, "type": "boolean" } }, "required": [ "workspaceId", "did", "organizationName" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Add federated root.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "did": "did:web:partner.example.com", "organizationName": "Partner Example Corp", "maxAcceptedSafetyLevel": "mutation" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "addedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "addedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Add federated root.", "value": { "addedAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "workspaces.view" ] }, { "OAuth2": [ "workspaces.view" ] }, { "WorkspaceApiKey": [ "workspaces.view" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent.trusted_root.added", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/trustactor.run": { "post": { "operationId": "trustactor_run", "summary": "Post a run to a TrustActor spot actor (witness/council/historian/custodian/conscience/…) — observe + decide + anchor it in the workspace hash-chain.", "x-trustvice-description-key": "actions.trustactor.run.description", "tags": [ "trustactor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "version": { "default": "v1", "type": "string", "enum": [ "v0", "v1", "v2" ] }, "actor": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Actor id, e.g. 'witness'." }, "agentDid": { "description": "DID of the agent that produced the run.", "type": [ "string", "null" ] }, "input": { "description": "The agent run payload — opaque; the actor interprets it." } }, "required": [ "actor", "input" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Witness a billing-agent run.", "value": { "version": "v1", "actor": "witness", "agentDid": "did:web:example.com:agent:billing", "input": { "task": "refund", "amount": 4200 } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "status": { "type": "string" }, "receipt": {}, "spillToR2": { "type": "boolean" } }, "required": [ "status", "receipt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Witness a billing-agent run.", "value": { "status": "ok", "receipt": { "runId": "run_abc" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_invocation", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/trustactor.runs.list": { "post": { "operationId": "trustactor_runs_list", "summary": "List the workspace's TrustActor runs (actor IS the surface: witness | historian | custodian | conscience | …).", "x-trustvice-description-key": "actions.trustactor.runs.list.description", "tags": [ "trustactor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "actor": { "type": "string", "maxLength": 32 }, "version": { "type": "string", "enum": [ "v0", "v1", "v2" ] }, "agentDid": { "type": "string" }, "limit": { "default": 50, "type": "integer", "minimum": 1, "maximum": 200 } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Recent witness runs.", "value": { "actor": "witness", "limit": 20 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "runs": { "type": "array", "items": {} }, "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "runs", "count" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Recent witness runs.", "value": { "runs": [], "count": 0 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/trustactor.actors.list": { "post": { "operationId": "trustactor_actors_list", "summary": "List the TrustActor roster (optionally for one version) with each actor's min tier.", "x-trustvice-description-key": "actions.trustactor.actors.list.description", "tags": [ "trustactor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "version": { "type": "string", "enum": [ "v0", "v1", "v2" ] } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Discover v1 actors.", "value": { "version": "v1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "actors": { "type": "array", "items": {} } }, "required": [ "actors" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Discover v1 actors.", "value": { "actors": [ { "id": "witness", "version": "v1", "minTier": "free" } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/trustactor.agents.list": { "post": { "operationId": "trustactor_agents_list", "summary": "List the workspace's posting agents (distinct agent DIDs across runs, with counts + last-seen).", "x-trustvice-description-key": "actions.trustactor.agents.list.description", "tags": [ "trustactor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Who's posting runs.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agents": { "type": "array", "items": {} }, "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "agents", "count" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Who's posting runs.", "value": { "agents": [], "count": 0 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/trustactor.runs.verify-chain": { "post": { "operationId": "trustactor_runs_verify-chain", "summary": "Verify the integrity of the workspace's run hash-chain from a starting sequence.", "x-trustvice-description-key": "actions.trustactor.runs.verify-chain.description", "tags": [ "trustactor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "from": { "default": 1, "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Prove the chain is intact.", "value": { "from": 1 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Prove the chain is intact.", "value": { "ok": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/trustactor.runs.diff": { "post": { "operationId": "trustactor_runs_diff", "summary": "Compare two TrustActor runs (classification + payload diff).", "x-trustvice-description-key": "actions.trustactor.runs.diff.description", "tags": [ "trustactor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "a": { "type": "string", "minLength": 1 }, "b": { "type": "string", "minLength": 1 } }, "required": [ "a", "b" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Diff two runs.", "value": { "a": "run_abc", "b": "run_def" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Diff two runs.", "value": { "ok": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/trustactor.runs.replay": { "post": { "operationId": "trustactor_runs_replay", "summary": "Reconstruct + re-verify a single run from its chain entry.", "x-trustvice-description-key": "actions.trustactor.runs.replay.description", "tags": [ "trustactor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "runId": { "type": "string", "minLength": 1 }, "expectInputHash": { "type": "string" } }, "required": [ "runId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Replay a run.", "value": { "runId": "run_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ok": { "type": "boolean" }, "found": { "type": "boolean" } }, "required": [ "ok", "found" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Replay a run.", "value": { "ok": true, "found": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/trustactor.liability.blame-graph": { "post": { "operationId": "trustactor_liability_blame-graph", "summary": "Apportion fault across a multi-agent failure from a signed causal chain.", "x-trustvice-description-key": "actions.trustactor.liability.blame-graph.description", "tags": [ "trustactor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "incidentRef": { "type": "string", "minLength": 1, "maxLength": 128 }, "nodes": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "nodeId": { "type": "string", "minLength": 1, "maxLength": 128 }, "actorDid": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "null" } ] }, "action": { "type": "string", "minLength": 1, "maxLength": 1000 }, "inputsFrom": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "actedCorrectly": { "type": "boolean" }, "evidenceRefs": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 } }, "causalWeight": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "nodeId", "actorDid", "action", "actedCorrectly", "causalWeight" ], "additionalProperties": false } } }, "required": [ "incidentRef", "nodes" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "One at-fault node, fully evidenced.", "value": { "incidentRef": "inc_1", "nodes": [ { "nodeId": "n1", "actorDid": "did:web:a.example", "action": "issued a refund", "actedCorrectly": false, "evidenceRefs": [ "run_1" ], "causalWeight": 1 } ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "graph": { "type": "object", "properties": { "incidentRef": { "type": "string" }, "computedAt": { "type": "string" }, "apportioned": { "type": "array", "items": {} }, "unattributed": { "type": "object", "properties": { "share": { "type": "number" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "share", "reasons" ], "additionalProperties": {} }, "exonerated": { "type": "array", "items": {} }, "fullyEvidenced": { "type": "boolean" }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "incidentRef", "computedAt", "apportioned", "unattributed", "exonerated", "fullyEvidenced", "notes" ], "additionalProperties": {} }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "graph", "notes" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "One at-fault node, fully evidenced.", "value": { "graph": { "incidentRef": "inc_1", "computedAt": "2026-09-04T00:00:00.000Z", "apportioned": [], "unattributed": { "share": 0, "reasons": [] }, "exonerated": [], "fullyEvidenced": true, "notes": [] }, "notes": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/trustactor.liability.indemnity-feed": { "post": { "operationId": "trustactor_liability_indemnity-feed", "summary": "Build the underwriting evidence feed for one agent — observed experience, stated credibility, and no pricing.", "x-trustvice-description-key": "actions.trustactor.liability.indemnity-feed.description", "tags": [ "trustactor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentRef": { "type": "string", "minLength": 1, "maxLength": 512 }, "window": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "maxLength": 64 }, "to": { "type": "string", "minLength": 1, "maxLength": 64 }, "runs": { "type": "number", "minimum": 0 } }, "required": [ "from", "to", "runs" ], "additionalProperties": false }, "experience": { "type": "object", "properties": { "incidents": { "type": "number", "minimum": 0 }, "mandateViolations": { "type": "number", "minimum": 0 }, "breakerTrips": { "type": "number", "minimum": 0 }, "oversightAdherence": { "type": "number", "minimum": 0, "maximum": 1 }, "apportionedFaultShares": { "type": "array", "items": { "type": "number", "minimum": 0, "maximum": 1 } } }, "required": [ "incidents", "mandateViolations", "breakerTrips", "oversightAdherence" ], "additionalProperties": false } }, "required": [ "agentRef", "window", "experience" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "A data source, not a price.", "value": { "agentRef": "did:web:a.example", "window": { "from": "2026-01-01T00:00:00.000Z", "to": "2026-09-01T00:00:00.000Z", "runs": 5000 }, "experience": { "incidents": 2, "mandateViolations": 1, "breakerTrips": 3, "oversightAdherence": 0.9 } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "feed": { "type": "object", "properties": { "agentRef": { "type": "string" }, "window": {}, "credibility": { "type": "number" }, "credibilityBasis": { "type": "object", "properties": { "nFull": { "type": "number" }, "floor": { "type": "number" } }, "required": [ "nFull", "floor" ], "additionalProperties": {} }, "belowFloor": { "type": "boolean" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "ratePerThousand": { "type": [ "number", "null" ] }, "count": { "type": "number" }, "note": { "type": "string" } }, "required": [ "label", "ratePerThousand", "count", "note" ], "additionalProperties": {} } }, "fault": { "type": "object", "properties": { "totalShare": { "type": "number" }, "findings": { "type": "number" }, "note": { "type": "string" } }, "required": [ "totalShare", "findings", "note" ], "additionalProperties": {} }, "priced": { "type": "boolean", "const": false }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "agentRef", "window", "credibility", "credibilityBasis", "belowFloor", "entries", "fault", "priced", "notes" ], "additionalProperties": {} }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "feed", "notes" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "A data source, not a price.", "value": { "feed": { "agentRef": "did:web:a.example", "window": {}, "credibility": 0.68, "credibilityBasis": { "nFull": 1082, "floor": 30 }, "belowFloor": false, "entries": [], "fault": { "totalShare": 0, "findings": 0, "note": "" }, "priced": false, "notes": [] }, "notes": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/trustactor.actor-score": { "post": { "operationId": "trustactor_actor-score", "summary": "Compute an agent's Actor Score from its signed runs, with every deduction naming the run that caused it.", "x-trustvice-description-key": "actions.trustactor.actor-score.description", "tags": [ "trustactor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentRef": { "type": "string", "minLength": 1, "maxLength": 512 }, "runs": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "runId": { "type": "string", "minLength": 1, "maxLength": 128 }, "signed": { "type": "boolean" }, "safetyLevel": { "type": "string", "enum": [ "read", "mutation", "billing_impacting", "destructive" ] }, "oversightHonoured": { "type": "boolean" }, "mandateViolation": { "type": "boolean" }, "breakerTripped": { "type": "boolean" }, "incident": { "type": "boolean" } }, "required": [ "runId", "signed", "safetyLevel", "oversightHonoured", "mandateViolation", "breakerTripped", "incident" ], "additionalProperties": false } } }, "required": [ "agentRef", "runs" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "One run is not a score.", "value": { "agentRef": "did:web:a.example", "runs": [ { "runId": "run_1", "signed": true, "safetyLevel": "read", "oversightHonoured": true, "mandateViolation": false, "breakerTripped": false, "incident": false } ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "score": { "type": "object", "properties": { "agentRef": { "type": "string" }, "score": { "type": [ "number", "null" ] }, "band": { "anyOf": [ { "type": "string", "enum": [ "exemplary", "sound", "watch", "at-risk" ] }, { "type": "null" } ] }, "runsScored": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "runsExcludedUnsigned": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "tiers": { "type": "array", "items": {} }, "unprovenTiers": { "type": "array", "items": { "type": "string" } }, "faultingRunIds": { "type": "array", "items": { "type": "string" } }, "computedAt": { "type": "string" }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "agentRef", "score", "band", "runsScored", "runsExcludedUnsigned", "tiers", "unprovenTiers", "faultingRunIds", "computedAt", "notes" ], "additionalProperties": {} }, "mint": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "actor-score" }, "source": {} }, "required": [ "kind", "source" ], "additionalProperties": {} }, { "type": "null" } ] }, "notMintableReason": { "type": [ "string", "null" ] }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "score", "mint", "notMintableReason", "notes" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "One run is not a score.", "value": { "score": { "agentRef": "did:web:a.example", "score": null, "band": null, "runsScored": 1, "runsExcludedUnsigned": 0, "tiers": [], "unprovenTiers": [ "read" ], "faultingRunIds": [], "computedAt": "2026-09-04T00:00:00.000Z", "notes": [] }, "mint": null, "notMintableReason": "Not mintable: 1 signed run(s), below the floor…", "notes": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.catalog.get": { "post": { "operationId": "nexus_catalog_get", "summary": "Get the Nexus product catalogue (the available primitives + tiers for the workspace).", "x-trustvice-description-key": "actions.nexus.catalog.get.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "List Nexus primitives.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "List Nexus primitives.", "value": { "products": [ { "product": "oracle", "basePath": "/v1/nexus/oracle", "mcpEndpoint": "/api/v1/nexus/oracle/mcp", "graphqlEndpoint": "/api/v1/nexus/oracle/graphql" } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.usage.get": { "post": { "operationId": "nexus_usage_get", "summary": "Get the workspace's Nexus usage + quota for the current period.", "x-trustvice-description-key": "actions.nexus.usage.get.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read Nexus usage.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read Nexus usage.", "value": { "period": "2026-09", "tier": "pro", "metrics": [ { "metric": "oracle_query", "used": 1284, "limit": 50000 }, { "metric": "ledger_append", "used": 63, "limit": null } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.oracle.agent.get": { "post": { "operationId": "nexus_oracle_agent_get", "summary": "Look up the Nexus Oracle reputation for a specific agent (by id / DID).", "x-trustvice-description-key": "actions.nexus.oracle.agent.get.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1, "description": "Agent id or DID to score." } }, "required": [ "agentId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Reputation for an agent.", "value": { "agentId": "did:web:example.com:agent:support" } }, "example_1": { "summary": "An agent with too little history to score.", "value": { "agentId": "did:web:example.com:agent:new" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Reputation for an agent.", "value": { "reputation": { "agentId": "did:web:example.com:agent:support", "samples": 412, "reputationScoreBps": 8730, "avgModulationBps": -120, "avgConfidenceBps": 7400, "calibrationSamples": 96, "calibrationAccuracyBps": 8100, "trend": "improving", "firstSeen": "2026-06-02T09:14:00.000Z", "lastSeen": "2026-09-01T18:22:00.000Z" } } }, "example_1": { "summary": "An agent with too little history to score.", "value": { "reputation": { "agentId": "did:web:example.com:agent:new", "samples": 2, "reputationScoreBps": null, "avgModulationBps": null, "avgConfidenceBps": null, "calibrationSamples": 0, "calibrationAccuracyBps": null, "trend": "insufficient_data", "firstSeen": "2026-08-30T11:00:00.000Z", "lastSeen": "2026-08-31T07:45:00.000Z" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.oracle.price": { "post": { "operationId": "nexus_oracle_price", "summary": "Price an agent action by risk, returning modulation, escrow and confidence.", "x-trustvice-description-key": "actions.nexus.oracle.price.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "actionDescription": { "type": "string", "minLength": 1, "maxLength": 2000 }, "agentId": { "type": "string", "maxLength": 200 } }, "required": [ "actionDescription" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Price a risky action.", "value": { "actionDescription": "transfer funds to an external account", "agentId": "agent_1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Price a risky action.", "value": { "id": "prc_1", "priceCents": 250, "modulationBps": 7500, "confidenceBps": 8000 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.oracle.use" ] }, { "OAuth2": [ "nexus.oracle.use" ] }, { "WorkspaceApiKey": [ "nexus.oracle.use" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.oracle.policy.set": { "post": { "operationId": "nexus_oracle_policy_set", "summary": "Set the workspace's Oracle base price and risk multiplier.", "x-trustvice-description-key": "actions.nexus.oracle.policy.set.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "basePriceCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "riskMultiplierBps": { "type": "integer", "minimum": 0, "maximum": 100000 } }, "required": [ "basePriceCents", "riskMultiplierBps" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Set the pricing policy.", "value": { "basePriceCents": 250, "riskMultiplierBps": 3000 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Set the pricing policy.", "value": { "policy": { "basePriceCents": 250, "riskMultiplierBps": 3000 } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.oracle.manage" ] }, { "OAuth2": [ "nexus.oracle.manage" ] }, { "WorkspaceApiKey": [ "nexus.oracle.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.oracle.calibration.feedback": { "post": { "operationId": "nexus_oracle_calibration_feedback", "summary": "Report whether a price Oracle quoted turned out accurate.", "x-trustvice-description-key": "actions.nexus.oracle.calibration.feedback.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "pricingId": { "type": "string", "minLength": 1 }, "observedOutcome": { "type": "string", "minLength": 1, "maxLength": 200 }, "note": { "type": "string", "maxLength": 2000 } }, "required": [ "pricingId", "observedOutcome" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Close the calibration loop.", "value": { "pricingId": "prc_1", "observedOutcome": "accurate" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Close the calibration loop.", "value": { "id": "cal_1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.oracle.use" ] }, { "OAuth2": [ "nexus.oracle.use" ] }, { "WorkspaceApiKey": [ "nexus.oracle.use" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.oracle.model.pin": { "post": { "operationId": "nexus_oracle_model_pin", "summary": "Pin the Oracle pricing model version for the workspace.", "x-trustvice-description-key": "actions.nexus.oracle.model.pin.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "modelId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "modelId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Pin a model.", "value": { "modelId": "risk-keyword-v1-strict" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Pin a model.", "value": { "pinnedModelId": "risk-keyword-v1-strict" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.oracle.manage" ] }, { "OAuth2": [ "nexus.oracle.manage" ] }, { "WorkspaceApiKey": [ "nexus.oracle.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.oracle.source.add": { "post": { "operationId": "nexus_oracle_source_add", "summary": "Record an external reputation source for Oracle.", "x-trustvice-description-key": "actions.nexus.oracle.source.add.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "url": { "type": "string", "format": "uri" }, "kind": { "type": "string", "maxLength": 120 } }, "required": [ "name", "url" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Record a source.", "value": { "name": "Partner reputation", "url": "https://example.test/rep" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Record a source.", "value": { "id": "src_1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.oracle.manage" ] }, { "OAuth2": [ "nexus.oracle.manage" ] }, { "WorkspaceApiKey": [ "nexus.oracle.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.oracle.graphql": { "post": { "operationId": "nexus_oracle_graphql", "summary": "Query the Oracle read surface (policy, pricings, reputation).", "x-trustvice-description-key": "actions.nexus.oracle.graphql.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 8000 }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "query" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Query Oracle.", "value": { "query": "{ pricings { id } }" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Query Oracle.", "value": { "data": { "pricings": [] } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.oracle.use" ] }, { "OAuth2": [ "nexus.oracle.use" ] }, { "WorkspaceApiKey": [ "nexus.oracle.use" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.charter.publish": { "post": { "operationId": "nexus_charter_publish", "summary": "Publish a charter version for a publisher.", "x-trustvice-description-key": "actions.nexus.charter.publish.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "publisher": { "type": "string", "minLength": 1, "maxLength": 200 }, "rules": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "publisher" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Publish terms.", "value": { "publisher": "acme", "rules": { "retention": "30d" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Publish terms.", "value": { "id": "cht_1", "version": 1 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.charter.manage" ] }, { "OAuth2": [ "nexus.charter.manage" ] }, { "WorkspaceApiKey": [ "nexus.charter.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.charter.validate": { "post": { "operationId": "nexus_charter_validate", "summary": "Validate a set of charter rules without publishing them.", "x-trustvice-description-key": "actions.nexus.charter.validate.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "rules": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "rules" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Validate rules.", "value": { "rules": { "retention": "30d" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Validate rules.", "value": { "valid": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.charter.use" ] }, { "OAuth2": [ "nexus.charter.use" ] }, { "WorkspaceApiKey": [ "nexus.charter.use" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.charter.audit.request": { "post": { "operationId": "nexus_charter_audit_request", "summary": "Request an audit of a publisher's charter.", "x-trustvice-description-key": "actions.nexus.charter.audit.request.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "publisher": { "type": "string", "minLength": 1, "maxLength": 200 }, "scope": { "type": "string", "maxLength": 200 } }, "required": [ "publisher" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Request an audit.", "value": { "publisher": "acme", "scope": "terms" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Request an audit.", "value": { "id": "aud_1", "status": "requested" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.charter.use" ] }, { "OAuth2": [ "nexus.charter.use" ] }, { "WorkspaceApiKey": [ "nexus.charter.use" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.charter.graphql": { "post": { "operationId": "nexus_charter_graphql", "summary": "Query the Charter read surface (charters, audits).", "x-trustvice-description-key": "actions.nexus.charter.graphql.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 8000 }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "query" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Query Charter.", "value": { "query": "{ charters { id } }" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Query Charter.", "value": { "data": { "charters": [] } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.charter.use" ] }, { "OAuth2": [ "nexus.charter.use" ] }, { "WorkspaceApiKey": [ "nexus.charter.use" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.compass.verify": { "post": { "operationId": "nexus_compass_verify", "summary": "Verify that a proposed action matches the user's stated request.", "x-trustvice-description-key": "actions.nexus.compass.verify.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userRequest": { "type": "string", "minLength": 1, "maxLength": 4000 }, "proposedAction": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "userRequest" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify an intent.", "value": { "userRequest": "book a flight under $500", "proposedAction": { "kind": "purchase", "amount": 480 } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Verify an intent.", "value": { "id": "ver_1", "verdict": "aligned" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.compass.use" ] }, { "OAuth2": [ "nexus.compass.use" ] }, { "WorkspaceApiKey": [ "nexus.compass.use" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.compass.verify.explain": { "post": { "operationId": "nexus_compass_verify_explain", "summary": "Explain a stored Compass verification.", "x-trustvice-description-key": "actions.nexus.compass.verify.explain.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "verificationId": { "type": "string", "minLength": 1 } }, "required": [ "verificationId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Explain a verdict.", "value": { "verificationId": "ver_1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Explain a verdict.", "value": { "factors": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.compass.use" ] }, { "OAuth2": [ "nexus.compass.use" ] }, { "WorkspaceApiKey": [ "nexus.compass.use" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.compass.policy.set": { "post": { "operationId": "nexus_compass_policy_set", "summary": "Set the Compass review and deny thresholds.", "x-trustvice-description-key": "actions.nexus.compass.policy.set.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reviewThresholdBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "denyThresholdBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "autoDenyOnRisk": { "type": "boolean" } }, "required": [ "reviewThresholdBps", "denyThresholdBps" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Set thresholds.", "value": { "reviewThresholdBps": 7000, "denyThresholdBps": 8500 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Set thresholds.", "value": { "policy": { "reviewThresholdBps": 7000 } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.compass.manage" ] }, { "OAuth2": [ "nexus.compass.manage" ] }, { "WorkspaceApiKey": [ "nexus.compass.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.compass.hitl.escalate": { "post": { "operationId": "nexus_compass_hitl_escalate", "summary": "Escalate a verification to a human reviewer.", "x-trustvice-description-key": "actions.nexus.compass.hitl.escalate.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "verificationId": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "maxLength": 2000 } }, "required": [ "verificationId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Escalate to a human.", "value": { "verificationId": "ver_1", "reason": "ambiguous intent" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Escalate to a human.", "value": { "id": "esc_1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.compass.use" ] }, { "OAuth2": [ "nexus.compass.use" ] }, { "WorkspaceApiKey": [ "nexus.compass.use" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.compass.model.pin": { "post": { "operationId": "nexus_compass_model_pin", "summary": "Pin the Compass matching model version.", "x-trustvice-description-key": "actions.nexus.compass.model.pin.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "modelId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "modelId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Pin a model.", "value": { "modelId": "intent-align-v1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Pin a model.", "value": { "pinnedModelId": "intent-align-v1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.compass.manage" ] }, { "OAuth2": [ "nexus.compass.manage" ] }, { "WorkspaceApiKey": [ "nexus.compass.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.compass.graphql": { "post": { "operationId": "nexus_compass_graphql", "summary": "Query the Compass read surface (verifications, policy, escalations).", "x-trustvice-description-key": "actions.nexus.compass.graphql.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 8000 }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "query" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Query Compass.", "value": { "query": "{ verifications { id } }" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Query Compass.", "value": { "data": { "verifications": [] } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.compass.use" ] }, { "OAuth2": [ "nexus.compass.use" ] }, { "WorkspaceApiKey": [ "nexus.compass.use" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.ledger.verify": { "post": { "operationId": "nexus_ledger_verify", "summary": "Verify an action claim and mint its receipt.", "x-trustvice-description-key": "actions.nexus.ledger.verify.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "actionClaim": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "maxLength": 512 }, "actionId": { "type": "string", "maxLength": 200 }, "evidence": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "subject" ], "additionalProperties": {} } }, "required": [ "actionClaim" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify a claim.", "value": { "actionClaim": { "subject": "did:tv:a", "actionId": "act_1" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Verify a claim.", "value": { "verification": { "id": "lv_1" }, "receipt": { "id": "rcpt_1" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.ledger.use" ] }, { "OAuth2": [ "nexus.ledger.use" ] }, { "WorkspaceApiKey": [ "nexus.ledger.use" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.ledger.verifier.create": { "post": { "operationId": "nexus_ledger_verifier_create", "summary": "Register a custom Ledger verifier.", "x-trustvice-description-key": "actions.nexus.ledger.verifier.create.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "definition": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Add a verifier.", "value": { "name": "Invoice checks", "definition": { "requires": [ "subject" ] } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Add a verifier.", "value": { "verifierId": "lvf_1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.ledger.manage" ] }, { "OAuth2": [ "nexus.ledger.manage" ] }, { "WorkspaceApiKey": [ "nexus.ledger.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.ledger.locker.connect": { "post": { "operationId": "nexus_ledger_locker_connect", "summary": "Connect an external receipt locker.", "x-trustvice-description-key": "actions.nexus.ledger.locker.connect.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "endpoint": { "type": "string", "format": "uri" } }, "required": [ "name", "endpoint" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Connect a locker.", "value": { "name": "Archive", "endpoint": "https://example.test/locker" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Connect a locker.", "value": { "id": "conn_1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.ledger.manage" ] }, { "OAuth2": [ "nexus.ledger.manage" ] }, { "WorkspaceApiKey": [ "nexus.ledger.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.ledger.graphql": { "post": { "operationId": "nexus_ledger_graphql", "summary": "Query the Ledger read surface (receipts).", "x-trustvice-description-key": "actions.nexus.ledger.graphql.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 8000 }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "query" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Query Ledger.", "value": { "query": "{ receipts { id } }" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Query Ledger.", "value": { "data": { "receipts": [] } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.ledger.use" ] }, { "OAuth2": [ "nexus.ledger.use" ] }, { "WorkspaceApiKey": [ "nexus.ledger.use" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.lattice.delegation.publish": { "post": { "operationId": "nexus_lattice_delegation_publish", "summary": "Publish a delegation from one agent to another.", "x-trustvice-description-key": "actions.nexus.lattice.delegation.publish.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sourceAgent": { "type": "string", "minLength": 1, "maxLength": 400 }, "targetAgent": { "type": "string", "minLength": 1, "maxLength": 400 }, "actionClass": { "type": "string", "maxLength": 200 }, "scopes": { "type": "array", "items": { "type": "string" } }, "expiration": { "type": "string" } }, "required": [ "sourceAgent", "targetAgent" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Publish a delegation.", "value": { "sourceAgent": "did:tv:a", "targetAgent": "did:tv:b", "actionClass": "read", "expiration": "2027-01-01T00:00:00.000Z" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Publish a delegation.", "value": { "id": "del_1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.lattice.manage" ] }, { "OAuth2": [ "nexus.lattice.manage" ] }, { "WorkspaceApiKey": [ "nexus.lattice.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.lattice.path.find": { "post": { "operationId": "nexus_lattice_path_find", "summary": "Find a delegation path between two agents.", "x-trustvice-description-key": "actions.nexus.lattice.path.find.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sourceAgent": { "type": "string", "minLength": 1, "maxLength": 400 }, "targetAgent": { "type": "string", "minLength": 1, "maxLength": 400 } }, "required": [ "sourceAgent", "targetAgent" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Find a path.", "value": { "sourceAgent": "did:tv:a", "targetAgent": "did:tv:b" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Find a path.", "value": { "found": true, "path": [ "did:tv:a", "did:tv:b" ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.lattice.use" ] }, { "OAuth2": [ "nexus.lattice.use" ] }, { "WorkspaceApiKey": [ "nexus.lattice.use" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.lattice.path.verify": { "post": { "operationId": "nexus_lattice_path_verify", "summary": "Verify that a specific delegation path is valid.", "x-trustvice-description-key": "actions.nexus.lattice.path.verify.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "path": { "minItems": 2, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "path" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify a path.", "value": { "path": [ "did:tv:a", "did:tv:b" ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Verify a path.", "value": { "valid": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.lattice.use" ] }, { "OAuth2": [ "nexus.lattice.use" ] }, { "WorkspaceApiKey": [ "nexus.lattice.use" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.lattice.federation.node.add": { "post": { "operationId": "nexus_lattice_federation_node_add", "summary": "Add a federation peer to the delegation graph.", "x-trustvice-description-key": "actions.nexus.lattice.federation.node.add.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "endpoint": { "type": "string", "format": "uri" }, "did": { "type": "string", "maxLength": 400 } }, "required": [ "name", "endpoint" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Add a peer.", "value": { "name": "Partner", "endpoint": "https://example.test/lattice" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Add a peer.", "value": { "id": "peer_1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.lattice.manage" ] }, { "OAuth2": [ "nexus.lattice.manage" ] }, { "WorkspaceApiKey": [ "nexus.lattice.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.lattice.graphql": { "post": { "operationId": "nexus_lattice_graphql", "summary": "Query the Lattice read surface (delegations, peers).", "x-trustvice-description-key": "actions.nexus.lattice.graphql.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 8000 }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "query" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Query Lattice.", "value": { "query": "{ delegations { id } }" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Query Lattice.", "value": { "data": { "delegations": [] } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.lattice.use" ] }, { "OAuth2": [ "nexus.lattice.use" ] }, { "WorkspaceApiKey": [ "nexus.lattice.use" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.sentinel.ingest": { "post": { "operationId": "nexus_sentinel_ingest", "summary": "Submit an agent request for Sentinel inspection.", "x-trustvice-description-key": "actions.nexus.sentinel.ingest.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "destination": { "type": "string", "minLength": 1, "maxLength": 2000 }, "agentId": { "type": "string", "maxLength": 200 }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "destination" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Inspect a request.", "value": { "destination": "https://example.test/api", "agentId": "agent_1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Inspect a request.", "value": { "id": "evt_1", "verdict": "clean" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.sentinel.use" ] }, { "OAuth2": [ "nexus.sentinel.use" ] }, { "WorkspaceApiKey": [ "nexus.sentinel.use" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.sentinel.policy.create": { "post": { "operationId": "nexus_sentinel_policy_create", "summary": "Create a Sentinel traffic policy.", "x-trustvice-description-key": "actions.nexus.sentinel.policy.create.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "pattern": { "type": "string", "maxLength": 2000 } }, "required": [ "name" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Create a policy.", "value": { "name": "Block exfil", "pattern": "example.test" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Create a policy.", "value": { "id": "spol_1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.sentinel.manage" ] }, { "OAuth2": [ "nexus.sentinel.manage" ] }, { "WorkspaceApiKey": [ "nexus.sentinel.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.sentinel.classifier.create": { "post": { "operationId": "nexus_sentinel_classifier_create", "summary": "Register a custom Sentinel classifier.", "x-trustvice-description-key": "actions.nexus.sentinel.classifier.create.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "definition": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Add a classifier.", "value": { "name": "PII", "definition": { "match": "ssn" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Add a classifier.", "value": { "classifierId": "cls_1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.sentinel.manage" ] }, { "OAuth2": [ "nexus.sentinel.manage" ] }, { "WorkspaceApiKey": [ "nexus.sentinel.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.sentinel.graphql": { "post": { "operationId": "nexus_sentinel_graphql", "summary": "Query the Sentinel read surface (events, incidents).", "x-trustvice-description-key": "actions.nexus.sentinel.graphql.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 8000 }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "query" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Query Sentinel.", "value": { "query": "{ events { id } }" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Query Sentinel.", "value": { "data": { "events": [] } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.sentinel.use" ] }, { "OAuth2": [ "nexus.sentinel.use" ] }, { "WorkspaceApiKey": [ "nexus.sentinel.use" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.tribunal.dispute.file": { "post": { "operationId": "nexus_tribunal_dispute_file", "summary": "File a dispute against another agent.", "x-trustvice-description-key": "actions.nexus.tribunal.dispute.file.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "opposingAgent": { "type": "string", "minLength": 1, "maxLength": 400 }, "transactionReference": { "type": "string", "maxLength": 200 }, "claim": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "opposingAgent" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "File a dispute.", "value": { "opposingAgent": "did:tv:b", "transactionReference": "txn_1", "claim": { "reason": "undelivered" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "File a dispute.", "value": { "id": "dsp_1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.tribunal.use" ] }, { "OAuth2": [ "nexus.tribunal.use" ] }, { "WorkspaceApiKey": [ "nexus.tribunal.use" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.tribunal.adjudicator.connect": { "post": { "operationId": "nexus_tribunal_adjudicator_connect", "summary": "Connect an adjudicator pool.", "x-trustvice-description-key": "actions.nexus.tribunal.adjudicator.connect.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "endpoint": { "type": "string", "format": "uri" } }, "required": [ "name", "endpoint" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Connect a pool.", "value": { "name": "Panel", "endpoint": "https://example.test/adjudicators" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Connect a pool.", "value": { "id": "adj_1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.tribunal.manage" ] }, { "OAuth2": [ "nexus.tribunal.manage" ] }, { "WorkspaceApiKey": [ "nexus.tribunal.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.tribunal.legal-framework.set": { "post": { "operationId": "nexus_tribunal_legal-framework_set", "summary": "Set the workspace's governing legal framework.", "x-trustvice-description-key": "actions.nexus.tribunal.legal-framework.set.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "legalFramework": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "legalFramework" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Set the framework.", "value": { "legalFramework": "ny-arbitration" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Set the framework.", "value": { "legalFramework": "ny-arbitration" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.tribunal.manage" ] }, { "OAuth2": [ "nexus.tribunal.manage" ] }, { "WorkspaceApiKey": [ "nexus.tribunal.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.tribunal.graphql": { "post": { "operationId": "nexus_tribunal_graphql", "summary": "Query the Tribunal read surface (disputes, precedents).", "x-trustvice-description-key": "actions.nexus.tribunal.graphql.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 8000 }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "query" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Query Tribunal.", "value": { "query": "{ disputes { id } }" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Query Tribunal.", "value": { "data": { "disputes": [] } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.tribunal.use" ] }, { "OAuth2": [ "nexus.tribunal.use" ] }, { "WorkspaceApiKey": [ "nexus.tribunal.use" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.keyring.credential.mint": { "post": { "operationId": "nexus_keyring_credential_mint", "summary": "Mint a scoped, time-boxed credential for a target system.", "x-trustvice-description-key": "actions.nexus.keyring.credential.mint.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "targetSystem": { "type": "string", "minLength": 1, "maxLength": 200 }, "intendedAction": { "type": "string", "minLength": 1, "maxLength": 200 }, "intendedScope": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "ttl": { "type": "integer", "minimum": 60, "maximum": 86400 } }, "required": [ "targetSystem", "intendedAction" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Mint a credential.", "value": { "targetSystem": "billing", "intendedAction": "read", "ttl": 3600 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Mint a credential.", "value": { "credentialId": "krc_1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.keyring.use" ] }, { "OAuth2": [ "nexus.keyring.use" ] }, { "WorkspaceApiKey": [ "nexus.keyring.use" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.keyring.policy.create": { "post": { "operationId": "nexus_keyring_policy_create", "summary": "Create a Keyring issuance policy.", "x-trustvice-description-key": "actions.nexus.keyring.policy.create.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "type": "string", "maxLength": 120 } }, "required": [ "name" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Create a policy.", "value": { "name": "Read-only", "kind": "allow" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Create a policy.", "value": { "id": "kpol_1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.keyring.manage" ] }, { "OAuth2": [ "nexus.keyring.manage" ] }, { "WorkspaceApiKey": [ "nexus.keyring.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.keyring.vault.reference.add": { "post": { "operationId": "nexus_keyring_vault_reference_add", "summary": "Record a POINTER into your own vault. Never the secret itself.", "x-trustvice-description-key": "actions.nexus.keyring.vault.reference.add.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "ref": { "type": "string", "minLength": 1, "maxLength": 500 }, "kind": { "type": "string", "maxLength": 120 } }, "required": [ "name", "ref" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Record a reference.", "value": { "name": "Billing key", "ref": "vault://acme/billing" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Record a reference.", "value": { "masterCredentialId": "kv_1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.keyring.manage" ] }, { "OAuth2": [ "nexus.keyring.manage" ] }, { "WorkspaceApiKey": [ "nexus.keyring.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.keyring.graphql": { "post": { "operationId": "nexus_keyring_graphql", "summary": "Query the Keyring read surface (credentials, policies).", "x-trustvice-description-key": "actions.nexus.keyring.graphql.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 8000 }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "query" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Query Keyring.", "value": { "query": "{ credentials { id } }" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Query Keyring.", "value": { "data": { "credentials": [] } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.keyring.use" ] }, { "OAuth2": [ "nexus.keyring.use" ] }, { "WorkspaceApiKey": [ "nexus.keyring.use" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.imprint.stamp.issue": { "post": { "operationId": "nexus_imprint_stamp_issue", "summary": "Issue a provenance stamp over a payload.", "x-trustvice-description-key": "actions.nexus.imprint.stamp.issue.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "license": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "payload" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Issue a stamp.", "value": { "payload": { "text": "hello" }, "license": { "policyId": "ipol_1" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Issue a stamp.", "value": { "stampId": "stm_1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.imprint.use" ] }, { "OAuth2": [ "nexus.imprint.use" ] }, { "WorkspaceApiKey": [ "nexus.imprint.use" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.imprint.stamp.verify": { "post": { "operationId": "nexus_imprint_stamp_verify", "summary": "Verify a payload against its Imprint stamp.", "x-trustvice-description-key": "actions.nexus.imprint.stamp.verify.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "payload" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify a stamp.", "value": { "payload": { "text": "hello" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Verify a stamp.", "value": { "valid": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.imprint.use" ] }, { "OAuth2": [ "nexus.imprint.use" ] }, { "WorkspaceApiKey": [ "nexus.imprint.use" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.imprint.policy.create": { "post": { "operationId": "nexus_imprint_policy_create", "summary": "Create an Imprint licensing policy.", "x-trustvice-description-key": "actions.nexus.imprint.policy.create.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "terms": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Create a policy.", "value": { "name": "Attribution", "terms": { "reuse": "attribution" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Create a policy.", "value": { "policyId": "ipol_1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.imprint.manage" ] }, { "OAuth2": [ "nexus.imprint.manage" ] }, { "WorkspaceApiKey": [ "nexus.imprint.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.imprint.runtime.register": { "post": { "operationId": "nexus_imprint_runtime_register", "summary": "Register a runtime that may issue Imprint stamps.", "x-trustvice-description-key": "actions.nexus.imprint.runtime.register.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "endpoint": { "type": "string", "format": "uri" } }, "required": [ "name", "endpoint" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Register a runtime.", "value": { "name": "Editor", "endpoint": "https://example.test/runtime" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Register a runtime.", "value": { "id": "irt_1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.imprint.manage" ] }, { "OAuth2": [ "nexus.imprint.manage" ] }, { "WorkspaceApiKey": [ "nexus.imprint.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.imprint.graphql": { "post": { "operationId": "nexus_imprint_graphql", "summary": "Query the Imprint read surface (stamps, policies).", "x-trustvice-description-key": "actions.nexus.imprint.graphql.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 8000 }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "query" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Query Imprint.", "value": { "query": "{ stamps { id } }" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Query Imprint.", "value": { "data": { "stamps": [] } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.imprint.use" ] }, { "OAuth2": [ "nexus.imprint.use" ] }, { "WorkspaceApiKey": [ "nexus.imprint.use" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.underwriter.premium.quote": { "post": { "operationId": "nexus_underwriter_premium_quote", "summary": "Quote a premium for covering an action. A price, not a commitment.", "x-trustvice-description-key": "actions.nexus.underwriter.premium.quote.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "coverageCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "action": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Quote a premium.", "value": { "coverageCents": 10000, "action": { "kind": "transfer" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Quote a premium.", "value": { "premiumCents": 200 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.underwriter.use" ] }, { "OAuth2": [ "nexus.underwriter.use" ] }, { "WorkspaceApiKey": [ "nexus.underwriter.use" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.underwriter.coverage.bind": { "post": { "operationId": "nexus_underwriter_coverage_bind", "summary": "Bind coverage against a policy — this creates a warranty.", "x-trustvice-description-key": "actions.nexus.underwriter.coverage.bind.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "policyId": { "type": "string", "minLength": 1 }, "transactionId": { "type": "string", "minLength": 1, "maxLength": 200 }, "coverageCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "policyId", "transactionId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Bind coverage.", "value": { "policyId": "upol_1", "transactionId": "txn_1", "coverageCents": 10000 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Bind coverage.", "value": { "warrantyId": "wnt_1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.underwriter.use" ] }, { "OAuth2": [ "nexus.underwriter.use" ] }, { "WorkspaceApiKey": [ "nexus.underwriter.use" ] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.underwriter.claim.file": { "post": { "operationId": "nexus_underwriter_claim_file", "summary": "File a claim against a bound warranty.", "x-trustvice-description-key": "actions.nexus.underwriter.claim.file.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "warrantyId": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "warrantyId", "reason" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "File a claim.", "value": { "warrantyId": "wnt_1", "reason": "undelivered" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "File a claim.", "value": { "claimId": "clm_1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.underwriter.use" ] }, { "OAuth2": [ "nexus.underwriter.use" ] }, { "WorkspaceApiKey": [ "nexus.underwriter.use" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.underwriter.policy.create": { "post": { "operationId": "nexus_underwriter_policy_create", "summary": "Create a coverage policy with its rate and ceiling.", "x-trustvice-description-key": "actions.nexus.underwriter.policy.create.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "baseRateBps": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "maxCoverageCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "name" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Create a policy.", "value": { "name": "Standard", "baseRateBps": 200, "maxCoverageCents": 500000 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Create a policy.", "value": { "policyId": "upol_1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.underwriter.manage" ] }, { "OAuth2": [ "nexus.underwriter.manage" ] }, { "WorkspaceApiKey": [ "nexus.underwriter.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.underwriter.backend.connect": { "post": { "operationId": "nexus_underwriter_backend_connect", "summary": "Connect a reinsurance backend.", "x-trustvice-description-key": "actions.nexus.underwriter.backend.connect.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "endpoint": { "type": "string", "format": "uri" } }, "required": [ "name", "endpoint" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Connect a backend.", "value": { "name": "Reinsurer", "endpoint": "https://example.test/reinsurance" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Connect a backend.", "value": { "id": "ubk_1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.underwriter.manage" ] }, { "OAuth2": [ "nexus.underwriter.manage" ] }, { "WorkspaceApiKey": [ "nexus.underwriter.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/nexus.underwriter.graphql": { "post": { "operationId": "nexus_underwriter_graphql", "summary": "Query the Underwriter read surface (warranties, claims).", "x-trustvice-description-key": "actions.nexus.underwriter.graphql.description", "tags": [ "nexus" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 8000 }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "query" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Query Underwriter.", "value": { "query": "{ claims { id } }" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Query Underwriter.", "value": { "data": { "claims": [] } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "nexus.underwriter.use" ] }, { "OAuth2": [ "nexus.underwriter.use" ] }, { "WorkspaceApiKey": [ "nexus.underwriter.use" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/vector.registry.search": { "post": { "operationId": "vector_registry_search", "summary": "Search the public Vector agent registry.", "x-trustvice-description-key": "actions.vector.registry.search.description", "tags": [ "vector" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "q": { "description": "Free-text query.", "type": "string" }, "limit": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Find registered agents.", "value": { "q": "support agent" } }, "example_1": { "summary": "An empty query returns nothing, not everything.", "value": { "q": "" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Find registered agents.", "value": { "entries": [ { "id": "ag_demo_1", "kind": "agent", "name": "Support Agent", "description": "Answers tier-1 support questions over the public docs.", "endpoint": "https://agents.example.com/support", "tags": [ "support", "docs" ], "createdAt": "2026-05-04T10:00:00.000Z" } ], "count": 1 } }, "example_1": { "summary": "An empty query returns nothing, not everything.", "value": { "entries": [], "count": 0 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/vector.registry.entry.get": { "post": { "operationId": "vector_registry_entry_get", "summary": "Get a single Vector registry entry by id.", "x-trustvice-description-key": "actions.vector.registry.entry.get.description", "tags": [ "vector" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Resolve a registry entry.", "value": { "id": "ag_demo_1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Resolve a registry entry.", "value": { "entry": { "id": "ag_demo_1", "kind": "agent", "name": "Support Agent", "description": "Answers tier-1 support questions over the public docs.", "endpoint": "https://agents.example.com/support", "tags": [ "support", "docs" ], "createdAt": "2026-05-04T10:00:00.000Z" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/vector.pricing.get": { "post": { "operationId": "vector_pricing_get", "summary": "Look up Vector public pricing.", "x-trustvice-description-key": "actions.vector.pricing.get.description", "tags": [ "vector" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read Vector pricing.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read Vector pricing.", "value": { "product": "vector", "currency": "USD", "note": "Display currency varies by region (EUR/GBP/USD); the amount is identical.", "tiers": [ { "tier": "vector_free", "monthlyUsd": 0 }, { "tier": "vector_starter", "monthlyUsd": 59 }, { "tier": "vector_pro", "monthlyUsd": 179 }, { "tier": "vector_enterprise", "monthlyUsd": null } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/vector.mcp.servers.list": { "post": { "operationId": "vector_mcp_servers_list", "summary": "List the MCP servers in the public Vector registry.", "x-trustvice-description-key": "actions.vector.mcp.servers.list.description", "tags": [ "vector" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Discover MCP servers.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Discover MCP servers.", "value": { "servers": [ { "id": "mcp_docs_1", "kind": "mcp_server", "name": "Docs MCP", "description": "Read-only MCP server over the public documentation.", "endpoint": "https://mcp.example.com/docs", "tags": [ "docs", "read-only" ], "createdAt": "2026-05-04T10:00:00.000Z" } ], "count": 1 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/vector.catalog.get": { "post": { "operationId": "vector_catalog_get", "summary": "Get the workspace's Vector product catalogue.", "x-trustvice-description-key": "actions.vector.catalog.get.description", "tags": [ "vector" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "List Vector products.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "List Vector products.", "value": { "products": [ { "product": "registry", "basePath": "/v1/vector/registry", "mcpEndpoint": "/v1/vector/registry/mcp" }, { "product": "mirror", "basePath": "/v1/vector/mirror", "mcpEndpoint": "/v1/vector/mirror/mcp" } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/vector.registry.register": { "post": { "operationId": "vector_registry_register", "summary": "Register an agent, tool, MCP server or service in the Vector registry.", "x-trustvice-description-key": "actions.vector.registry.register.description", "tags": [ "vector" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "kind": { "type": "string", "enum": [ "agent", "tool", "mcp_server", "service" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "endpoint": { "type": "string", "format": "uri" }, "visibility": { "default": "private", "type": "string", "enum": [ "private", "public" ] }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "kind", "name" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Register an agent.", "value": { "kind": "agent", "name": "Support Agent", "description": "Answers tier-1 support questions.", "visibility": "private" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Register an agent.", "value": { "entry": { "id": "ag_1", "kind": "agent", "name": "Support Agent", "visibility": "private" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "vector.registry.register" ] }, { "OAuth2": [ "vector.registry.register" ] }, { "WorkspaceApiKey": [ "vector.registry.register" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/vector.persona.create": { "post": { "operationId": "vector_persona_create", "summary": "Create a Vector persona — a named attribute + scope set an agent can act under.", "x-trustvice-description-key": "actions.vector.persona.create.description", "tags": [ "vector" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "attributes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "name" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Create a persona.", "value": { "name": "Auditor", "attributes": { "role": "auditor" }, "scopes": [ "read" ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Create a persona.", "value": { "id": "per_1", "name": "Auditor" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "vector.persona.manage" ] }, { "OAuth2": [ "vector.persona.manage" ] }, { "WorkspaceApiKey": [ "vector.persona.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/vector.persona.select": { "post": { "operationId": "vector_persona_select", "summary": "Resolve a persona by id for the calling agent.", "x-trustvice-description-key": "actions.vector.persona.select.description", "tags": [ "vector" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "personaId": { "type": "string", "minLength": 1 } }, "required": [ "personaId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Select a persona.", "value": { "personaId": "per_1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Select a persona.", "value": { "persona": { "id": "per_1", "name": "Auditor" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "vector.persona.manage" ] }, { "OAuth2": [ "vector.persona.manage" ] }, { "WorkspaceApiKey": [ "vector.persona.manage" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/vector.policy.create": { "post": { "operationId": "vector_policy_create", "summary": "Create a Vector egress policy.", "x-trustvice-description-key": "actions.vector.policy.create.description", "tags": [ "vector" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "effect": { "default": "deny_by_default", "type": "string", "enum": [ "deny_by_default", "allow_by_default" ] }, "rules": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Create a policy.", "value": { "name": "Egress allowlist", "effect": "deny_by_default", "rules": { "allow": [ "https://example.test" ] } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Create a policy.", "value": { "id": "pol_1", "name": "Egress allowlist" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "vector.policy.manage" ] }, { "OAuth2": [ "vector.policy.manage" ] }, { "WorkspaceApiKey": [ "vector.policy.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/vector.policy.evaluate": { "post": { "operationId": "vector_policy_evaluate", "summary": "Ask whether a destination is permitted by the workspace's Vector policies.", "x-trustvice-description-key": "actions.vector.policy.evaluate.description", "tags": [ "vector" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "destination": { "type": "string", "minLength": 1 } }, "required": [ "destination" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Evaluate a destination.", "value": { "destination": "https://example.test/agent" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Evaluate a destination.", "value": { "allowed": false, "reason": "deny_by_default" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "vector.policy.evaluate" ] }, { "OAuth2": [ "vector.policy.evaluate" ] }, { "WorkspaceApiKey": [ "vector.policy.evaluate" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/vector.vault.credential.create": { "post": { "operationId": "vector_vault_credential_create", "summary": "Record a credential REFERENCE in the Vector vault. Never the secret itself.", "x-trustvice-description-key": "actions.vector.vault.credential.create.description", "tags": [ "vector" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "credType": { "default": "api_key", "type": "string", "enum": [ "api_key", "oauth", "reference" ] } }, "required": [ "name" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Record a credential reference.", "value": { "name": "Billing API", "credType": "api_key" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Record a credential reference.", "value": { "id": "cred_1", "name": "Billing API" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "vector.vault.manage" ] }, { "OAuth2": [ "vector.vault.manage" ] }, { "WorkspaceApiKey": [ "vector.vault.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/vector.conduit.connection.create": { "post": { "operationId": "vector_conduit_connection_create", "summary": "Create a Vector conduit connection to an upstream provider.", "x-trustvice-description-key": "actions.vector.conduit.connection.create.description", "tags": [ "vector" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "provider": { "type": "string", "minLength": 1, "maxLength": 120 }, "authMode": { "default": "byo", "type": "string", "enum": [ "byo", "oauth", "none" ] }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name", "provider" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Create a connection.", "value": { "name": "Billing", "provider": "http", "authMode": "byo", "config": { "url": "https://example.test" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Create a connection.", "value": { "id": "con_1", "name": "Billing" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "vector.conduit.connect" ] }, { "OAuth2": [ "vector.conduit.connect" ] }, { "WorkspaceApiKey": [ "vector.conduit.connect" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/vector.cartograph.mapping.create": { "post": { "operationId": "vector_cartograph_mapping_create", "summary": "Create a Cartograph field mapping between two schemas.", "x-trustvice-description-key": "actions.vector.cartograph.mapping.create.description", "tags": [ "vector" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "sourceSchema": { "default": "", "type": "string", "maxLength": 200 }, "targetSchema": { "default": "", "type": "string", "maxLength": 200 }, "fieldMap": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": [ "name" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Create a mapping.", "value": { "name": "CRM → ledger", "sourceSchema": "crm.v1", "targetSchema": "ledger.v2", "fieldMap": { "customer_id": "account" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Create a mapping.", "value": { "id": "map_1", "name": "CRM → ledger" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "vector.cartograph.manage" ] }, { "OAuth2": [ "vector.cartograph.manage" ] }, { "WorkspaceApiKey": [ "vector.cartograph.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/vector.cartograph.translate": { "post": { "operationId": "vector_cartograph_translate", "summary": "Translate one record through a Cartograph mapping.", "x-trustvice-description-key": "actions.vector.cartograph.translate.description", "tags": [ "vector" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "mappingId": { "type": "string", "minLength": 1 }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "mappingId", "payload" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Translate a record.", "value": { "mappingId": "map_1", "payload": { "account": "A-1" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Translate a record.", "value": { "translated": { "customer_id": "A-1" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "vector.cartograph.translate" ] }, { "OAuth2": [ "vector.cartograph.translate" ] }, { "WorkspaceApiKey": [ "vector.cartograph.translate" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/vector.cartograph.batch": { "post": { "operationId": "vector_cartograph_batch", "summary": "Translate many records through a Cartograph mapping in one call.", "x-trustvice-description-key": "actions.vector.cartograph.batch.description", "tags": [ "vector" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "mappingId": { "type": "string", "minLength": 1 }, "records": { "minItems": 1, "maxItems": 5000, "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "required": [ "mappingId", "records" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Translate a batch.", "value": { "mappingId": "map_1", "records": [ { "account": "A-1" }, { "account": "A-2" } ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Translate a batch.", "value": { "translated": [ { "customer_id": "A-1" }, { "customer_id": "A-2" } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "vector.cartograph.translate" ] }, { "OAuth2": [ "vector.cartograph.translate" ] }, { "WorkspaceApiKey": [ "vector.cartograph.translate" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "expensive", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/vector.compliance.declare": { "post": { "operationId": "vector_compliance_declare", "summary": "Declare a compliance framework and its constraints for the workspace.", "x-trustvice-description-key": "actions.vector.compliance.declare.description", "tags": [ "vector" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "framework": { "type": "string", "minLength": 1, "maxLength": 120 }, "constraints": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "framework" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Declare GDPR.", "value": { "framework": "gdpr", "constraints": { "residency": "eu" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Declare GDPR.", "value": { "id": "dec_1", "framework": "gdpr" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "vector.compliance.declare" ] }, { "OAuth2": [ "vector.compliance.declare" ] }, { "WorkspaceApiKey": [ "vector.compliance.declare" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/vector.compliance.check": { "post": { "operationId": "vector_compliance_check", "summary": "Check a region against a declared compliance framework.", "x-trustvice-description-key": "actions.vector.compliance.check.description", "tags": [ "vector" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "framework": { "type": "string", "minLength": 1, "maxLength": 120 }, "region": { "type": "string", "minLength": 1, "maxLength": 60 } }, "required": [ "framework", "region" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Check a region.", "value": { "framework": "gdpr", "region": "eu" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Check a region.", "value": { "compliant": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "vector.compliance.check" ] }, { "OAuth2": [ "vector.compliance.check" ] }, { "WorkspaceApiKey": [ "vector.compliance.check" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/vector.routing.route.create": { "post": { "operationId": "vector_routing_route_create", "summary": "Create a Vector route — an intent and the candidates that can serve it.", "x-trustvice-description-key": "actions.vector.routing.route.create.description", "tags": [ "vector" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "intent": { "type": "string", "minLength": 1, "maxLength": 200 }, "strategy": { "default": "lowest_cost", "type": "string", "enum": [ "lowest_cost", "lowest_latency", "round_robin" ] }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "string", "minLength": 1 }, "costUm": { "type": "number" } }, "required": [ "target" ], "additionalProperties": {} } } }, "required": [ "intent" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Create a route.", "value": { "intent": "summarise", "strategy": "lowest_cost", "candidates": [ { "target": "https://example.test/a", "costUm": 1 } ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Create a route.", "value": { "id": "rt_1", "intent": "summarise" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "vector.routing.manage" ] }, { "OAuth2": [ "vector.routing.manage" ] }, { "WorkspaceApiKey": [ "vector.routing.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/vector.routing.resolve": { "post": { "operationId": "vector_routing_resolve", "summary": "Resolve an intent to the target Vector selects for it.", "x-trustvice-description-key": "actions.vector.routing.resolve.description", "tags": [ "vector" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "intent": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "intent" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Resolve an intent.", "value": { "intent": "summarise" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Resolve an intent.", "value": { "selected": { "target": "https://example.test/a" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "vector.routing.resolve" ] }, { "OAuth2": [ "vector.routing.resolve" ] }, { "WorkspaceApiKey": [ "vector.routing.resolve" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/pricevice.attest.price": { "post": { "operationId": "pricevice_attest_price", "summary": "Issue a Price Provenance Receipt (PPR) for a pricing decision — signed, time-anchored, input-committed, policy-conformance-checked.", "x-trustvice-description-key": "actions.pricevice.attest.price.description", "tags": [ "pricevice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "modelLabel": { "type": "string", "minLength": 1, "maxLength": 200 }, "modelSha256": { "anyOf": [ { "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" } ] }, "policyId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "inputCommitment": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "inputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] } }, "kind": { "default": "price", "type": "string", "enum": [ "price", "discount", "rebate", "quote" ] }, "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "unit": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "domain": { "type": "string", "enum": [ "saas", "goods", "services", "real_estate_sale", "real_estate_rent", "other" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 500 }, "buyerRef": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "workspaceId", "modelLabel", "amountMinor", "currency", "domain", "reference" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Attest a quoted price.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "modelLabel": "rate-card-2026Q2", "policyId": "01J9X4P9R7Z2C1A1F2A8VBJYP1", "inputCommitment": "abcd1234567890abcdef1234567890abcdef1234567890abcdef12345678abcd", "kind": "quote", "amountMinor": 1250000, "currency": "USD", "unit": "total", "domain": "saas", "reference": "Q-2026-0042", "buyerRef": "segment:mid-market" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "receipt": { "type": "object", "properties": { "version": { "type": "string", "const": "1" }, "receiptId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "type": { "type": "string", "const": "price.attest" }, "signatureKeyId": { "type": "string" }, "signature": { "type": "string" }, "body": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "version", "receiptId", "issuedAt", "type", "signatureKeyId", "signature", "body" ], "additionalProperties": {} } }, "required": [ "receipt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Attest a quoted price.", "value": { "receipt": { "version": "1", "receiptId": "01J9X4P9R7Z2C1A1F2A8VBJYV9", "issuedAt": "2026-06-10T12:00:00.000Z", "type": "price.attest", "signatureKeyId": "k1B2c3D4e5F6g7H8i9J0kA", "signature": "...", "body": {} } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "pricevice.attest" ] }, { "OAuth2": [ "pricevice.attest" ] }, { "WorkspaceApiKey": [ "pricevice.attest" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/pricevice.receipt.list": { "post": { "operationId": "pricevice_receipt_list", "summary": "List Price Provenance Receipts for a workspace (filter by domain or conformance verdict).", "x-trustvice-description-key": "actions.pricevice.receipt.list.description", "tags": [ "pricevice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "domain": { "type": "string", "enum": [ "saas", "goods", "services", "real_estate_sale", "real_estate_rent", "other" ] }, "conformance": { "type": "string", "enum": [ "within", "off_policy", "unchecked" ] } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List PPRs.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "domain": "saas" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "receipts": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "string", "const": "1" }, "receiptId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "type": { "type": "string", "const": "price.attest" }, "signatureKeyId": { "type": "string" }, "signature": { "type": "string" }, "body": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "version", "receiptId", "issuedAt", "type", "signatureKeyId", "signature", "body" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "receipts", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List PPRs.", "value": { "receipts": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "pricevice.receipts.view" ] }, { "OAuth2": [ "pricevice.receipts.view" ] }, { "WorkspaceApiKey": [ "pricevice.receipts.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/pricevice.receipt.get": { "post": { "operationId": "pricevice_receipt_get", "summary": "Get a single Price Provenance Receipt with its full seven-component body.", "x-trustvice-description-key": "actions.pricevice.receipt.get.description", "tags": [ "pricevice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "receiptId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "required": [ "workspaceId", "receiptId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read a PPR.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "receiptId": "01J9X4P9R7Z2C1A1F2A8VBJYV9" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "receipt": { "type": "object", "properties": { "version": { "type": "string", "const": "1" }, "receiptId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "type": { "type": "string", "const": "price.attest" }, "signatureKeyId": { "type": "string" }, "signature": { "type": "string" }, "body": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "version", "receiptId", "issuedAt", "type", "signatureKeyId", "signature", "body" ], "additionalProperties": {} } }, "required": [ "receipt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read a PPR.", "value": { "receipt": { "version": "1", "receiptId": "01J9X4P9R7Z2C1A1F2A8VBJYV9", "issuedAt": "2026-06-10T12:00:00.000Z", "type": "price.attest", "signatureKeyId": "k1B2c3D4e5F6g7H8i9J0kA", "signature": "...", "body": {} } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "pricevice.receipts.view" ] }, { "OAuth2": [ "pricevice.receipts.view" ] }, { "WorkspaceApiKey": [ "pricevice.receipts.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/pricevice.receipt.verify": { "post": { "operationId": "pricevice_receipt_verify", "summary": "Verify a PPR's Ed25519 signature against the published Pricevice public keys. Public — no account required. Cannot be disabled.", "x-trustvice-description-key": "actions.pricevice.receipt.verify.description", "tags": [ "pricevice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "receipt": { "type": "object", "properties": { "version": { "type": "string", "const": "1" }, "receiptId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "type": { "type": "string", "const": "price.attest" }, "signatureKeyId": { "type": "string" }, "signature": { "type": "string" }, "body": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "version", "receiptId", "issuedAt", "type", "signatureKeyId", "signature", "body" ], "additionalProperties": {} } }, "required": [ "receipt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify a PPR.", "value": { "receipt": { "version": "1", "receiptId": "01J9X4P9R7Z2C1A1F2A8VBJYV9", "issuedAt": "2026-06-10T12:00:00.000Z", "type": "price.attest", "signatureKeyId": "k1B2c3D4e5F6g7H8i9J0kA", "signature": "...", "body": {} } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "signedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "signatureKeyId": { "type": "string" }, "publishedKeyUrl": { "type": "string", "format": "uri" } }, "required": [ "ok", "signedAt", "signatureKeyId", "publishedKeyUrl" ], "additionalProperties": {} }, { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "reason": { "type": "string", "enum": [ "bad_signature", "unknown_key", "malformed_envelope" ] }, "publishedKeyUrl": { "type": "string", "format": "uri" } }, "required": [ "ok", "reason", "publishedKeyUrl" ], "additionalProperties": {} } ] }, "examples": { "example_0": { "summary": "Verify a PPR.", "value": { "ok": true, "signedAt": "2026-06-10T12:00:00.000Z", "signatureKeyId": "k1B2c3D4e5F6g7H8i9J0kA", "publishedKeyUrl": "https://api.trustvice.com/.well-known/pricevice-keys.json" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/pricevice.policy.add": { "post": { "operationId": "pricevice_policy_add", "summary": "Create a pricing policy — the declared bounds + Level-0 excluded-attributes list PPRs are conformance-checked against.", "x-trustvice-description-key": "actions.pricevice.policy.add.description", "tags": [ "pricevice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "floorMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ceilingMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "currency": { "default": "USD", "type": "string", "minLength": 3, "maxLength": 3 }, "excludedAttributes": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 100 } } }, "required": [ "workspaceId", "label" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Create a policy.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "label": "SaaS list-price band 2026", "floorMinor": 90000, "ceilingMinor": 150000, "currency": "USD", "excludedAttributes": [ "nationality", "gender" ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "policy": { "type": "object", "properties": { "policyId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "label": { "type": "string" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "floorMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ceilingMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "currency": { "type": "string" }, "excludedAttributes": { "type": "array", "items": { "type": "string" } }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "policyId", "workspaceId", "label", "version", "floorMinor", "ceilingMinor", "currency", "excludedAttributes", "isActive", "createdAt" ], "additionalProperties": {} } }, "required": [ "policy" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Create a policy.", "value": { "policy": { "policyId": "01J9X4P9R7Z2C1A1F2A8VBJYP1", "workspaceId": "ws_DEMODEFAULT0000000000", "label": "SaaS list-price band 2026", "version": 1, "floorMinor": 90000, "ceilingMinor": 150000, "currency": "USD", "excludedAttributes": [ "nationality", "gender" ], "isActive": true, "createdAt": "2026-06-10T12:00:00.000Z" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "pricevice.policies.create" ] }, { "OAuth2": [ "pricevice.policies.create" ] }, { "WorkspaceApiKey": [ "pricevice.policies.create" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/pricevice.policy.list": { "post": { "operationId": "pricevice_policy_list", "summary": "List pricing policies in a workspace.", "x-trustvice-description-key": "actions.pricevice.policy.list.description", "tags": [ "pricevice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "activeOnly": { "default": false, "type": "boolean" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List policies.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "policies": { "type": "array", "items": { "type": "object", "properties": { "policyId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "label": { "type": "string" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "floorMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ceilingMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "currency": { "type": "string" }, "excludedAttributes": { "type": "array", "items": { "type": "string" } }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "policyId", "workspaceId", "label", "version", "floorMinor", "ceilingMinor", "currency", "excludedAttributes", "isActive", "createdAt" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "policies", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List policies.", "value": { "policies": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "pricevice.policies.view" ] }, { "OAuth2": [ "pricevice.policies.view" ] }, { "WorkspaceApiKey": [ "pricevice.policies.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/pricevice.policy.get": { "post": { "operationId": "pricevice_policy_get", "summary": "Get one pricing policy.", "x-trustvice-description-key": "actions.pricevice.policy.get.description", "tags": [ "pricevice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "policyId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "required": [ "workspaceId", "policyId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read a policy.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "policyId": "01J9X4P9R7Z2C1A1F2A8VBJYP1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "policy": { "type": "object", "properties": { "policyId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "label": { "type": "string" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "floorMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ceilingMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "currency": { "type": "string" }, "excludedAttributes": { "type": "array", "items": { "type": "string" } }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "policyId", "workspaceId", "label", "version", "floorMinor", "ceilingMinor", "currency", "excludedAttributes", "isActive", "createdAt" ], "additionalProperties": {} } }, "required": [ "policy" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read a policy.", "value": { "policyId": "01J9X4P9R7Z2C1A1F2A8VBJYP1", "workspaceId": "ws_DEMODEFAULT0000000000", "label": "SaaS list-price band 2026", "version": 1, "floorMinor": 90000, "ceilingMinor": 150000, "currency": "USD", "excludedAttributes": [], "isActive": true, "createdAt": "2026-06-10T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "pricevice.policies.view" ] }, { "OAuth2": [ "pricevice.policies.view" ] }, { "WorkspaceApiKey": [ "pricevice.policies.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/pricevice.policy.update": { "post": { "operationId": "pricevice_policy_update", "summary": "Update a pricing policy (bumps the version; receipts pin the version they were checked against — history never rewrites).", "x-trustvice-description-key": "actions.pricevice.policy.update.description", "tags": [ "pricevice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "policyId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "floorMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ceilingMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "excludedAttributes": { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 100 } } }, "required": [ "workspaceId", "policyId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Update a policy.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "policyId": "01J9X4P9R7Z2C1A1F2A8VBJYP1", "ceilingMinor": 160000 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "policyId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "label": { "type": "string" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "floorMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ceilingMinor": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "currency": { "type": "string" }, "excludedAttributes": { "type": "array", "items": { "type": "string" } }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "policyId", "workspaceId", "label", "version", "floorMinor", "ceilingMinor", "currency", "excludedAttributes", "isActive", "createdAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Update a policy.", "value": { "policyId": "01J9X4P9R7Z2C1A1F2A8VBJYP1", "workspaceId": "ws_DEMODEFAULT0000000000", "label": "SaaS list-price band 2026", "version": 2, "floorMinor": 90000, "ceilingMinor": 160000, "currency": "USD", "excludedAttributes": [], "isActive": true, "createdAt": "2026-06-10T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "pricevice.policies.edit" ] }, { "OAuth2": [ "pricevice.policies.edit" ] }, { "WorkspaceApiKey": [ "pricevice.policies.edit" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/pricevice.policy.remove": { "post": { "operationId": "pricevice_policy_remove", "summary": "Deactivate a pricing policy (soft — issued receipts keep their pinned policy version).", "x-trustvice-description-key": "actions.pricevice.policy.remove.description", "tags": [ "pricevice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "policyId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "policyId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Deactivate a policy.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "policyId": "01J9X4P9R7Z2C1A1F2A8VBJYP1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deactivated": { "type": "boolean" } }, "required": [ "deactivated" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Deactivate a policy.", "value": { "deactivated": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "pricevice.policies.delete" ] }, { "OAuth2": [ "pricevice.policies.delete" ] }, { "WorkspaceApiKey": [ "pricevice.policies.delete" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/pricevice.integrity.summary": { "post": { "operationId": "pricevice_integrity_summary", "summary": "Get the Keystone pricing-integrity summary — totals by conformance verdict + the recent off-policy receipts with proof attached.", "x-trustvice-description-key": "actions.pricevice.integrity.summary.description", "tags": [ "pricevice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read the integrity summary.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "totals": { "type": "object", "properties": { "receipts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "withinBounds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "offPolicy": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unchecked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "receipts", "withinBounds", "offPolicy", "unchecked" ], "additionalProperties": false }, "recentOffPolicy": { "type": "array", "items": { "type": "object", "properties": { "receiptId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "amountMinor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "currency": { "type": "string" }, "policyId": { "type": [ "string", "null" ] }, "subjectReference": { "type": "string" } }, "required": [ "receiptId", "issuedAt", "amountMinor", "currency", "policyId", "subjectReference" ], "additionalProperties": false } }, "byDomain": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "required": [ "totals", "recentOffPolicy", "byDomain" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read the integrity summary.", "value": { "totals": { "receipts": 1240, "withinBounds": 1180, "offPolicy": 12, "unchecked": 48 }, "recentOffPolicy": [], "byDomain": { "saas": 900, "services": 340 } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "pricevice.integrity.view" ] }, { "OAuth2": [ "pricevice.integrity.view" ] }, { "WorkspaceApiKey": [ "pricevice.integrity.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/pricevice.disclosure.generate": { "post": { "operationId": "pricevice_disclosure_generate", "summary": "Generate the Aegis personalized-pricing disclosure for a PPR (deterministic from the receipt facts; states exactly what is proven and what is not).", "x-trustvice-description-key": "actions.pricevice.disclosure.generate.description", "tags": [ "pricevice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "receiptId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "regime": { "default": "generic", "type": "string", "enum": [ "eu_omnibus", "generic" ] } }, "required": [ "workspaceId", "receiptId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Generate a disclosure.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "receiptId": "01J9X4P9R7Z2C1A1F2A8VBJYV9", "regime": "eu_omnibus" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "receiptId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "regime": { "type": "string" }, "disclosureText": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "receiptId", "regime", "disclosureText", "generatedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Generate a disclosure.", "value": { "receiptId": "01J9X4P9R7Z2C1A1F2A8VBJYV9", "regime": "eu_omnibus", "disclosureText": "This price was determined …", "generatedAt": "2026-06-10T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "pricevice.disclosures.generate" ] }, { "OAuth2": [ "pricevice.disclosures.generate" ] }, { "WorkspaceApiKey": [ "pricevice.disclosures.generate" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.idiom.session.open": { "post": { "operationId": "paradigm_idiom_session_open", "summary": "Open an Idiom mediation session with a counterparty agent (inline requires dual consent; annotation/advisory work single-sided).", "x-trustvice-description-key": "actions.paradigm.idiom.session.open.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "counterpartyRef": { "type": "string", "minLength": 1, "maxLength": 200 }, "mode": { "default": "advisory", "type": "string", "enum": [ "inline", "annotation", "advisory" ] }, "exchangeType": { "default": "negotiation", "type": "string", "enum": [ "negotiation", "support", "coordination", "dispute" ] }, "counterpartyConsentRef": { "type": "string", "maxLength": 200 } }, "required": [ "workspaceId", "counterpartyRef" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Open an advisory session.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "counterpartyRef": "agent:acme-procurement", "mode": "advisory", "exchangeType": "negotiation" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sessionId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "mode": { "type": "string", "enum": [ "inline", "annotation", "advisory" ] }, "exchangeType": { "type": "string", "enum": [ "negotiation", "support", "coordination", "dispute" ] }, "counterpartyRef": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "sessionId", "workspaceId", "mode", "exchangeType", "counterpartyRef", "status", "createdAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Open an advisory session.", "value": { "sessionId": "01J9X4P9R7Z2C1A1F2A8VBJYS1", "workspaceId": "ws_DEMODEFAULT0000000000", "mode": "advisory", "exchangeType": "negotiation", "counterpartyRef": "agent:acme-procurement", "status": "active", "createdAt": "2026-06-10T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.idiom.sessions" ] }, { "OAuth2": [ "paradigm.idiom.sessions" ] }, { "WorkspaceApiKey": [ "paradigm.idiom.sessions" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.idiom.message.mediate": { "post": { "operationId": "paradigm_idiom_message_mediate", "summary": "Submit a message to an Idiom session for mediation/annotation. Substance is never altered; an unverified rendering is never released (fallback = annotated verbatim).", "x-trustvice-description-key": "actions.paradigm.idiom.message.mediate.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "sessionId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "direction": { "default": "inbound", "type": "string", "enum": [ "outbound", "inbound" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "workspaceId", "sessionId", "message" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Mediate an inbound message.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "sessionId": "01J9X4P9R7Z2C1A1F2A8VBJYS1", "direction": "inbound", "message": "We are not in a position to accept these terms." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "messageId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "direction": { "type": "string", "enum": [ "outbound", "inbound" ] }, "verbatimOriginal": { "type": "string" }, "rendering": { "type": [ "string", "null" ] }, "verificationResult": { "type": "string", "enum": [ "verified", "fallback_annotation", "not_applicable" ] }, "annotations": { "type": "array", "items": { "type": "string" } }, "chainHash": { "type": "string" } }, "required": [ "messageId", "direction", "verbatimOriginal", "rendering", "verificationResult", "annotations", "chainHash" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Mediate an inbound message.", "value": { "messageId": "01J9X4P9R7Z2C1A1F2A8VBJYM1", "direction": "inbound", "verbatimOriginal": "We are not in a position to accept these terms.", "rendering": null, "verificationResult": "fallback_annotation", "annotations": [ "Directness is register-typical for this counterparty frame — read as position, not hostility." ], "chainHash": "…" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.idiom.sessions" ] }, { "OAuth2": [ "paradigm.idiom.sessions" ] }, { "WorkspaceApiKey": [ "paradigm.idiom.sessions" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.idiom.advisory.analyze": { "post": { "operationId": "paradigm_idiom_advisory_analyze", "summary": "Advisory (single-side) analysis of a counterparty message: frame features, misread warnings, what it actually signals.", "x-trustvice-description-key": "actions.paradigm.idiom.advisory.analyze.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "sessionId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "message": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "workspaceId", "message" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Analyze a counterparty message.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "message": "No. The price is the price." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "frameFeatures": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "annotations": { "type": "array", "items": { "type": "string" } }, "misreadWarnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "frameFeatures", "annotations", "misreadWarnings" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Analyze a counterparty message.", "value": { "frameFeatures": { "directness": 0.95, "hedging": 0.05 }, "annotations": [ "High-directness frame." ], "misreadWarnings": [ "Bluntness here is frame-derived; do not read as bad faith." ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.idiom.advisory" ] }, { "OAuth2": [ "paradigm.idiom.advisory" ] }, { "WorkspaceApiKey": [ "paradigm.idiom.advisory" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.idiom.profile.declare": { "post": { "operationId": "paradigm_idiom_profile_declare", "summary": "Declare your own agent's frame profile (recorded alongside inferred profiles; declared-vs-inferred divergence is itself a signal).", "x-trustvice-description-key": "actions.paradigm.idiom.profile.declare.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "agentRef": { "type": "string", "minLength": 1, "maxLength": 200 }, "dimensions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number", "minimum": 0, "maximum": 1 } } }, "required": [ "workspaceId", "agentRef", "dimensions" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Declare a frame profile.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "agentRef": "agent:our-negotiator", "dimensions": { "directness": 0.4, "hedging": 0.7 } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "profileId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "agentRef": { "type": "string" }, "level": { "type": "string", "const": "declared" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "profileId", "agentRef", "level", "version" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Declare a frame profile.", "value": { "profileId": "01J9X4P9R7Z2C1A1F2A8VBJYF1", "agentRef": "agent:our-negotiator", "level": "declared", "version": 1 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.idiom.advisory" ] }, { "OAuth2": [ "paradigm.idiom.advisory" ] }, { "WorkspaceApiKey": [ "paradigm.idiom.advisory" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.idiom.transcript.get": { "post": { "operationId": "paradigm_idiom_transcript_get", "summary": "Get a session's signed, hash-chained mediation transcript (verbatim originals paired with renderings and annotations).", "x-trustvice-description-key": "actions.paradigm.idiom.transcript.get.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "sessionId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "required": [ "workspaceId", "sessionId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read a transcript.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "sessionId": "01J9X4P9R7Z2C1A1F2A8VBJYS1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sessionId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "messageId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "direction": { "type": "string", "enum": [ "outbound", "inbound" ] }, "verbatimOriginal": { "type": "string" }, "rendering": { "type": [ "string", "null" ] }, "verificationResult": { "type": "string", "enum": [ "verified", "fallback_annotation", "not_applicable" ] }, "annotations": { "type": "array", "items": { "type": "string" } }, "chainHash": { "type": "string" } }, "required": [ "messageId", "direction", "verbatimOriginal", "rendering", "verificationResult", "annotations", "chainHash" ], "additionalProperties": {} } } }, "required": [ "sessionId", "messages" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read a transcript.", "value": { "sessionId": "01J9X4P9R7Z2C1A1F2A8VBJYS1", "messages": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.idiom.sessions" ] }, { "OAuth2": [ "paradigm.idiom.sessions" ] }, { "WorkspaceApiKey": [ "paradigm.idiom.sessions" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.temperament.card.publish": { "post": { "operationId": "paradigm_temperament_card_publish", "summary": "Author and publish a temperament card for an API (validated for semantic consistency; publishes as provider_declared — verification upgrades evidence, never the publisher).", "x-trustvice-description-key": "actions.paradigm.temperament.card.publish.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "apiRef": { "type": "string", "minLength": 1, "maxLength": 300 }, "scope": { "default": "whole_api", "type": "string", "maxLength": 300 }, "sections": { "type": "object", "properties": { "ambiguity": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "retry": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "errorStyle": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "determinism": { "type": "object", "properties": { "class": { "type": "string", "enum": [ "deterministic", "eventually_consistent", "probabilistic" ] } }, "required": [ "class" ], "additionalProperties": {} }, "freshness": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "degradation": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "change": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "ambiguity", "retry", "errorStyle", "determinism" ], "additionalProperties": {} }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "workspaceId", "apiRef", "sections" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Publish a card.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "apiRef": "api.example.com/v2", "scope": "whole_api", "sections": { "ambiguity": { "malformed_date": "reject" }, "retry": { "reads": "guaranteed", "writes": "designed_but_unverified" }, "errorStyle": { "verbosity": "structured" }, "determinism": { "class": "deterministic" }, "freshness": {}, "degradation": {}, "change": {} } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cardId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "apiRef": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published", "qualified", "downgraded", "expired" ] }, "sections": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "evidence": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "cardId", "apiRef", "status", "sections", "evidence", "version" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Publish a card.", "value": { "cardId": "01J9X4P9R7Z2C1A1F2A8VBJYC1", "apiRef": "api.example.com/v2", "status": "published", "sections": {}, "evidence": {}, "version": 1 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.temperament.publish" ] }, { "OAuth2": [ "paradigm.temperament.publish" ] }, { "WorkspaceApiKey": [ "paradigm.temperament.publish" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.temperament.card.get": { "post": { "operationId": "paradigm_temperament_card_get", "summary": "Get a temperament card (published cards are public registry reads; 'no card published' is itself a queryable state).", "x-trustvice-description-key": "actions.paradigm.temperament.card.get.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "cardId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "apiRef": { "type": "string", "maxLength": 300 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read a card by API ref.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "apiRef": "api.example.com/v2" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cardId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "apiRef": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published", "qualified", "downgraded", "expired" ] }, "sections": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "evidence": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "cardId", "apiRef", "status", "sections", "evidence", "version" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read a card by API ref.", "value": { "cardId": "01J9X4P9R7Z2C1A1F2A8VBJYC1", "apiRef": "api.example.com/v2", "status": "published", "sections": {}, "evidence": {}, "version": 1 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.temperament.view" ] }, { "OAuth2": [ "paradigm.temperament.view" ] }, { "WorkspaceApiKey": [ "paradigm.temperament.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.temperament.search": { "post": { "operationId": "paradigm_temperament_search", "summary": "Search the temperament-card registry by API ref and behavioral filters (determinism class, status).", "x-trustvice-description-key": "actions.paradigm.temperament.search.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "apiRef": { "type": "string", "maxLength": 300 }, "determinism": { "type": "string", "enum": [ "deterministic", "eventually_consistent", "probabilistic" ] }, "status": { "type": "string", "enum": [ "draft", "published", "qualified", "downgraded", "expired" ] } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Search cards.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "determinism": "deterministic" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cards": { "type": "array", "items": { "type": "object", "properties": { "cardId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "apiRef": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published", "qualified", "downgraded", "expired" ] }, "sections": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "evidence": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "cardId", "apiRef", "status", "sections", "evidence", "version" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "cards", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Search cards.", "value": { "cards": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.temperament.view" ] }, { "OAuth2": [ "paradigm.temperament.view" ] }, { "WorkspaceApiKey": [ "paradigm.temperament.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.temperament.strategy.get": { "post": { "operationId": "paradigm_temperament_strategy_get", "summary": "Get the compiled calling-strategy directives for a card (retry policy, input strictness, response interpretation, degradation expectation) — unverified cards carry lower trust weights.", "x-trustvice-description-key": "actions.paradigm.temperament.strategy.get.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "cardId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "required": [ "workspaceId", "cardId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Compile a calling strategy.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "cardId": "01J9X4P9R7Z2C1A1F2A8VBJYC1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cardId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "apiRef": { "type": "string" }, "directives": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "compilerVersion": { "type": "string" }, "trustWeight": { "type": "number" } }, "required": [ "cardId", "apiRef", "directives", "compilerVersion", "trustWeight" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Compile a calling strategy.", "value": { "cardId": "01J9X4P9R7Z2C1A1F2A8VBJYC1", "apiRef": "api.example.com/v2", "directives": {}, "compilerVersion": "strategy-c1", "trustWeight": 0.5 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.temperament.view" ] }, { "OAuth2": [ "paradigm.temperament.view" ] }, { "WorkspaceApiKey": [ "paradigm.temperament.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.overture.offer.publish": { "post": { "operationId": "paradigm_overture_offer_publish", "summary": "Publish an Overture initiation offer (a typed declaration of what you may proactively tell subscribers — delivery still requires their consent).", "x-trustvice-description-key": "actions.paradigm.overture.offer.publish.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "type": { "type": "string", "enum": [ "alert", "risk_warning", "opportunity", "remediation_proposal", "status_insight", "recommendation" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "subjectScope": { "type": "string", "minLength": 1, "maxLength": 500 }, "frequencyBandPerDay": { "default": 10, "type": "integer", "exclusiveMinimum": 0, "maximum": 10000 } }, "required": [ "workspaceId", "type", "label", "subjectScope" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Publish an offer.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "type": "risk_warning", "label": "Chargeback pattern forming", "subjectScope": "subscriber payment telemetry", "frequencyBandPerDay": 5 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "offerId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "type": { "type": "string", "enum": [ "alert", "risk_warning", "opportunity", "remediation_proposal", "status_insight", "recommendation" ] }, "label": { "type": "string" }, "status": { "type": "string" } }, "required": [ "offerId", "type", "label", "status" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Publish an offer.", "value": { "offerId": "01J9X4P9R7Z2C1A1F2A8VBJY01", "type": "risk_warning", "label": "Chargeback pattern forming", "status": "active" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.overture.provider" ] }, { "OAuth2": [ "paradigm.overture.provider" ] }, { "WorkspaceApiKey": [ "paradigm.overture.provider" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.overture.subscribe": { "post": { "operationId": "paradigm_overture_subscribe", "summary": "Subscribe to an initiation offer with consent rules (value threshold, frequency caps, quiet hours). Mints a signed consent receipt.", "x-trustvice-description-key": "actions.paradigm.overture.subscribe.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "offerId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "minPredictedValue": { "default": 0.3, "type": "number", "minimum": 0, "maximum": 1 }, "frequencyCapPerDay": { "type": "integer", "exclusiveMinimum": 0, "maximum": 1000 } }, "required": [ "workspaceId", "offerId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Subscribe with rules.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "offerId": "01J9X4P9R7Z2C1A1F2A8VBJY01", "minPredictedValue": 0.5 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subscriptionId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "offerId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "consentReceipt": { "type": "string" }, "status": { "type": "string" } }, "required": [ "subscriptionId", "offerId", "consentReceipt", "status" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Subscribe with rules.", "value": { "subscriptionId": "01J9X4P9R7Z2C1A1F2A8VBJYU1", "offerId": "01J9X4P9R7Z2C1A1F2A8VBJY01", "consentReceipt": "…", "status": "active" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.overture.subscribe" ] }, { "OAuth2": [ "paradigm.overture.subscribe" ] }, { "WorkspaceApiKey": [ "paradigm.overture.subscribe" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.overture.initiate": { "post": { "operationId": "paradigm_overture_initiate", "summary": "Submit an initiation for delivery to subscribers. Consent-first: subscribers without an active subscription are never reached; each delivery is value-predicted against the attention budget.", "x-trustvice-description-key": "actions.paradigm.overture.initiate.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "offerId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "urgency": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "workspaceId", "offerId", "payload" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Initiate to subscribers.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "offerId": "01J9X4P9R7Z2C1A1F2A8VBJY01", "payload": { "pattern": "chargeback_spike", "confidence": 0.83 }, "urgency": 0.8 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "initiationId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "subscriptionId": { "type": "string" }, "decision": { "type": "string", "enum": [ "deliver", "defer", "digest", "drop" ] }, "predictedValue": { "type": "number" }, "rationale": { "type": "string" } }, "required": [ "subscriptionId", "decision", "predictedValue", "rationale" ], "additionalProperties": false } } }, "required": [ "initiationId", "decisions" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Initiate to subscribers.", "value": { "initiationId": "01J9X4P9R7Z2C1A1F2A8VBJYI1", "decisions": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.overture.provider" ] }, { "OAuth2": [ "paradigm.overture.provider" ] }, { "WorkspaceApiKey": [ "paradigm.overture.provider" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.overture.inbox.list": { "post": { "operationId": "paradigm_overture_inbox_list", "summary": "Read the initiation inbox — delivered initiations with predicted-value disclosure and feedback affordances.", "x-trustvice-description-key": "actions.paradigm.overture.inbox.list.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read the inbox.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deliveries": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "deliveries", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read the inbox.", "value": { "deliveries": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.overture.subscribe" ] }, { "OAuth2": [ "paradigm.overture.subscribe" ] }, { "WorkspaceApiKey": [ "paradigm.overture.subscribe" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.overture.feedback": { "post": { "operationId": "paradigm_overture_feedback", "summary": "Rate a delivered initiation (useful / not useful / harmful) — the value loop that earns or costs the provider future attention.", "x-trustvice-description-key": "actions.paradigm.overture.feedback.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "deliveryId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "rating": { "type": "string", "enum": [ "useful", "not_useful", "harmful" ] } }, "required": [ "workspaceId", "deliveryId", "rating" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Close the value loop.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "deliveryId": "01J9X4P9R7Z2C1A1F2A8VBJYD1", "rating": "useful" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "recorded": { "type": "boolean" } }, "required": [ "recorded" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Close the value loop.", "value": { "recorded": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.overture.subscribe" ] }, { "OAuth2": [ "paradigm.overture.subscribe" ] }, { "WorkspaceApiKey": [ "paradigm.overture.subscribe" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.rapport.events.ingest": { "post": { "operationId": "paradigm_rapport_events_ingest", "summary": "Contribute consented agent-interaction telemetry (calls, retries, doc fetches, abandonment markers). Requires an active consent grant; identity is stripped at the edge.", "x-trustvice-description-key": "actions.paradigm.rapport.events.ingest.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "grantId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "events": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "apiRef": { "type": "string", "minLength": 1, "maxLength": 300 }, "eventType": { "type": "string", "enum": [ "call", "retry", "doc_fetch", "introspection", "abandon_marker", "recommendation" ] }, "outcome": { "default": "n_a", "type": "string", "enum": [ "success", "failure", "n_a" ] }, "parameterDelta": { "default": false, "type": "boolean" }, "agentHash": { "type": "string", "maxLength": 128 }, "sessionRef": { "type": "string", "maxLength": 200 } }, "required": [ "apiRef", "eventType" ] } } }, "required": [ "workspaceId", "grantId", "events" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Contribute telemetry.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "grantId": "01J9X4P9R7Z2C1A1F2A8VBJYG1", "events": [ { "apiRef": "api.example.com/v2", "eventType": "call", "outcome": "success", "parameterDelta": false } ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "accepted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rejected": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "accepted", "rejected" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Contribute telemetry.", "value": { "accepted": 1, "rejected": 0 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.rapport.contribute" ] }, { "OAuth2": [ "paradigm.rapport.contribute" ] }, { "WorkspaceApiKey": [ "paradigm.rapport.contribute" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.rapport.score.get": { "post": { "operationId": "paradigm_rapport_score_get", "summary": "Get the public Rapport Score for an API (k-floored: under-floor APIs honestly return 'insufficient_data', never a weak number).", "x-trustvice-description-key": "actions.paradigm.rapport.score.get.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "apiRef": { "type": "string", "minLength": 1, "maxLength": 300 } }, "required": [ "workspaceId", "apiRef" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read a public score.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "apiRef": "api.example.com/v2" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "apiRef": { "type": "string" }, "score": { "type": [ "number", "null" ] }, "methodologyVersion": { "type": "string" }, "publicationStatus": { "type": "string", "enum": [ "published", "insufficient_data" ] } }, "required": [ "apiRef", "score", "methodologyVersion", "publicationStatus" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read a public score.", "value": { "apiRef": "api.example.com/v2", "score": null, "methodologyVersion": "rapport-m1", "publicationStatus": "insufficient_data" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.rapport.analytics.get": { "post": { "operationId": "paradigm_rapport_analytics_get", "summary": "Provider analytics for your own API: metric cells + attribution findings ranked by impact (which endpoint/error/pattern drives confusion or abandonment).", "x-trustvice-description-key": "actions.paradigm.rapport.analytics.get.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "apiRef": { "type": "string", "minLength": 1, "maxLength": 300 } }, "required": [ "workspaceId", "apiRef" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read provider analytics.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "apiRef": "api.example.com/v2" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cells": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "attribution": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "required": [ "cells", "attribution" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read provider analytics.", "value": { "cells": [], "attribution": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.rapport.analytics" ] }, { "OAuth2": [ "paradigm.rapport.analytics" ] }, { "WorkspaceApiKey": [ "paradigm.rapport.analytics" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.counterfact.feasibility.check": { "post": { "operationId": "paradigm_counterfact_feasibility_check", "summary": "Check what substrate modes are available for a counterfactual query before running it (which mode, what confidence ceiling, what gaps, whether it would be refused).", "x-trustvice-description-key": "actions.paradigm.counterfact.feasibility.check.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "apiRef": { "type": "string", "minLength": 1, "maxLength": 300 }, "anchorTraceIds": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "interventionType": { "type": "string", "enum": [ "alternate_params", "alternate_sequence", "no_call" ] }, "minMode": { "type": "string", "enum": [ "cooperative_replay", "recorded_reconstruction", "semantic_simulation" ] } }, "required": [ "workspaceId", "apiRef", "anchorTraceIds", "interventionType" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Check feasibility.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "apiRef": "api.example.com/v2", "anchorTraceIds": [ "01J9X4P9R7Z2C1A1F2A8VBJYT1" ], "interventionType": "no_call" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "availableModes": { "type": "array", "items": { "type": "string", "enum": [ "cooperative_replay", "recorded_reconstruction", "semantic_simulation" ] } }, "selectedMode": { "anyOf": [ { "type": "string", "enum": [ "cooperative_replay", "recorded_reconstruction", "semantic_simulation" ] }, { "type": "null" } ] }, "confidenceCeiling": { "type": [ "string", "null" ] }, "gapSummary": { "type": "array", "items": { "type": "string" } }, "wouldRefuse": { "type": "boolean" } }, "required": [ "availableModes", "selectedMode", "confidenceCeiling", "gapSummary", "wouldRefuse" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Check feasibility.", "value": { "availableModes": [ "recorded_reconstruction" ], "selectedMode": "recorded_reconstruction", "confidenceCeiling": "reconstruction_complete", "gapSummary": [], "wouldRefuse": false } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.counterfact.run" ] }, { "OAuth2": [ "paradigm.counterfact.run" ] }, { "WorkspaceApiKey": [ "paradigm.counterfact.run" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.counterfact.query.run": { "post": { "operationId": "paradigm_counterfact_query_run", "summary": "Run a counterfactual query against recorded interaction state. Every result carries its mode + confidence grade; un-answerable classes are refused with a structured explanation, never guessed.", "x-trustvice-description-key": "actions.paradigm.counterfact.query.run.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "apiRef": { "type": "string", "minLength": 1, "maxLength": 300 }, "anchorTraceIds": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "interventionType": { "type": "string", "enum": [ "alternate_params", "alternate_sequence", "no_call" ] }, "alternateParams": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "minMode": { "type": "string", "enum": [ "cooperative_replay", "recorded_reconstruction", "semantic_simulation" ] } }, "required": [ "workspaceId", "apiRef", "anchorTraceIds", "interventionType" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Run a counterfactual.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "apiRef": "api.example.com/v2", "anchorTraceIds": [ "01J9X4P9R7Z2C1A1F2A8VBJYT1" ], "interventionType": "no_call" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "queryId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "status": { "type": "string", "enum": [ "evaluated", "refused" ] }, "result": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "refusal": { "type": [ "string", "null" ] } }, "required": [ "queryId", "status", "result", "refusal" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Run a counterfactual.", "value": { "queryId": "01J9X4P9R7Z2C1A1F2A8VBJYQ1", "status": "evaluated", "result": {}, "refusal": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.counterfact.run" ] }, { "OAuth2": [ "paradigm.counterfact.run" ] }, { "WorkspaceApiKey": [ "paradigm.counterfact.run" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.counterfact.record.get": { "post": { "operationId": "paradigm_counterfact_record_get", "summary": "Get the sealed, hash-chained evidentiary record for an evaluated counterfactual (citable in audits and disputes).", "x-trustvice-description-key": "actions.paradigm.counterfact.record.get.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "queryId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "required": [ "workspaceId", "queryId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read a sealed record.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "queryId": "01J9X4P9R7Z2C1A1F2A8VBJYQ1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "record": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "record" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read a sealed record.", "value": { "record": {} } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.counterfact.run" ] }, { "OAuth2": [ "paradigm.counterfact.run" ] }, { "WorkspaceApiKey": [ "paradigm.counterfact.run" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.breaker.signal.list": { "post": { "operationId": "paradigm_breaker_signal_list", "summary": "Read the public halt-signal log (active and historical) — append-only, complete, offline-verifiable. Public; cannot be disabled.", "x-trustvice-description-key": "actions.paradigm.breaker.signal.list.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] }, "sinceSeq": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read the public signal log.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "status": "active" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "signals": { "type": "array", "items": { "type": "object", "properties": { "signalId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "issuerClass": { "type": "string", "enum": [ "regulator", "provider", "community" ] }, "scope": { "type": "object", "properties": { "actionClasses": { "type": "array", "items": { "type": "string", "enum": [ "agent_financial_transactions", "autonomous_writes", "autonomous_communications", "agent_purchases", "data_exports", "credential_operations", "all_autonomous_actions" ] } }, "domains": { "type": "array", "items": { "type": "string" } }, "jurisdictions": { "type": "array", "items": { "type": "string" } }, "qualifiers": { "type": "array", "items": { "type": "string" } } }, "required": [ "actionClasses", "domains", "jurisdictions", "qualifiers" ], "additionalProperties": {} }, "severity": { "type": "string", "enum": [ "advisory", "soft_halt", "hard_halt" ] }, "drill": { "type": "boolean" }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] } }, "required": [ "signalId", "issuerClass", "scope", "severity", "drill", "issuedAt", "expiresAt", "status" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "signals", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read the public signal log.", "value": { "signals": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.breaker.check.action": { "post": { "operationId": "paradigm_breaker_check_action", "summary": "Pre-flight halt check: does any active signal's scope match this action descriptor? Returns matched signals + the strictest severity. Absent any signal, the answer is 'proceed' — the system halts on authenticated signal, never on silence.", "x-trustvice-description-key": "actions.paradigm.breaker.check.action.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "actionClass": { "type": "string", "enum": [ "agent_financial_transactions", "autonomous_writes", "autonomous_communications", "agent_purchases", "data_exports", "credential_operations", "all_autonomous_actions" ] }, "domain": { "type": "string", "maxLength": 300 }, "jurisdiction": { "type": "string", "maxLength": 50 } }, "required": [ "workspaceId", "actionClass" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Pre-flight check.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "actionClass": "agent_financial_transactions", "domain": "payments" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "halted": { "type": "boolean" }, "severity": { "anyOf": [ { "type": "string", "enum": [ "advisory", "soft_halt", "hard_halt" ] }, { "type": "null" } ] }, "matchedSignals": { "type": "array", "items": { "type": "object", "properties": { "signalId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "issuerClass": { "type": "string", "enum": [ "regulator", "provider", "community" ] }, "scope": { "type": "object", "properties": { "actionClasses": { "type": "array", "items": { "type": "string", "enum": [ "agent_financial_transactions", "autonomous_writes", "autonomous_communications", "agent_purchases", "data_exports", "credential_operations", "all_autonomous_actions" ] } }, "domains": { "type": "array", "items": { "type": "string" } }, "jurisdictions": { "type": "array", "items": { "type": "string" } }, "qualifiers": { "type": "array", "items": { "type": "string" } } }, "required": [ "actionClasses", "domains", "jurisdictions", "qualifiers" ], "additionalProperties": {} }, "severity": { "type": "string", "enum": [ "advisory", "soft_halt", "hard_halt" ] }, "drill": { "type": "boolean" }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] } }, "required": [ "signalId", "issuerClass", "scope", "severity", "drill", "issuedAt", "expiresAt", "status" ], "additionalProperties": {} } } }, "required": [ "halted", "severity", "matchedSignals" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Pre-flight check.", "value": { "halted": false, "severity": null, "matchedSignals": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.breaker.signal.issue": { "post": { "operationId": "paradigm_breaker_signal_issue", "summary": "Issue a halt signal (provider-class: your own registered surface only; duration is capped by the issuer-class ceiling and every signal expires — unconditionally).", "x-trustvice-description-key": "actions.paradigm.breaker.signal.issue.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "actionClasses": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "string", "enum": [ "agent_financial_transactions", "autonomous_writes", "autonomous_communications", "agent_purchases", "data_exports", "credential_operations", "all_autonomous_actions" ] } }, "domains": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "qualifiers": { "default": [], "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 100 } }, "severity": { "default": "soft_halt", "type": "string", "enum": [ "advisory", "soft_halt", "hard_halt" ] }, "basis": { "type": "string", "minLength": 10, "maxLength": 2000 }, "durationMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "drill": { "default": false, "type": "boolean" } }, "required": [ "workspaceId", "actionClasses", "domains", "basis", "durationMinutes" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Issue a scoped halt.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "actionClasses": [ "agent_purchases" ], "domains": [ "api.example.com/v2" ], "qualifiers": [], "severity": "soft_halt", "basis": "Correlated mis-execution pattern across fleet; pausing pending review.", "durationMinutes": 90, "drill": false } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "signalId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "issuerClass": { "type": "string", "enum": [ "regulator", "provider", "community" ] }, "scope": { "type": "object", "properties": { "actionClasses": { "type": "array", "items": { "type": "string", "enum": [ "agent_financial_transactions", "autonomous_writes", "autonomous_communications", "agent_purchases", "data_exports", "credential_operations", "all_autonomous_actions" ] } }, "domains": { "type": "array", "items": { "type": "string" } }, "jurisdictions": { "type": "array", "items": { "type": "string" } }, "qualifiers": { "type": "array", "items": { "type": "string" } } }, "required": [ "actionClasses", "domains", "jurisdictions", "qualifiers" ], "additionalProperties": {} }, "severity": { "type": "string", "enum": [ "advisory", "soft_halt", "hard_halt" ] }, "drill": { "type": "boolean" }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] } }, "required": [ "signalId", "issuerClass", "scope", "severity", "drill", "issuedAt", "expiresAt", "status" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Issue a scoped halt.", "value": { "signalId": "01J9X4P9R7Z2C1A1F2A8VBJYH1", "issuerClass": "provider", "scope": { "actionClasses": [ "agent_purchases" ], "domains": [ "api.example.com/v2" ], "jurisdictions": [], "qualifiers": [] }, "severity": "soft_halt", "drill": false, "issuedAt": "2026-06-10T12:00:00.000Z", "expiresAt": "2026-06-10T13:30:00.000Z", "status": "active" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.breaker.issue" ] }, { "OAuth2": [ "paradigm.breaker.issue" ] }, { "WorkspaceApiKey": [ "paradigm.breaker.issue" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.breaker.point.register": { "post": { "operationId": "paradigm_breaker_point_register", "summary": "Register an enforcement point (gateway, runtime or MCP server) that will acknowledge and enforce breaker signals for this workspace.", "x-trustvice-description-key": "actions.paradigm.breaker.point.register.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "type": { "type": "string", "enum": [ "gateway", "runtime", "mcp_server" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "registeredSurface": { "default": [], "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 300 } }, "drillParticipation": { "default": false, "type": "boolean" } }, "required": [ "workspaceId", "type", "label" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Register an enforcement point.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "type": "gateway", "label": "EU edge gateway", "registeredSurface": [ "api.example.com/v2" ], "drillParticipation": true } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "point": { "type": "object", "properties": { "pointId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "type": { "type": "string" }, "label": { "type": "string" }, "registeredSurface": { "type": "array", "items": { "type": "string" } }, "drillParticipation": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "pointId", "workspaceId", "type", "label", "registeredSurface", "drillParticipation", "createdAt" ], "additionalProperties": false } }, "required": [ "point" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Register an enforcement point.", "value": { "point": { "pointId": "01J9X4P9R7Z2C1A1F2A8VBJYP1", "workspaceId": "ws_DEMODEFAULT0000000000", "type": "gateway", "label": "EU edge gateway", "registeredSurface": [ "api.example.com/v2" ], "drillParticipation": true, "createdAt": "2026-09-02T12:00:00.000Z" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.breaker.enforce" ] }, { "OAuth2": [ "paradigm.breaker.enforce" ] }, { "WorkspaceApiKey": [ "paradigm.breaker.enforce" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.breaker.point.list": { "post": { "operationId": "paradigm_breaker_point_list", "summary": "List this workspace's registered enforcement points — which surfaces are wired to honour breaker signals.", "x-trustvice-description-key": "actions.paradigm.breaker.point.list.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List enforcement points.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "points": { "type": "array", "items": { "type": "object", "properties": { "pointId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "type": { "type": "string" }, "label": { "type": "string" }, "registeredSurface": { "type": "array", "items": { "type": "string" } }, "drillParticipation": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "pointId", "workspaceId", "type", "label", "registeredSurface", "drillParticipation", "createdAt" ], "additionalProperties": false } } }, "required": [ "points" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List enforcement points.", "value": { "points": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.breaker.enforce" ] }, { "OAuth2": [ "paradigm.breaker.enforce" ] }, { "WorkspaceApiKey": [ "paradigm.breaker.enforce" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.breaker.acknowledge": { "post": { "operationId": "paradigm_breaker_acknowledge", "summary": "Report an enforcement point's state for a signal (acknowledged / enforcing / declared non-compliant) — coverage visibility is part of the protocol.", "x-trustvice-description-key": "actions.paradigm.breaker.acknowledge.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "signalId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "pointId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "state": { "type": "string", "enum": [ "acknowledged", "enforcing", "non_compliant_declared" ] } }, "required": [ "workspaceId", "signalId", "pointId", "state" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Acknowledge enforcement.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "signalId": "01J9X4P9R7Z2C1A1F2A8VBJYH1", "pointId": "01J9X4P9R7Z2C1A1F2A8VBJYP1", "state": "enforcing" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "recorded": { "type": "boolean" } }, "required": [ "recorded" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Acknowledge enforcement.", "value": { "recorded": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.breaker.enforce" ] }, { "OAuth2": [ "paradigm.breaker.enforce" ] }, { "WorkspaceApiKey": [ "paradigm.breaker.enforce" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.breaker.proposal.open": { "post": { "operationId": "paradigm_breaker_proposal_open", "summary": "Open a community-class halt proposal (draft signal + evidence) for the affected operator constituency to vote on — advisories never bypass the vote.", "x-trustvice-description-key": "actions.paradigm.breaker.proposal.open.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "draftSignal": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "evidence": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 2000 } }, "ballotMinutes": { "default": 120, "type": "integer", "exclusiveMinimum": 0, "maximum": 1440 } }, "required": [ "workspaceId", "draftSignal", "evidence" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Open a community proposal.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "draftSignal": { "actionClasses": [ "autonomous_writes" ], "domains": [ "api.example.com" ] }, "evidence": [ "Synchronized retry storm observed across 40 fleets." ], "ballotMinutes": 60 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "proposalId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "status": { "type": "string" }, "ballotClosesAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "proposalId", "status", "ballotClosesAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Open a community proposal.", "value": { "proposalId": "01J9X4P9R7Z2C1A1F2A8VBJYR1", "status": "open", "ballotClosesAt": "2026-06-10T13:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.breaker.vote" ] }, { "OAuth2": [ "paradigm.breaker.vote" ] }, { "WorkspaceApiKey": [ "paradigm.breaker.vote" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.umbra.document.publish": { "post": { "operationId": "paradigm_umbra_document_publish", "summary": "Author and publish an Umbra negative-space document. Vague entries are structurally rejected (triggers + failure signature required; silent-failure entries require detection guidance).", "x-trustvice-description-key": "actions.paradigm.umbra.document.publish.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "apiRef": { "type": "string", "minLength": 1, "maxLength": 300 }, "versionRange": { "type": "string", "minLength": 1, "maxLength": 100 }, "coverageStatement": { "type": "string", "minLength": 10, "maxLength": 2000 }, "entries": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "cannot_do", "unhandled_input", "silent_failure", "performance_cliff", "undocumented_coupling", "coverage_gap", "known_issue" ] }, "specification": { "type": "string", "minLength": 10, "maxLength": 2000 }, "triggers": { "type": "string", "minLength": 5, "maxLength": 2000 }, "failureSignature": { "type": "string", "enum": [ "error", "silent_miscomputation", "partial_effect", "not_applicable" ] }, "severity": { "type": "string", "enum": [ "informational", "planning_relevant", "hazardous", "silent_hazardous" ] }, "detectionGuidance": { "type": "string", "maxLength": 2000 }, "avoidance": { "type": "string", "maxLength": 2000 }, "workaround": { "type": "string", "maxLength": 2000 } }, "required": [ "type", "specification", "triggers", "failureSignature", "severity" ] } } }, "required": [ "workspaceId", "apiRef", "versionRange", "coverageStatement", "entries" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Publish negative space.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "apiRef": "api.example.com/v2", "versionRange": ">=2.0 <3.0", "coverageStatement": "Input classes and call-order couplings examined by the provider team; no probe pass yet.", "entries": [ { "type": "silent_failure", "specification": "Batch update reports 200 OK while skipping rows over 1MB.", "triggers": "POST /batch with any row > 1MB", "failureSignature": "partial_effect", "severity": "silent_hazardous", "detectionGuidance": "Re-read affected rows after batch write and compare row counts." } ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "documentId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "apiRef": { "type": "string" }, "status": { "type": "string" }, "entryCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "documentId", "apiRef", "status", "entryCount" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Publish negative space.", "value": { "documentId": "01J9X4P9R7Z2C1A1F2A8VBJYW1", "apiRef": "api.example.com/v2", "status": "published", "entryCount": 1 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.umbra.publish" ] }, { "OAuth2": [ "paradigm.umbra.publish" ] }, { "WorkspaceApiKey": [ "paradigm.umbra.publish" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.umbra.document.get": { "post": { "operationId": "paradigm_umbra_document_get", "summary": "Get an API's published Umbra document with entries (published documents are public registry reads; every document carries its coverage statement).", "x-trustvice-description-key": "actions.paradigm.umbra.document.get.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "documentId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "apiRef": { "type": "string", "maxLength": 300 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read a document.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "apiRef": "api.example.com/v2" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "document": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "entries": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "required": [ "document", "entries" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read a document.", "value": { "document": {}, "entries": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.umbra.view" ] }, { "OAuth2": [ "paradigm.umbra.view" ] }, { "WorkspaceApiKey": [ "paradigm.umbra.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.umbra.input.check": { "post": { "operationId": "paradigm_umbra_input_check", "summary": "Pre-call check of an input descriptor against an API's known-unhandled classes — plan around documented failure modes instead of colliding with them.", "x-trustvice-description-key": "actions.paradigm.umbra.input.check.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "apiRef": { "type": "string", "minLength": 1, "maxLength": 300 }, "operation": { "type": "string", "minLength": 1, "maxLength": 300 }, "inputDescriptor": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "workspaceId", "apiRef", "operation", "inputDescriptor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Check an input pre-call.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "apiRef": "api.example.com/v2", "operation": "POST /batch", "inputDescriptor": "rows up to 2MB" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "matches": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "hazardous": { "type": "boolean" }, "coverageStatement": { "type": "string" } }, "required": [ "matches", "hazardous", "coverageStatement" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Check an input pre-call.", "value": { "matches": [], "hazardous": false, "coverageStatement": "No published document covers this operation — absence of an entry is not absence of a limitation." } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.umbra.view" ] }, { "OAuth2": [ "paradigm.umbra.view" ] }, { "WorkspaceApiKey": [ "paradigm.umbra.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.umbra.guards.get": { "post": { "operationId": "paradigm_umbra_guards_get", "summary": "Get the compiled integration checks + runtime guards for an Umbra document (effect-verification wrappers for silent failures, input pre-validators, cliff-aware batching).", "x-trustvice-description-key": "actions.paradigm.umbra.guards.get.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "documentId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "required": [ "workspaceId", "documentId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Compile guards.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "documentId": "01J9X4P9R7Z2C1A1F2A8VBJYW1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "integrationChecks": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "runtimeGuards": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "compilerVersion": { "type": "string" } }, "required": [ "integrationChecks", "runtimeGuards", "compilerVersion" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Compile guards.", "value": { "integrationChecks": [], "runtimeGuards": [], "compilerVersion": "guards-c1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.umbra.view" ] }, { "OAuth2": [ "paradigm.umbra.view" ] }, { "WorkspaceApiKey": [ "paradigm.umbra.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.survey.recommend": { "post": { "operationId": "paradigm_survey_recommend", "summary": "For task T under constraints C at step S: the ecosystem's revealed preference — usage shares, quality differentials, behavioral annotations, and a mandatory coverage statement. 'More used' is distinguished from 'measurably better'.", "x-trustvice-description-key": "actions.paradigm.survey.recommend.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "task": { "type": "string", "enum": [ "research", "data_extraction", "financial_analysis", "communication", "commerce_operations", "code_tasks", "content_generation", "operations_monitoring" ] }, "stepRole": { "type": "string", "minLength": 1, "maxLength": 200 }, "constraintProfile": { "default": "balanced", "type": "string", "enum": [ "latency_sensitive", "accuracy_sensitive", "cost_sensitive", "balanced" ] } }, "required": [ "workspaceId", "task", "stepRole" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Ask the map.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "task": "data_extraction", "stepRole": "document_parse", "constraintProfile": "accuracy_sensitive" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ranked": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "floorStatus": { "type": "string", "enum": [ "published", "insufficient_data" ] }, "coverageStatement": { "type": "string" } }, "required": [ "ranked", "floorStatus", "coverageStatement" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Ask the map.", "value": { "ranked": [], "floorStatus": "insufficient_data", "coverageStatement": "Below the contributor floor for this cell — contribute telemetry to deepen the map." } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.survey.query" ] }, { "OAuth2": [ "paradigm.survey.query" ] }, { "WorkspaceApiKey": [ "paradigm.survey.query" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.survey.map.get": { "post": { "operationId": "paradigm_survey_map_get", "summary": "Read a usage-map cell (per task node and step role): API usage shares with quality differentials, k-floored, with skew flags and the coverage statement.", "x-trustvice-description-key": "actions.paradigm.survey.map.get.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "task": { "type": "string", "enum": [ "research", "data_extraction", "financial_analysis", "communication", "commerce_operations", "code_tasks", "content_generation", "operations_monitoring" ] }, "stepRole": { "type": "string", "maxLength": 200 } }, "required": [ "workspaceId", "task" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Browse the map.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "task": "research" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cells": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "coverageStatement": { "type": "string" } }, "required": [ "cells", "coverageStatement" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Browse the map.", "value": { "cells": [], "coverageStatement": "…" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.survey.query" ] }, { "OAuth2": [ "paradigm.survey.query" ] }, { "WorkspaceApiKey": [ "paradigm.survey.query" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.survey.events.contribute": { "post": { "operationId": "paradigm_survey_events_contribute", "summary": "Contribute consented task-telemetry events (task context, call sequence roles, outcome markers). Contributors see deeper into the maps their data builds.", "x-trustvice-description-key": "actions.paradigm.survey.events.contribute.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "grantId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "events": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "task": { "type": "string", "enum": [ "research", "data_extraction", "financial_analysis", "communication", "commerce_operations", "code_tasks", "content_generation", "operations_monitoring" ] }, "stepRole": { "type": "string", "minLength": 1, "maxLength": 200 }, "apiRef": { "type": "string", "minLength": 1, "maxLength": 300 }, "sequencePosition": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outcome": { "type": "string", "enum": [ "completed", "abandoned", "failed" ] }, "qualitySignal": { "type": "number", "minimum": 0, "maximum": 1 }, "agentHash": { "type": "string", "maxLength": 128 } }, "required": [ "task", "stepRole", "apiRef", "outcome" ] } } }, "required": [ "workspaceId", "grantId", "events" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Contribute task telemetry.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "grantId": "01J9X4P9R7Z2C1A1F2A8VBJYG1", "events": [ { "task": "research", "stepRole": "web_search", "apiRef": "api.example.com/v2", "sequencePosition": 0, "outcome": "completed", "qualitySignal": 0.9 } ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "accepted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rejected": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "accepted", "rejected" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Contribute task telemetry.", "value": { "accepted": 1, "rejected": 0 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.survey.contribute" ] }, { "OAuth2": [ "paradigm.survey.contribute" ] }, { "WorkspaceApiKey": [ "paradigm.survey.contribute" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.consent.grant": { "post": { "operationId": "paradigm_consent_grant", "summary": "Create a Paradigm consent grant (scoped by modules + data class + granularity) — the precondition for ANY telemetry consumption. Mints a signed consent receipt.", "x-trustvice-description-key": "actions.paradigm.consent.grant.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "products": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "idiom", "temperament", "overture", "rapport", "counterfact", "breaker", "umbra", "survey" ] } }, "dataClass": { "type": "string", "enum": [ "interaction_events", "message_streams", "task_contexts", "trace_records" ] }, "granularity": { "default": "aggregate_only", "type": "string", "enum": [ "aggregate_only", "identified_internal" ] } }, "required": [ "workspaceId", "products", "dataClass" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Grant consent.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "products": [ "rapport", "survey" ], "dataClass": "interaction_events", "granularity": "aggregate_only" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "grantId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "receipt": { "type": "string" }, "status": { "type": "string" } }, "required": [ "grantId", "receipt", "status" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Grant consent.", "value": { "grantId": "01J9X4P9R7Z2C1A1F2A8VBJYG1", "receipt": "…", "status": "active" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.consent.manage" ] }, { "OAuth2": [ "paradigm.consent.manage" ] }, { "WorkspaceApiKey": [ "paradigm.consent.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/paradigm.consent.revoke": { "post": { "operationId": "paradigm_consent_revoke", "summary": "Revoke a consent grant — unaggregated contributed events are purged and the contributor is excluded from future cells.", "x-trustvice-description-key": "actions.paradigm.consent.revoke.description", "tags": [ "paradigm" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "grantId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "grantId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Revoke + purge.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "grantId": "01J9X4P9R7Z2C1A1F2A8VBJYG1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "revoked": { "type": "boolean" }, "purgedEvents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "revoked", "purgedEvents" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Revoke + purge.", "value": { "revoked": true, "purgedEvents": 412 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "paradigm.consent.manage" ] }, { "OAuth2": [ "paradigm.consent.manage" ] }, { "WorkspaceApiKey": [ "paradigm.consent.manage" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/driftvice.surface.connect": { "post": { "operationId": "driftvice_surface_connect", "summary": "Connect a surface where company language lives (BYO credentials) — the metered unit. Driftvice reads it with the access you scope.", "x-trustvice-description-key": "actions.driftvice.surface.connect.description", "tags": [ "driftvice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "class": { "type": "string", "enum": [ "analytics", "bi_semantic_layer", "warehouse", "documentation", "codebase", "ui_strings", "templates_crm", "api_spec", "spreadsheet", "project_pm", "communication" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "connectionRef": { "type": "string", "minLength": 1, "maxLength": 500 }, "scope": { "default": [], "maxItems": 500, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "syncSchedule": { "default": "daily", "type": "string", "enum": [ "manual", "hourly", "daily", "event" ] } }, "required": [ "workspaceId", "class", "label", "connectionRef" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Connect a BI surface.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "class": "bi_semantic_layer", "label": "Looker — growth project", "connectionRef": "conn_looker_001", "scope": [ "growth" ], "syncSchedule": "daily" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "surfaceId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "class": { "type": "string", "enum": [ "analytics", "bi_semantic_layer", "warehouse", "documentation", "codebase", "ui_strings", "templates_crm", "api_spec", "spreadsheet", "project_pm", "communication" ] }, "label": { "type": "string" }, "scope": { "type": "array", "items": { "type": "string" } }, "writeBackCapable": { "type": "boolean" }, "syncState": { "type": "string", "enum": [ "never", "syncing", "healthy", "stale", "error" ] }, "lastSyncAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "surfaceId", "workspaceId", "class", "label", "scope", "writeBackCapable", "syncState", "lastSyncAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Connect a BI surface.", "value": { "surfaceId": "01J9X4P9R7Z2C1A1F2A8VBJYS1", "workspaceId": "ws_DEMODEFAULT0000000000", "class": "bi_semantic_layer", "label": "Looker — growth project", "scope": [ "growth" ], "writeBackCapable": true, "syncState": "never", "lastSyncAt": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "driftvice.surfaces.connect" ] }, { "OAuth2": [ "driftvice.surfaces.connect" ] }, { "WorkspaceApiKey": [ "driftvice.surfaces.connect" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/driftvice.surface.list": { "post": { "operationId": "driftvice_surface_list", "summary": "List the connected surfaces in a workspace with their sync health.", "x-trustvice-description-key": "actions.driftvice.surface.list.description", "tags": [ "driftvice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "class": { "type": "string", "enum": [ "analytics", "bi_semantic_layer", "warehouse", "documentation", "codebase", "ui_strings", "templates_crm", "api_spec", "spreadsheet", "project_pm", "communication" ] } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List surfaces.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "surfaces": { "type": "array", "items": { "type": "object", "properties": { "surfaceId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "class": { "type": "string", "enum": [ "analytics", "bi_semantic_layer", "warehouse", "documentation", "codebase", "ui_strings", "templates_crm", "api_spec", "spreadsheet", "project_pm", "communication" ] }, "label": { "type": "string" }, "scope": { "type": "array", "items": { "type": "string" } }, "writeBackCapable": { "type": "boolean" }, "syncState": { "type": "string", "enum": [ "never", "syncing", "healthy", "stale", "error" ] }, "lastSyncAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "surfaceId", "workspaceId", "class", "label", "scope", "writeBackCapable", "syncState", "lastSyncAt" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "surfaces", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List surfaces.", "value": { "surfaces": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "driftvice.surfaces.view" ] }, { "OAuth2": [ "driftvice.surfaces.view" ] }, { "WorkspaceApiKey": [ "driftvice.surfaces.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/driftvice.surface.sync": { "post": { "operationId": "driftvice_surface_sync", "summary": "Trigger an incremental re-sync + re-extraction of a connected surface.", "x-trustvice-description-key": "actions.driftvice.surface.sync.description", "tags": [ "driftvice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "surfaceId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "required": [ "workspaceId", "surfaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Re-sync a surface.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "surfaceId": "01J9X4P9R7Z2C1A1F2A8VBJYS1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "surfaceId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "syncState": { "type": "string", "enum": [ "syncing", "healthy", "stale", "error" ] }, "queuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "surfaceId", "syncState", "queuedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Re-sync a surface.", "value": { "surfaceId": "01J9X4P9R7Z2C1A1F2A8VBJYS1", "syncState": "syncing", "queuedAt": "2026-06-14T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "driftvice.surfaces.edit" ] }, { "OAuth2": [ "driftvice.surfaces.edit" ] }, { "WorkspaceApiKey": [ "driftvice.surfaces.edit" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/driftvice.surface.revoke": { "post": { "operationId": "driftvice_surface_revoke", "summary": "Revoke a connected surface — purges its derived usages per the platform's data-handling terms.", "x-trustvice-description-key": "actions.driftvice.surface.revoke.description", "tags": [ "driftvice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "surfaceId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "surfaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Revoke + purge.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "surfaceId": "01J9X4P9R7Z2C1A1F2A8VBJYS1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "revoked": { "type": "boolean" }, "usagesPurged": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "revoked", "usagesPurged" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Revoke + purge.", "value": { "revoked": true, "usagesPurged": 412 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "driftvice.surfaces.revoke" ] }, { "OAuth2": [ "driftvice.surfaces.revoke" ] }, { "WorkspaceApiKey": [ "driftvice.surfaces.revoke" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/driftvice.glossary.search": { "post": { "operationId": "driftvice_glossary_search", "summary": "Semantic search over the DERIVED glossary — a projection of the live language graph, never an authored document.", "x-trustvice-description-key": "actions.driftvice.glossary.search.description", "tags": [ "driftvice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "query": { "type": "string", "minLength": 1, "maxLength": 500 }, "limit": { "default": 10, "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "workspaceId", "query" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Search the glossary.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "query": "active user" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "canonId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "conceptId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "canonicalName": { "type": "string" }, "authoritativeDefinition": { "type": "string" }, "approvedAliases": { "type": "array", "items": { "type": "string" } }, "scopeRules": { "type": "object", "properties": { "inclusion": { "type": "array", "items": { "type": "string" } }, "exclusion": { "type": "array", "items": { "type": "string" } } }, "required": [ "inclusion", "exclusion" ], "additionalProperties": false }, "tier": { "anyOf": [ { "type": "number", "const": 1 }, { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ] }, "governanceState": { "type": "string", "enum": [ "proposed", "canonical", "deprecated" ] }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "driftStatus": { "type": "string", "enum": [ "settled", "open_drift" ] } }, "required": [ "canonId", "workspaceId", "conceptId", "canonicalName", "authoritativeDefinition", "approvedAliases", "scopeRules", "tier", "governanceState", "version", "driftStatus" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "entries", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Search the glossary.", "value": { "entries": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "driftvice.glossary.view" ] }, { "OAuth2": [ "driftvice.glossary.view" ] }, { "WorkspaceApiKey": [ "driftvice.glossary.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/driftvice.term.resolve": { "post": { "operationId": "driftvice_term_resolve", "summary": "Resolve a term to its canonical definition, approved aliases, and scope rules — with governance + drift status, so an agent knows settled vs drifting before it acts.", "x-trustvice-description-key": "actions.driftvice.term.resolve.description", "tags": [ "driftvice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "term": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "workspaceId", "term" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Resolve a term to canon.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "term": "active user" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "resolved": { "type": "boolean" }, "canon": { "anyOf": [ { "type": "object", "properties": { "canonId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "conceptId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "canonicalName": { "type": "string" }, "authoritativeDefinition": { "type": "string" }, "approvedAliases": { "type": "array", "items": { "type": "string" } }, "scopeRules": { "type": "object", "properties": { "inclusion": { "type": "array", "items": { "type": "string" } }, "exclusion": { "type": "array", "items": { "type": "string" } } }, "required": [ "inclusion", "exclusion" ], "additionalProperties": false }, "tier": { "anyOf": [ { "type": "number", "const": 1 }, { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ] }, "governanceState": { "type": "string", "enum": [ "proposed", "canonical", "deprecated" ] }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "driftStatus": { "type": "string", "enum": [ "settled", "open_drift" ] } }, "required": [ "canonId", "workspaceId", "conceptId", "canonicalName", "authoritativeDefinition", "approvedAliases", "scopeRules", "tier", "governanceState", "version", "driftStatus" ], "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "resolved", "canon" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Resolve a term to canon.", "value": { "resolved": false, "canon": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "driftvice.glossary.view" ] }, { "OAuth2": [ "driftvice.glossary.view" ] }, { "WorkspaceApiKey": [ "driftvice.glossary.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/driftvice.metric.definition": { "post": { "operationId": "driftvice_metric_definition", "summary": "Return a metric's canonical computation (normalized + renderings) and whether surfaces currently diverge from it.", "x-trustvice-description-key": "actions.driftvice.metric.definition.description", "tags": [ "driftvice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "metric": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "workspaceId", "metric" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Get a metric's canon computation.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "metric": "MRR" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conceptId": { "anyOf": [ { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "canonicalComputation": { "anyOf": [ { "type": "object", "properties": { "normalized": { "type": "string" }, "renderings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": [ "normalized" ], "additionalProperties": false }, { "type": "null" } ] }, "divergingSurfaceCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "conceptId", "canonicalComputation", "divergingSurfaceCount" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Get a metric's canon computation.", "value": { "conceptId": null, "canonicalComputation": null, "divergingSurfaceCount": 0 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "driftvice.glossary.view" ] }, { "OAuth2": [ "driftvice.glossary.view" ] }, { "WorkspaceApiKey": [ "driftvice.glossary.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/driftvice.term.check": { "post": { "operationId": "driftvice_term_check", "summary": "Check a definition or computation an agent is about to use against canon — report conformance or the specific drift.", "x-trustvice-description-key": "actions.driftvice.term.check.description", "tags": [ "driftvice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "term": { "type": "string", "minLength": 1, "maxLength": 200 }, "definition": { "type": "string", "maxLength": 2000 }, "computation": { "type": "string", "maxLength": 4000 } }, "required": [ "workspaceId", "term" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Check a definition against canon.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "term": "active user", "definition": "logged in within 30 days" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conforms": { "type": "boolean" }, "driftType": { "anyOf": [ { "type": "string", "enum": [ "definitional_conflict", "canon_vs_usage", "naming_stale_alias", "naming_synonymy", "naming_polysemy", "metric_computation", "scope_boundary", "temporal", "lineage_break", "ungoverned_heavy_usage", "orphaned_canon", "ownership_gap" ] }, { "type": "null" } ] }, "explanation": { "type": "string" } }, "required": [ "conforms", "driftType", "explanation" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Check a definition against canon.", "value": { "conforms": true, "driftType": null, "explanation": "Matches canon (30-day window, excludes internal accounts)." } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "driftvice.glossary.view" ] }, { "OAuth2": [ "driftvice.glossary.view" ] }, { "WorkspaceApiKey": [ "driftvice.glossary.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/driftvice.canon.status": { "post": { "operationId": "driftvice_canon_status", "summary": "Get a concept's governance state, owner, coherence, and any linked decisions.", "x-trustvice-description-key": "actions.driftvice.canon.status.description", "tags": [ "driftvice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "conceptId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "required": [ "workspaceId", "conceptId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read canon status.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "conceptId": "01J9X4P9R7Z2C1A1F2A8VBJYC1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conceptId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "state": { "type": "string", "enum": [ "ungoverned", "proposed", "canonical", "deprecated", "orphaned" ] }, "ownerRef": { "type": [ "string", "null" ] }, "openDriftCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "linkedDecisions": { "type": "array", "items": { "type": "string" } } }, "required": [ "conceptId", "state", "ownerRef", "openDriftCount", "linkedDecisions" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read canon status.", "value": { "conceptId": "01J9X4P9R7Z2C1A1F2A8VBJYC1", "state": "canonical", "ownerRef": "team:growth", "openDriftCount": 0, "linkedDecisions": [ "Q3 board deck" ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "driftvice.canon.view" ] }, { "OAuth2": [ "driftvice.canon.view" ] }, { "WorkspaceApiKey": [ "driftvice.canon.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/driftvice.drift.list": { "post": { "operationId": "driftvice_drift_list", "summary": "Query the open drift feed — filter by type, severity, surface, domain, owner, or state.", "x-trustvice-description-key": "actions.driftvice.drift.list.description", "tags": [ "driftvice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "type": { "type": "string", "enum": [ "definitional_conflict", "canon_vs_usage", "naming_stale_alias", "naming_synonymy", "naming_polysemy", "metric_computation", "scope_boundary", "temporal", "lineage_break", "ungoverned_heavy_usage", "orphaned_canon", "ownership_gap" ] }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "state": { "type": "string", "enum": [ "open", "routed", "in_resolution", "resolved", "accepted", "suppressed" ] } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List open drift.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "severity": "high" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "drift": { "type": "array", "items": { "type": "object", "properties": { "driftId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "type": { "type": "string", "enum": [ "definitional_conflict", "canon_vs_usage", "naming_stale_alias", "naming_synonymy", "naming_polysemy", "metric_computation", "scope_boundary", "temporal", "lineage_break", "ungoverned_heavy_usage", "orphaned_canon", "ownership_gap" ] }, "conceptId": { "anyOf": [ { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, { "type": "null" } ] }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "blastRadius": { "type": "integer", "minimum": 0, "maximum": 100 }, "state": { "type": "string", "enum": [ "open", "routed", "in_resolution", "resolved", "accepted", "suppressed" ] } }, "required": [ "driftId", "workspaceId", "type", "conceptId", "severity", "blastRadius", "state" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "drift", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List open drift.", "value": { "drift": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "driftvice.drift.view" ] }, { "OAuth2": [ "driftvice.drift.view" ] }, { "WorkspaceApiKey": [ "driftvice.drift.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/driftvice.drift.resolve": { "post": { "operationId": "driftvice_drift_resolve", "summary": "Resolve a drift via an owner decision: declare canon, merge/split concepts, approve/deprecate an alias, adjust scope, or accept the divergence with rationale.", "x-trustvice-description-key": "actions.driftvice.drift.resolve.description", "tags": [ "driftvice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "driftId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "action": { "type": "string", "enum": [ "declare_canon", "merge_concepts", "split_concept", "approve_alias", "deprecate_alias", "adjust_scope", "accept_divergence" ] }, "decisionPayload": { "default": {}, "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "workspaceId", "driftId", "action" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Resolve drift by declaring canon.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "driftId": "01J9X4P9R7Z2C1A1F2A8VBJYD1", "action": "declare_canon", "decisionPayload": { "canonicalName": "active user", "authoritativeDefinition": "logged in within 30 days, excluding internal accounts" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reconciliationId": { "type": "string" }, "driftId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "propagationState": { "type": "string", "enum": [ "pending", "partial", "conformed" ] } }, "required": [ "reconciliationId", "driftId", "propagationState" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Resolve drift by declaring canon.", "value": { "reconciliationId": "01J9X4P9R7Z2C1A1F2A8VBJYR1", "driftId": "01J9X4P9R7Z2C1A1F2A8VBJYD1", "propagationState": "pending" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "driftvice.drift.resolve" ] }, { "OAuth2": [ "driftvice.drift.resolve" ] }, { "WorkspaceApiKey": [ "driftvice.drift.resolve" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/driftvice.canon.declare": { "post": { "operationId": "driftvice_canon_declare", "summary": "Declare canon for a concept — the authoritative definition, approved aliases, scope rules, and (for metrics) the canonical computation. Anchored to the deriving usages.", "x-trustvice-description-key": "actions.driftvice.canon.declare.description", "tags": [ "driftvice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "conceptId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "canonicalName": { "type": "string", "minLength": 1, "maxLength": 200 }, "authoritativeDefinition": { "type": "string", "minLength": 1, "maxLength": 2000 }, "approvedAliases": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 200 } }, "scopeRules": { "type": "object", "properties": { "inclusion": { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 200 } }, "exclusion": { "maxItems": 100, "type": "array", "items": { "type": "string", "maxLength": 200 } } }, "required": [ "inclusion", "exclusion" ] }, "tier": { "default": 2, "anyOf": [ { "type": "number", "const": 1 }, { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ] } }, "required": [ "workspaceId", "conceptId", "canonicalName", "authoritativeDefinition" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Declare canon.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "conceptId": "01J9X4P9R7Z2C1A1F2A8VBJYC1", "canonicalName": "active user", "authoritativeDefinition": "logged in within 30 days, excluding internal accounts", "tier": 1 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "canonId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "conceptId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "canonicalName": { "type": "string" }, "authoritativeDefinition": { "type": "string" }, "approvedAliases": { "type": "array", "items": { "type": "string" } }, "scopeRules": { "type": "object", "properties": { "inclusion": { "type": "array", "items": { "type": "string" } }, "exclusion": { "type": "array", "items": { "type": "string" } } }, "required": [ "inclusion", "exclusion" ], "additionalProperties": false }, "tier": { "anyOf": [ { "type": "number", "const": 1 }, { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ] }, "governanceState": { "type": "string", "enum": [ "proposed", "canonical", "deprecated" ] }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "driftStatus": { "type": "string", "enum": [ "settled", "open_drift" ] } }, "required": [ "canonId", "workspaceId", "conceptId", "canonicalName", "authoritativeDefinition", "approvedAliases", "scopeRules", "tier", "governanceState", "version", "driftStatus" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Declare canon.", "value": { "canonId": "01J9X4P9R7Z2C1A1F2A8VBJYK1", "workspaceId": "ws_DEMODEFAULT0000000000", "conceptId": "01J9X4P9R7Z2C1A1F2A8VBJYC1", "canonicalName": "active user", "authoritativeDefinition": "logged in within 30 days, excluding internal accounts", "approvedAliases": [], "scopeRules": { "inclusion": [], "exclusion": [ "internal accounts" ] }, "tier": 1, "governanceState": "canonical", "version": 1, "driftStatus": "settled" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "driftvice.canon.declare" ] }, { "OAuth2": [ "driftvice.canon.declare" ] }, { "WorkspaceApiKey": [ "driftvice.canon.declare" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/driftvice.coherence.summary": { "post": { "operationId": "driftvice_coherence_summary", "summary": "Get language-coherence scores per surface, per domain, and company-wide, with trends — plus ungoverned heavy-usage terms awaiting governance.", "x-trustvice-description-key": "actions.driftvice.coherence.summary.description", "tags": [ "driftvice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "scope": { "default": "company", "type": "string", "enum": [ "surface", "domain", "company" ] } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read coherence.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "scope": "company" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scores": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "surface", "domain", "company" ] }, "scopeRef": { "type": [ "string", "null" ] }, "score": { "type": "number", "minimum": 0, "maximum": 100 }, "trend": { "type": "string", "enum": [ "improving", "flat", "regressing" ] } }, "required": [ "scope", "scopeRef", "score", "trend" ], "additionalProperties": false } }, "ungovernedTopTerms": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "usageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "surfaceSpread": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "label", "usageCount", "surfaceSpread" ], "additionalProperties": false } } }, "required": [ "scores", "ungovernedTopTerms" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read coherence.", "value": { "scores": [ { "scope": "company", "scopeRef": null, "score": 78, "trend": "improving" } ], "ungovernedTopTerms": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "driftvice.glossary.view" ] }, { "OAuth2": [ "driftvice.glossary.view" ] }, { "WorkspaceApiKey": [ "driftvice.glossary.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/driftvice.canon.attest": { "post": { "operationId": "driftvice_canon_attest", "summary": "Issue a signed canon attestation — a verifiable snapshot of a canonical definition + governance + drift status at this time, so the ground-truth answer can be proven authentic.", "x-trustvice-description-key": "actions.driftvice.canon.attest.description", "tags": [ "driftvice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "canonId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "required": [ "workspaceId", "canonId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Issue a canon attestation.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "canonId": "01J9X4P9R7Z2C1A1F2A8VBJYK1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "version": { "type": "string" }, "attestationId": { "type": "string" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "type": { "type": "string", "const": "canon.attest" }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "signature": { "type": "string" }, "signatureKeyId": { "type": "string", "pattern": "^[a-z0-9-]{4,64}$" }, "body": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "version", "attestationId", "type", "issuedAt", "signature", "signatureKeyId", "body" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Issue a canon attestation.", "value": { "version": "1", "attestationId": "01J9X4P9R7Z2C1A1F2A8VBJYA1", "type": "canon.attest", "issuedAt": "2026-06-14T12:00:00.000Z", "signature": "...", "signatureKeyId": "driftvice-2026-q2-enam", "body": {} } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "driftvice.canon.attest" ] }, { "OAuth2": [ "driftvice.canon.attest" ] }, { "WorkspaceApiKey": [ "driftvice.canon.attest" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/driftvice.canon.verify": { "post": { "operationId": "driftvice_canon_verify", "summary": "Verify a canon attestation's Ed25519 signature against the published Driftvice public keys. Public — no account required. Cannot be disabled.", "x-trustvice-description-key": "actions.driftvice.canon.verify.description", "tags": [ "driftvice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "attestation": { "type": "object", "properties": { "version": { "type": "string" }, "attestationId": { "type": "string" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "type": { "type": "string", "const": "canon.attest" }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "signature": { "type": "string" }, "signatureKeyId": { "type": "string", "pattern": "^[a-z0-9-]{4,64}$" }, "body": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "version", "attestationId", "type", "issuedAt", "signature", "signatureKeyId", "body" ], "additionalProperties": {} } }, "required": [ "attestation" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify a canon attestation.", "value": { "attestation": { "version": "1", "attestationId": "01J9X4P9R7Z2C1A1F2A8VBJYA1", "type": "canon.attest", "issuedAt": "2026-06-14T12:00:00.000Z", "signature": "...", "signatureKeyId": "driftvice-2026-q2-enam", "body": {} } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "signedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "signatureKeyId": { "type": "string" }, "signerDid": { "type": "string" }, "artifact": { "type": "string" }, "publishedKeyUrl": { "type": "string", "format": "uri" } }, "required": [ "ok", "signedAt", "signatureKeyId", "signerDid", "artifact", "publishedKeyUrl" ], "additionalProperties": {} }, { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "reason": { "type": "string", "enum": [ "malformed_payload", "unknown_key", "bad_signature" ] }, "artifact": { "type": "string" }, "publishedKeyUrl": { "type": "string", "format": "uri" } }, "required": [ "ok", "reason", "artifact", "publishedKeyUrl" ], "additionalProperties": {} } ] }, "examples": { "example_0": { "summary": "Verify a canon attestation.", "value": { "ok": true, "signedAt": "2026-08-01T12:00:00.000Z", "signatureKeyId": "dKeyExampleBase64UrlAA", "signerDid": "did:web:trustvice.com", "artifact": "canon_attestation", "publishedKeyUrl": "https://api.trustvice.com/.well-known/driftvice-keys.json" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/driftvice.canon.guard": { "post": { "operationId": "driftvice_canon_guard", "summary": "Before acting on a concept, ask whether its live definition has drifted from canon far enough to warn or block. Blocking is deliberately hard to reach.", "x-trustvice-description-key": "actions.driftvice.canon.guard.description", "tags": [ "driftvice" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conceptId": { "type": "string", "minLength": 1 }, "policy": { "type": "object", "properties": { "blockOnComputationDivergenceAbove": { "description": "Block when this fraction of usages compute the concept differently. null = never block.", "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "warnAbove": { "type": "number", "minimum": 0, "maximum": 1 }, "neverBlockConcepts": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "additionalProperties": false } }, "required": [ "conceptId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "A guard that halts real work daily is a guard people disable.", "value": { "conceptId": "revenue" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "verdict": { "type": "object", "properties": { "conceptId": { "type": "string" }, "disposition": { "type": "string", "enum": [ "allow", "warn", "block" ] }, "state": { "type": "string" }, "measured": { "type": "number" }, "diverging": { "type": "number" }, "divergenceRate": { "type": [ "number", "null" ] }, "computationDiverging": { "type": "number" }, "computationRate": { "type": [ "number", "null" ] }, "citedUsages": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } } }, "required": [ "conceptId", "disposition", "state", "measured", "diverging", "divergenceRate", "computationDiverging", "computationRate", "citedUsages" ], "additionalProperties": {} }, "reportOnly": { "type": "boolean", "description": "True when the caller ran the guard in explicit report-only mode." }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "verdict", "reportOnly", "notes" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "A guard that halts real work daily is a guard people disable.", "value": { "verdict": { "conceptId": "revenue", "disposition": "warn", "state": "conformant", "measured": 12, "diverging": 2, "divergenceRate": 0.1667, "computationDiverging": 0, "computationRate": 0, "citedUsages": [] }, "reportOnly": false, "notes": [ "2 of 12 live usages diverge from canon; none diverge in computation, so this warns and does not block." ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "driftvice.canon.view" ] }, { "OAuth2": [ "driftvice.canon.view" ] }, { "WorkspaceApiKey": [ "driftvice.canon.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/fabric.retrieve.signed": { "post": { "operationId": "fabric_retrieve_signed", "summary": "Query extracted records AND get a signed-retrieval receipt source built from exactly the rows returned — so a downstream claim can prove what grounded it.", "x-trustvice-description-key": "actions.fabric.retrieve.signed.description", "tags": [ "fabric" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "kinds": { "maxItems": 23, "type": "array", "items": { "type": "string", "enum": [ "code-identifier", "commit", "review", "approval", "doc-chunk", "prose-section", "glossary-entry", "policy-clause", "faq-entry", "published-article", "metric-definition", "view-definition", "warehouse-schema", "api-spec-field", "event-taxonomy", "ui-string", "spreadsheet-row", "communication-message", "communication-thread", "ticket", "pricing-rule", "invoice-row", "webhook-event" ] } }, "sourceId": { "type": "string" }, "connectionId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "subscriber": { "type": "string", "enum": [ "trustactor", "entpoind", "nexus", "vector", "agorade", "pricevice", "paradigm", "driftvice", "actionflow", "norman", "trustmag" ] }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Retrieve policy clauses and receive the receipt source for exactly those rows.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "kinds": [ "policy-clause" ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "records": { "type": "array", "items": { "type": "object", "properties": { "recordId": { "type": "string" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "sourceId": { "type": "string" }, "connectionId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "kind": { "type": "string", "enum": [ "code-identifier", "commit", "review", "approval", "doc-chunk", "prose-section", "glossary-entry", "policy-clause", "faq-entry", "published-article", "metric-definition", "view-definition", "warehouse-schema", "api-spec-field", "event-taxonomy", "ui-string", "spreadsheet-row", "communication-message", "communication-thread", "ticket", "pricing-rule", "invoice-row", "webhook-event" ] }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "extractedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "contentHash": { "type": "string" }, "anchorUrl": { "type": [ "string", "null" ] } }, "required": [ "recordId", "workspaceId", "sourceId", "connectionId", "kind", "payload", "observedAt", "extractedAt", "contentHash", "anchorUrl" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] }, "mint": { "type": "object", "properties": { "kind": { "type": "string", "const": "signed-retrieval" }, "source": { "type": "object", "properties": { "retrievalRef": { "type": "string" }, "queryHash": { "type": "string" }, "retrievalMethod": { "type": "string", "enum": [ "embedding", "filter" ] }, "embeddingModel": { "type": [ "string", "null" ] }, "sources": { "type": "array", "items": { "type": "object", "properties": { "sourceRef": { "type": "string" }, "contentSha256": { "type": "string" } }, "required": [ "sourceRef", "contentSha256" ], "additionalProperties": {} } }, "retrievedAt": { "type": "string" } }, "required": [ "retrievalRef", "queryHash", "retrievalMethod", "embeddingModel", "sources", "retrievedAt" ], "additionalProperties": {} } }, "required": [ "kind", "source" ], "additionalProperties": false } }, "required": [ "records", "nextCursor", "mint" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Retrieve policy clauses and receive the receipt source for exactly those rows.", "value": { "records": [], "nextCursor": null, "mint": { "kind": "signed-retrieval", "source": { "retrievalRef": "ret_abc", "queryHash": "abc123", "retrievalMethod": "filter", "embeddingModel": null, "sources": [], "retrievedAt": "2026-09-04T00:00:00.000Z" } } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "fabric.records.view" ] }, { "OAuth2": [ "fabric.records.view" ] }, { "WorkspaceApiKey": [ "fabric.records.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/fabric.sources.catalog": { "post": { "operationId": "fabric_sources_catalog", "summary": "List the connectable source catalog (128 sources across 11 surface classes) with their auth method + emitted record kinds.", "x-trustvice-description-key": "actions.fabric.sources.catalog.description", "tags": [ "fabric" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "surfaceClass": { "type": "string", "enum": [ "analytics", "bi_semantic_layer", "warehouse", "documentation", "codebase", "ui_strings", "templates_crm", "api_spec", "spreadsheet", "project_pm", "communication" ] }, "query": { "type": "string", "maxLength": 200 } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Browse warehouse sources.", "value": { "surfaceClass": "warehouse" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "vendor": { "type": "string" }, "surfaceClass": { "type": "string", "enum": [ "analytics", "bi_semantic_layer", "warehouse", "documentation", "codebase", "ui_strings", "templates_crm", "api_spec", "spreadsheet", "project_pm", "communication" ] }, "authMethod": { "type": "string" }, "writeBackCapable": { "type": "boolean" }, "status": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "vendor", "surfaceClass", "authMethod", "writeBackCapable", "status", "description" ], "additionalProperties": {} } } }, "required": [ "sources" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Browse warehouse sources.", "value": { "sources": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "fabric.connections.view" ] }, { "OAuth2": [ "fabric.connections.view" ] }, { "WorkspaceApiKey": [ "fabric.connections.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/fabric.connections.connect": { "post": { "operationId": "fabric_connections_connect", "summary": "Connect a catalog source (BYO credentials) into the fabric. The connection's records broadcast to every subscribing product.", "x-trustvice-description-key": "actions.fabric.connections.connect.description", "tags": [ "fabric" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 120 }, "label": { "type": "string", "minLength": 1, "maxLength": 200 }, "scope": { "default": [], "maxItems": 500, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "syncSchedule": { "default": "daily", "type": "string", "enum": [ "manual", "hourly", "daily", "event" ] }, "connectionRef": { "type": "string", "maxLength": 500 } }, "required": [ "workspaceId", "sourceId", "label" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Connect GitHub.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "sourceId": "github", "label": "acme/app", "scope": [ "acme/app" ], "syncSchedule": "event" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "connectionId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "sourceId": { "type": "string" }, "surfaceClass": { "type": "string", "enum": [ "analytics", "bi_semantic_layer", "warehouse", "documentation", "codebase", "ui_strings", "templates_crm", "api_spec", "spreadsheet", "project_pm", "communication" ] }, "authMethod": { "type": "string", "enum": [ "oauth2", "api_key", "personal_access_token", "service_account_key", "basic_auth", "byo_credential", "file_upload" ] }, "label": { "type": "string" }, "scope": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string", "enum": [ "pending", "connected", "error", "revoked" ] }, "syncState": { "type": "string", "enum": [ "never", "syncing", "healthy", "stale", "error" ] }, "emits": { "type": "array", "items": { "type": "string", "enum": [ "code-identifier", "commit", "review", "approval", "doc-chunk", "prose-section", "glossary-entry", "policy-clause", "faq-entry", "published-article", "metric-definition", "view-definition", "warehouse-schema", "api-spec-field", "event-taxonomy", "ui-string", "spreadsheet-row", "communication-message", "communication-thread", "ticket", "pricing-rule", "invoice-row", "webhook-event" ] } }, "lastSyncAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "connectionId", "workspaceId", "sourceId", "surfaceClass", "authMethod", "label", "scope", "state", "syncState", "emits", "lastSyncAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Connect GitHub.", "value": { "connectionId": "01J9X4P9R7Z2C1A1F2A8VBJYS1", "workspaceId": "ws_DEMODEFAULT0000000000", "sourceId": "github", "surfaceClass": "codebase", "authMethod": "personal_access_token", "label": "acme/app", "scope": [ "acme/app" ], "state": "pending", "syncState": "never", "emits": [ "code-identifier", "doc-chunk" ], "lastSyncAt": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "fabric.connections.connect" ] }, { "OAuth2": [ "fabric.connections.connect" ] }, { "WorkspaceApiKey": [ "fabric.connections.connect" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/fabric.connections.list": { "post": { "operationId": "fabric_connections_list", "summary": "List the workspace's fabric connections with their sync health.", "x-trustvice-description-key": "actions.fabric.connections.list.description", "tags": [ "fabric" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "sourceId": { "type": "string" }, "surfaceClass": { "type": "string", "enum": [ "analytics", "bi_semantic_layer", "warehouse", "documentation", "codebase", "ui_strings", "templates_crm", "api_spec", "spreadsheet", "project_pm", "communication" ] } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List connections.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "properties": { "connectionId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "sourceId": { "type": "string" }, "surfaceClass": { "type": "string", "enum": [ "analytics", "bi_semantic_layer", "warehouse", "documentation", "codebase", "ui_strings", "templates_crm", "api_spec", "spreadsheet", "project_pm", "communication" ] }, "authMethod": { "type": "string", "enum": [ "oauth2", "api_key", "personal_access_token", "service_account_key", "basic_auth", "byo_credential", "file_upload" ] }, "label": { "type": "string" }, "scope": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string", "enum": [ "pending", "connected", "error", "revoked" ] }, "syncState": { "type": "string", "enum": [ "never", "syncing", "healthy", "stale", "error" ] }, "emits": { "type": "array", "items": { "type": "string", "enum": [ "code-identifier", "commit", "review", "approval", "doc-chunk", "prose-section", "glossary-entry", "policy-clause", "faq-entry", "published-article", "metric-definition", "view-definition", "warehouse-schema", "api-spec-field", "event-taxonomy", "ui-string", "spreadsheet-row", "communication-message", "communication-thread", "ticket", "pricing-rule", "invoice-row", "webhook-event" ] } }, "lastSyncAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "connectionId", "workspaceId", "sourceId", "surfaceClass", "authMethod", "label", "scope", "state", "syncState", "emits", "lastSyncAt" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "connections", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List connections.", "value": { "connections": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "fabric.connections.view" ] }, { "OAuth2": [ "fabric.connections.view" ] }, { "WorkspaceApiKey": [ "fabric.connections.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/fabric.connections.sync": { "post": { "operationId": "fabric_connections_sync", "summary": "Enqueue an on-demand sync + re-extraction of a fabric connection.", "x-trustvice-description-key": "actions.fabric.connections.sync.description", "tags": [ "fabric" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "connectionId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "required": [ "workspaceId", "connectionId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Sync now.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "connectionId": "01J9X4P9R7Z2C1A1F2A8VBJYS1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "enqueued": { "type": "boolean" }, "connectionId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "required": [ "enqueued", "connectionId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Sync now.", "value": { "enqueued": true, "connectionId": "01J9X4P9R7Z2C1A1F2A8VBJYS1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "fabric.connections.edit" ] }, { "OAuth2": [ "fabric.connections.edit" ] }, { "WorkspaceApiKey": [ "fabric.connections.edit" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/fabric.connections.revoke": { "post": { "operationId": "fabric_connections_revoke", "summary": "Revoke a fabric connection — purges its extracted records per the platform's data-handling terms.", "x-trustvice-description-key": "actions.fabric.connections.revoke.description", "tags": [ "fabric" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "connectionId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "connectionId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Revoke + purge.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "connectionId": "01J9X4P9R7Z2C1A1F2A8VBJYS1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "revoked": { "type": "boolean" }, "recordsPurged": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "revoked", "recordsPurged" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Revoke + purge.", "value": { "revoked": true, "recordsPurged": 1280 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "fabric.connections.revoke" ] }, { "OAuth2": [ "fabric.connections.revoke" ] }, { "WorkspaceApiKey": [ "fabric.connections.revoke" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/fabric.records.query": { "post": { "operationId": "fabric_records_query", "summary": "Query extracted records by kind / source / subscriber — the universal read every product (and agent) uses to consume the fabric.", "x-trustvice-description-key": "actions.fabric.records.query.description", "tags": [ "fabric" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "kinds": { "maxItems": 23, "type": "array", "items": { "type": "string", "enum": [ "code-identifier", "commit", "review", "approval", "doc-chunk", "prose-section", "glossary-entry", "policy-clause", "faq-entry", "published-article", "metric-definition", "view-definition", "warehouse-schema", "api-spec-field", "event-taxonomy", "ui-string", "spreadsheet-row", "communication-message", "communication-thread", "ticket", "pricing-rule", "invoice-row", "webhook-event" ] } }, "sourceId": { "type": "string" }, "connectionId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "subscriber": { "type": "string", "enum": [ "trustactor", "entpoind", "nexus", "vector", "agorade", "pricevice", "paradigm", "driftvice", "actionflow", "norman", "trustmag" ] }, "since": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read policy clauses across all sources.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "kinds": [ "policy-clause" ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "records": { "type": "array", "items": { "type": "object", "properties": { "recordId": { "type": "string" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "sourceId": { "type": "string" }, "connectionId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "kind": { "type": "string", "enum": [ "code-identifier", "commit", "review", "approval", "doc-chunk", "prose-section", "glossary-entry", "policy-clause", "faq-entry", "published-article", "metric-definition", "view-definition", "warehouse-schema", "api-spec-field", "event-taxonomy", "ui-string", "spreadsheet-row", "communication-message", "communication-thread", "ticket", "pricing-rule", "invoice-row", "webhook-event" ] }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "extractedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "contentHash": { "type": "string" }, "anchorUrl": { "type": [ "string", "null" ] } }, "required": [ "recordId", "workspaceId", "sourceId", "connectionId", "kind", "payload", "observedAt", "extractedAt", "contentHash", "anchorUrl" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "records", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read policy clauses across all sources.", "value": { "records": [], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "fabric.records.view" ] }, { "OAuth2": [ "fabric.records.view" ] }, { "WorkspaceApiKey": [ "fabric.records.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/fabric.subscriptions.matrix": { "post": { "operationId": "fabric_subscriptions_matrix", "summary": "Return the fabric subscription matrix — which product consumes which record kinds, and how many products each kind powers.", "x-trustvice-description-key": "actions.fabric.subscriptions.matrix.description", "tags": [ "fabric" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subscriber": { "type": "string", "enum": [ "trustactor", "entpoind", "nexus", "vector", "agorade", "pricevice", "paradigm", "driftvice", "actionflow", "norman", "trustmag" ] } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Introspect the matrix.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subscriptions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string", "enum": [ "code-identifier", "commit", "review", "approval", "doc-chunk", "prose-section", "glossary-entry", "policy-clause", "faq-entry", "published-article", "metric-definition", "view-definition", "warehouse-schema", "api-spec-field", "event-taxonomy", "ui-string", "spreadsheet-row", "communication-message", "communication-thread", "ticket", "pricing-rule", "invoice-row", "webhook-event" ] } } }, "kindReach": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "required": [ "subscriptions", "kindReach" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Introspect the matrix.", "value": { "subscriptions": {}, "kindReach": {} } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "fabric.connections.view" ] }, { "OAuth2": [ "fabric.connections.view" ] }, { "WorkspaceApiKey": [ "fabric.connections.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/actionflow.flows.list": { "post": { "operationId": "actionflow_flows_list", "summary": "List the workspace's ActionFlow flows.", "x-trustvice-description-key": "actions.actionflow.flows.list.description", "tags": [ "actionflow" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "List flows.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "List flows.", "value": { "flows": [ { "schemaVersion": "1.0", "id": "flow_incident", "workspaceId": "ws_example", "tenantId": "ws_example", "name": "Incident response", "description": "Page on-call, open a ticket, post to the channel.", "tags": [ "incident" ], "source": { "kind": "customer_authored" }, "triggers": [ { "kind": "webhook", "id": "trg_1" } ], "steps": [ { "id": "page", "kind": "http" } ], "version": { "semver": "1.0.0", "status": "published", "publishedAt": "2026-08-01T09:00:00.000Z" }, "authoredBy": "acct_1" } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/actionflow.flows.run": { "post": { "operationId": "actionflow_flows_run", "summary": "Run a flow — trigger an execution through the bounded graph engine.", "x-trustvice-description-key": "actions.actionflow.flows.run.description", "tags": [ "actionflow" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Flow id." }, "input": { "description": "Optional run input passed to the flow's variable scope." } }, "required": [ "id" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Run the incident flow.", "value": { "id": "flow_incident", "input": { "severity": "high" } } }, "example_1": { "summary": "Running an unpublished flow is refused, not silently skipped.", "value": { "id": "flow_draft", "input": {} } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Run the incident flow.", "value": { "execution": { "executionId": "exe_01M1F0000000000000000001", "flowId": "flow_incident", "flowVersion": "1.0.0", "workspaceId": "ws_example", "initiatedBy": { "kind": "agent", "agentId": "did:web:example.com:agent:ops" }, "triggeredBy": { "kind": "api" }, "status": "running", "stepStates": { "page": { "status": "succeeded", "completedAt": "2026-08-01T09:00:02.000Z" } } } } }, "example_1": { "summary": "Running an unpublished flow is refused, not silently skipped.", "value": { "error": "flow_not_published", "detail": "Flow flow_draft is not published." } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_invocation", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/actionflow.flows.publish": { "post": { "operationId": "actionflow_flows_publish", "summary": "Publish a flow (make the current draft the live version).", "x-trustvice-description-key": "actions.actionflow.flows.publish.description", "tags": [ "actionflow" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Publish a flow.", "value": { "id": "flow_incident" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Publish a flow.", "value": { "flow": { "schemaVersion": "1.0", "id": "flow_incident", "workspaceId": "ws_example", "tenantId": "ws_example", "name": "Incident response", "description": "Page on-call, open a ticket, post to the channel.", "tags": [ "incident" ], "source": { "kind": "customer_authored" }, "triggers": [ { "kind": "webhook", "id": "trg_1" } ], "steps": [ { "id": "page", "kind": "http" } ], "version": { "semver": "1.0.0", "status": "published", "publishedAt": "2026-08-01T09:00:00.000Z" }, "authoredBy": "acct_1" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_invocation", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/actionflow.templates.list": { "post": { "operationId": "actionflow_templates_list", "summary": "List the ActionFlow starter templates.", "x-trustvice-description-key": "actions.actionflow.templates.list.description", "tags": [ "actionflow" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Browse templates.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Browse templates.", "value": { "templates": [ { "id": "tmpl_incident_alert", "name": "Incident alert", "description": "Page on-call and open a ticket when an alert fires.", "tags": [ "incident", "alerting" ], "stepCount": 4, "triggerCount": 1 } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/actionflow.templates.instantiate": { "post": { "operationId": "actionflow_templates_instantiate", "summary": "Instantiate a template into a new draft flow in the workspace.", "x-trustvice-description-key": "actions.actionflow.templates.instantiate.description", "tags": [ "actionflow" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Template id." }, "name": { "type": "string", "maxLength": 120 } }, "required": [ "id" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Create a flow from a template.", "value": { "id": "tmpl_incident_alert", "name": "My incident flow" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Create a flow from a template.", "value": { "flow": { "schemaVersion": "1.0", "id": "flow_01M1F0000000000000000002", "workspaceId": "ws_example", "tenantId": "ws_example", "name": "My incident flow", "description": "Page on-call and open a ticket when an alert fires.", "tags": [ "incident", "alerting" ], "source": { "kind": "template", "templateId": "tmpl_incident_alert" }, "triggers": [ { "kind": "webhook", "id": "trg_1" } ], "steps": [ { "id": "page", "kind": "http" } ], "version": { "semver": "0.1.0", "status": "draft" }, "authoredBy": "acct_1" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_invocation", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/actionflow.executions.list": { "post": { "operationId": "actionflow_executions_list", "summary": "List recent ActionFlow executions.", "x-trustvice-description-key": "actions.actionflow.executions.list.description", "tags": [ "actionflow" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "List executions.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "List executions.", "value": { "executions": [ { "executionId": "exe_01M1F0000000000000000001", "flowId": "flow_incident", "flowVersion": "1.0.0", "workspaceId": "ws_example", "initiatedBy": { "kind": "agent", "agentId": "did:web:example.com:agent:ops" }, "triggeredBy": { "kind": "api" }, "status": "running", "stepStates": { "page": { "status": "succeeded", "completedAt": "2026-08-01T09:00:02.000Z" } } }, { "executionId": "exe_01M1F0000000000000000002", "flowId": "flow_incident", "flowVersion": "1.0.0", "workspaceId": "ws_example", "initiatedBy": { "kind": "api" }, "triggeredBy": { "kind": "webhook" }, "status": "awaiting_human_review", "stepStates": { "approve": { "status": "succeeded", "result": { "awaitingReview": true, "allowedDecisions": [ "approve", "reject" ] } } } } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/lens.list": { "post": { "operationId": "lens_list", "summary": "List the available compliance-evidence lenses.", "x-trustvice-description-key": "actions.lens.list.description", "tags": [ "lens" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Browse lenses.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Browse lenses.", "value": { "lenses": [ { "id": "lens_audit_activity", "name": "Audit Activity Summary", "version": "1.0.0", "description": "Counts and samples every audit-chain event in the window." } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/lens.execute": { "post": { "operationId": "lens_execute", "summary": "Execute a lens over the audit chain — produces a signed compliance-evidence bundle (a paid action).", "x-trustvice-description-key": "actions.lens.execute.description", "tags": [ "lens" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Lens id." }, "params": { "description": "Optional lens parameters (time window, scope, …)." } }, "required": [ "id" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Run a SOC 2 lens.", "value": { "id": "lens_audit_activity", "params": { "since": "2026-01-01T00:00:00.000Z" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Run a SOC 2 lens.", "value": { "ok": true, "resultId": "60e625a9-0cef-4e9f-ab6c-588e780a5a27", "signed": true, "bundle": { "lensId": "lens_audit_activity", "lensName": "Audit Activity Summary", "lensVersion": "1.0.0", "category": "operational", "contentHash": "fa439c11bed190031bc1479d087e5d201ace57d32f56b614133910ac1bdeec27", "executedAt": "2026-01-02T00:00:00.000Z", "rowsScanned": 128, "range": { "start": "2026-01-01T00:00:00.000Z", "end": "2026-01-02T00:00:00.000Z" }, "sections": [], "source": "audit_chain", "workspaceId": "ws_example", "signature": { "alg": "EdDSA", "signingKeyId": "43IS9jyB9T6B2q53OQAGng", "value": "…" } } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "billing", "x-trustvice-audit-kind": "agent_invocation", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/lens.validate": { "post": { "operationId": "lens_validate", "summary": "Validate a lens definition (dry-run; no evidence bundle, no charge).", "x-trustvice-description-key": "actions.lens.validate.description", "tags": [ "lens" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "definition": { "description": "The lens definition to validate." } }, "required": [ "definition" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Validate a lens.", "value": { "definition": { "framework": "soc2" } } }, "example_1": { "summary": "A definition that does not validate.", "value": { "definition": {} } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Validate a lens.", "value": { "ok": true } }, "example_1": { "summary": "A definition that does not validate.", "value": { "ok": false, "errors": [ "definition.framework is required" ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/lens.results.list": { "post": { "operationId": "lens_results_list", "summary": "List prior lens-execution results (the evidence-bundle history).", "x-trustvice-description-key": "actions.lens.results.list.description", "tags": [ "lens" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "List evidence bundles.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "List evidence bundles.", "value": { "results": [ { "id": "60e625a9-0cef-4e9f-ab6c-588e780a5a27", "lensId": "lens_audit_activity", "lensVersion": "1.0.0", "contentHash": "fa439c11bed190031bc1479d087e5d201ace57d32f56b614133910ac1bdeec27", "executedAt": "2026-01-02T00:00:00.000Z", "signed": true, "signingKeyId": "43IS9jyB9T6B2q53OQAGng", "status": "sealed" } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/notarian.snapshot.create": { "post": { "operationId": "notarian_snapshot_create", "summary": "Create a signed Notarian snapshot of the workspace's audit state (a paid action).", "x-trustvice-description-key": "actions.notarian.snapshot.create.description", "tags": [ "notarian" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scope": { "description": "Optional snapshot scope / label.", "type": "string" }, "params": {} }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Seal a signed snapshot.", "value": { "scope": "month-end" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Seal a signed snapshot.", "value": { "ok": true, "bundle": { "bundleId": "eb7f9624-1f91-45d9-a9a4-4f6adf0478ce", "workspaceId": "ws_example", "jurisdiction": "ENAM", "scope": "month-end", "rangeStart": "2026-01-01T00:00:00.000Z", "rangeEnd": "2026-01-31T23:59:59.999Z", "recordCount": 412, "merkleRoot": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "firstRecordId": "01M1F0000000000000000000A1", "lastRecordId": "01M1F0000000000000000000Z9", "snapshotAt": "2026-02-01T00:00:00.000Z", "records": [], "signingKeyId": "43IS9jyB9T6B2q53OQAGng", "ed25519Signature": "…" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "billing_impacting", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "billing", "x-trustvice-audit-kind": "agent_invocation", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/notarian.verify-chain": { "post": { "operationId": "notarian_verify-chain", "summary": "Verify the Notarian transparency chain (free — a transparency guarantee).", "x-trustvice-description-key": "actions.notarian.verify-chain.description", "tags": [ "notarian" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Prove the chain is intact.", "value": {} }, "example_1": { "summary": "A chain that does NOT verify — the request succeeded, the chain did not.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Prove the chain is intact.", "value": { "ok": true, "verification": { "ok": true, "workspaceId": "ws_example", "checkedCount": 412, "tipHash": "2a1865a1eb374e0590a5af631ad0999d7085075f7f1db581867a9be3574e1890" } } }, "example_1": { "summary": "A chain that does NOT verify — the request succeeded, the chain did not.", "value": { "ok": true, "verification": { "ok": false, "workspaceId": "ws_example", "checkedCount": 118, "breakAtSeq": 119, "breakReason": "prev_hash does not match the recomputed hash of seq 118" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/notarian.anchors.list": { "post": { "operationId": "notarian_anchors_list", "summary": "List the Notarian anchors (the published chain checkpoints).", "x-trustvice-description-key": "actions.notarian.anchors.list.description", "tags": [ "notarian" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "List anchors.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "List anchors.", "value": { "anchors": [ { "id": "eb7f9624-1f91-45d9-a9a4-4f6adf0478ce", "workspaceId": "ws_example", "ledgerSha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "snapshottedAt": "2026-02-01T00:00:00.000Z", "otsProofId": null, "btcBlockHeight": null, "status": "pending", "source": "manual", "label": "month-end", "recordCount": 412, "rangeStart": "2026-01-01T00:00:00.000Z", "rangeEnd": "2026-01-31T23:59:59.999Z", "jurisdiction": "ENAM", "bundleId": "eb7f9624-1f91-45d9-a9a4-4f6adf0478ce" } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/witness.frameworks.list": { "post": { "operationId": "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.", "x-trustvice-description-key": "actions.witness.frameworks.list.description", "tags": [ "witness" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "category": { "description": "Filter by framework category.", "type": "string", "minLength": 1 }, "status": { "description": "Filter by support status.", "type": "string", "enum": [ "stable", "beta", "coming-soon" ] }, "pattern": { "description": "Filter by integration pattern (sdk | webhook | otel | …).", "type": "string", "minLength": 1 } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "All stable frameworks.", "value": { "status": "stable" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "All stable frameworks.", "value": { "frameworks": [ { "id": "langchain", "name": "LangChain", "tagline": "The most widely deployed agent framework.", "category": "orchestration", "runtime": "python", "status": "stable", "integrationPattern": "sdk", "sdkPackage": "@trustvice/witness-langchain", "sdkVersion": "1.0.0", "integrationDocHref": "/docs/witness/langchain" } ], "counts": { "total": 175, "stable": 120, "beta": 40, "comingSoon": 15 } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/witness.frameworks.get": { "post": { "operationId": "witness_frameworks_get", "summary": "Get one agent framework's catalog entry (support status, integration pattern, SDK package, docs).", "x-trustvice-description-key": "actions.witness.frameworks.get.description", "tags": [ "witness" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "frameworkId": { "type": "string", "minLength": 1, "description": "Catalog id, e.g. langchain / crewai / openclaw." } }, "required": [ "frameworkId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "LangChain's catalog entry.", "value": { "frameworkId": "langchain" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "LangChain's catalog entry.", "value": { "framework": { "id": "langchain", "name": "LangChain", "tagline": "The most widely deployed agent framework.", "category": "orchestration", "runtime": "python", "status": "stable", "integrationPattern": "sdk", "sdkPackage": "@trustvice/witness-langchain", "sdkVersion": "1.0.0", "integrationDocHref": "/docs/witness/langchain" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/witness.patterns.list": { "post": { "operationId": "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).", "x-trustvice-description-key": "actions.witness.patterns.list.description", "tags": [ "witness" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "The pattern catalog.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "The pattern catalog.", "value": { "patterns": [ { "id": "sdk", "label": "SDK", "setup": "Install the framework SDK and set TRUSTVICE_API_KEY." }, { "id": "proxy", "label": "LLM proxy", "setup": "Point the framework's base URL at the Trustvice proxy." }, { "id": "webhook", "label": "Webhook", "setup": "Register a Trustvice endpoint as the framework's callback." } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/witness.subscriptions.get": { "post": { "operationId": "witness_subscriptions_get", "summary": "Get the Witness-Fabric subscription matrix — which products consume which record event classes from the neutral stream.", "x-trustvice-description-key": "actions.witness.subscriptions.get.description", "tags": [ "witness" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "The WITNESS_SUBSCRIPTIONS routing matrix.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "The WITNESS_SUBSCRIPTIONS routing matrix.", "value": { "subscriptions": [ { "subscriber": "driftvice", "events": [ "invocation", "tool_call" ], "binding": "FABRIC_SUBSCRIBER_DRIFTVICE" }, { "subscriber": "nexus", "events": [ "invocation" ], "binding": "FABRIC_SUBSCRIBER_NEXUS" } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/witness.interpose": { "post": { "operationId": "witness_interpose", "summary": "Witness one exchange with an agent you may not operate. Hashes only, unless retention is explicitly requested.", "x-trustvice-description-key": "actions.witness.interpose.description", "tags": [ "witness" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "exchange": { "type": "object", "properties": { "exchangeId": { "type": "string", "minLength": 1, "maxLength": 128 }, "targetRef": { "type": "string", "minLength": 1, "maxLength": 512 }, "requestBody": { "type": "string" }, "responseBody": { "type": "string" }, "requestAt": { "type": "string", "minLength": 1 }, "responseAt": { "type": "string", "minLength": 1 }, "outcome": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "exchangeId", "targetRef", "requestBody", "responseBody", "requestAt", "responseAt", "outcome" ], "additionalProperties": false }, "retention": { "type": "object", "properties": { "retainRequest": { "type": "boolean" }, "retainResponse": { "type": "boolean" }, "purpose": { "type": "string", "minLength": 1, "maxLength": 512 } }, "additionalProperties": false } }, "required": [ "exchange" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Hashes only. Nothing stored.", "value": { "exchange": { "exchangeId": "ex_1", "targetRef": "https://agent.example/v1", "requestBody": "{}", "responseBody": "{}", "requestAt": "2026-09-04T00:00:00.000Z", "responseAt": "2026-09-04T00:00:00.250Z", "outcome": "200" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "receipt": { "type": "object", "properties": { "exchangeId": { "type": "string" }, "targetRef": { "type": "string" }, "requestSha256": { "type": "string" }, "responseSha256": { "type": "string" }, "latencyMs": { "type": "number" }, "outcome": { "type": "string" }, "retained": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "attests": { "type": "array", "items": { "type": "string" } }, "observability": { "type": "object", "properties": { "vantage": { "type": "string", "const": "interposed" }, "cannotAttest": { "type": "array", "items": { "type": "string" } }, "note": { "type": "string" } }, "required": [ "vantage", "cannotAttest", "note" ], "additionalProperties": {} } }, "required": [ "exchangeId", "targetRef", "requestSha256", "responseSha256", "latencyMs", "outcome", "attests", "observability" ], "additionalProperties": {} }, "issue": { "type": "object", "properties": { "kind": { "type": "string", "const": "interpose-witness" }, "subject": {}, "claims": {} }, "required": [ "kind", "subject", "claims" ], "additionalProperties": {} }, "contentRetained": { "type": "boolean" }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "receipt", "issue", "contentRetained", "notes" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Hashes only. Nothing stored.", "value": { "receipt": { "exchangeId": "ex_1", "targetRef": "https://agent.example/v1", "requestSha256": "…", "responseSha256": "…", "latencyMs": 250, "outcome": "200", "attests": [ "request_bytes_as_received" ], "observability": { "vantage": "interposed", "cannotAttest": [], "note": "…" } }, "issue": { "kind": "interpose-witness", "subject": {}, "claims": {} }, "contentRetained": false, "notes": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/witness.interpose.verify": { "post": { "operationId": "witness_interpose_verify", "summary": "Check presented bytes against an interpose receipt's hashes.", "x-trustvice-description-key": "actions.witness.interpose.verify.description", "tags": [ "witness" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "receipt": { "type": "object", "properties": { "requestSha256": { "type": "string", "minLength": 1 }, "responseSha256": { "type": "string", "minLength": 1 } }, "required": [ "requestSha256", "responseSha256" ], "additionalProperties": {} }, "requestBody": { "type": "string" }, "responseBody": { "type": "string" } }, "required": [ "receipt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Null is not a mismatch.", "value": { "receipt": { "requestSha256": "aa", "responseSha256": "bb" }, "requestBody": "{}" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestMatches": { "type": [ "boolean", "null" ] }, "responseMatches": { "type": [ "boolean", "null" ] }, "fullyVerified": { "type": "boolean" }, "reason": { "type": "string" } }, "required": [ "requestMatches", "responseMatches", "fullyVerified", "reason" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Null is not a mismatch.", "value": { "requestMatches": false, "responseMatches": null, "fullyVerified": false, "reason": "A half-checked exchange is not a verified one." } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/witness.records.list": { "post": { "operationId": "witness_records_list", "summary": "List the workspace's adapter-captured agent records from the neutral Witness-Fabric store (chain-free read — product-independent; no TrustActor enrollment required).", "x-trustvice-description-key": "actions.witness.records.list.description", "tags": [ "witness" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "frameworkId": { "description": "Filter by source framework.", "type": "string", "minLength": 1 }, "pattern": { "description": "Filter by integration pattern.", "type": "string", "minLength": 1 }, "event": { "description": "Filter by record event class.", "type": "string", "enum": [ "invocation", "tool.call", "memory.write", "sub_agent.spawn", "channel.message" ] }, "agentId": { "description": "Filter by agent DID/id.", "type": "string", "minLength": 1 }, "before": { "description": "Cursor: rows stored strictly before this ISO timestamp (pass the previous page's nextCursor.before).", "type": "string", "minLength": 1 }, "beforeId": { "description": "Composite-cursor tiebreaker (the previous page's nextCursor.beforeId) — with `before`, guarantees same-millisecond rows are never skipped.", "type": "string", "minLength": 1 }, "limit": { "description": "Page size (default 50, max 200).", "type": "integer", "minimum": 1, "maximum": 200 } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Latest CrewAI records.", "value": { "frameworkId": "crewai", "limit": 20 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Latest CrewAI records.", "value": { "records": [ { "recordId": "0f5b0a1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a", "agentId": "did:web:example.com:agent:support", "event": "invocation", "occurredAt": "2026-07-19T12:00:00.000Z", "storedAt": "2026-07-19T12:00:01.480Z", "source": { "pattern": "sdk", "frameworkId": "crewai", "adapterVersion": "1.0.0", "ingestMode": "push" } } ], "count": 1, "nextCursor": { "before": "2026-07-19T12:00:01.480Z", "beforeId": "0f5b0a1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/witness.records.post": { "post": { "operationId": "witness_records_post", "summary": "Post an adapter record directly onto the neutral Witness-Fabric plane (stored chain-free + fanned out to subscribing products; NOT anchored in the TrustActor hash chain — use the ingest lane for evidentiary anchoring).", "x-trustvice-description-key": "actions.witness.records.post.description", "tags": [ "witness" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "record": { "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1, "description": "The agent DID/id the record observes." }, "event": { "type": "string", "enum": [ "invocation", "tool.call", "memory.write", "sub_agent.spawn", "channel.message" ] }, "occurredAt": { "type": "string", "minLength": 1, "description": "ISO timestamp of the agent event." }, "source": { "type": "object", "properties": { "pattern": { "type": "string", "minLength": 1 }, "frameworkId": { "type": "string", "minLength": 1 }, "adapterVersion": { "type": "string" }, "ingestMode": { "type": "string", "enum": [ "push", "pull" ] } }, "required": [ "pattern", "frameworkId", "adapterVersion", "ingestMode" ], "additionalProperties": {} } }, "required": [ "agentId", "event", "occurredAt", "source" ], "additionalProperties": {}, "description": "The AdapterRecord (workspaceId is gateway-resolved and overrides any body value)." } }, "required": [ "record" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Neutral-plane record post.", "value": { "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" } } } }, "example_1": { "summary": "The same record posted twice — a deduplication, not a new record.", "value": { "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" } } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Neutral-plane record post.", "value": { "recordId": "0f5b0a1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a", "deduplicated": false, "chainAnchored": false, "delivery": { "broadcast": [ "driftvice", "nexus" ], "failed": [] } } }, "example_1": { "summary": "The same record posted twice — a deduplication, not a new record.", "value": { "recordId": "0f5b0a1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a", "deduplicated": true, "chainAnchored": false, "delivery": { "broadcast": [], "failed": [] } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/witness.records.stats": { "post": { "operationId": "witness_records_stats", "summary": "Aggregate stats over the workspace's neutral witness stream (totals + per-framework / per-pattern / per-event counts).", "x-trustvice-description-key": "actions.witness.records.stats.description", "tags": [ "witness" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Stream aggregates for dashboards.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Stream aggregates for dashboards.", "value": { "stats": { "total": 18420, "byFramework": [ { "frameworkId": "langchain", "count": 11002 }, { "frameworkId": "crewai", "count": 4180 } ], "byPattern": [ { "pattern": "sdk", "count": 15200 }, { "pattern": "proxy", "count": 3220 } ], "byEvent": [ { "event": "invocation", "count": 12010 }, { "event": "tool_call", "count": 6410 } ] } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/witness.residency.prove": { "post": { "operationId": "witness_residency_prove", "summary": "Prove where a run's recorded hops stayed, with the ceiling the evidence actually supports.", "x-trustvice-description-key": "actions.witness.residency.prove.description", "tags": [ "witness" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "runId": { "type": "string", "minLength": 1 }, "declaredRegion": { "type": "string", "minLength": 1, "description": "The region the run is claimed to have stayed in. Required: the proof is that a run stayed in a NAMED region, and the worker will not assume its own." } }, "required": [ "runId", "declaredRegion" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "The ceiling is no_recorded_departure, never \"never left\".", "value": { "runId": "run_01J9", "declaredRegion": "weur-1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "proof": { "type": "object", "properties": { "runRef": { "type": "string" }, "declaredRegion": { "type": "string" }, "verdict": { "type": "string" }, "hopsRecorded": { "type": "number" }, "offRegionHops": { "type": "array", "items": { "type": "string" } }, "unknownRegionHops": { "type": "array", "items": { "type": "string" } }, "supportedClaim": { "type": "string", "description": "The exact sentence this proof supports. Never \"never left\" unless earned." }, "limits": { "type": "array", "items": { "type": "string" } } }, "required": [ "runRef", "declaredRegion", "verdict", "hopsRecorded", "offRegionHops", "unknownRegionHops", "supportedClaim", "limits" ], "additionalProperties": {} }, "hopsFromRecords": { "type": "number" }, "hopsWithNoRegion": { "type": "number" }, "egressInstrumented": { "type": "boolean", "description": "False: egress is not instrumented, and a residency proof must say so rather than imply completeness." }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "proof", "hopsFromRecords", "hopsWithNoRegion", "egressInstrumented", "notes" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "The ceiling is no_recorded_departure, never \"never left\".", "value": { "proof": { "runRef": "run_01J9", "declaredRegion": "weur-1", "verdict": "no_recorded_departure", "hopsRecorded": 4, "offRegionHops": [], "unknownRegionHops": [ "rec_2" ], "supportedClaim": "No recorded hop left weur-1. One hop's region is unknown, so this is not a proof that the run never left.", "limits": [ "Egress is not instrumented; an absent hop in this record is not evidence there was none." ] }, "hopsFromRecords": 4, "hopsWithNoRegion": 1, "egressInstrumented": false, "notes": [ "An unknown region is not an in-region hop." ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.overview": { "post": { "operationId": "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).", "x-trustvice-description-key": "actions.tranquility.overview.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "since": { "description": "ISO lower bound for the window.", "type": "string", "minLength": 1 } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Workspace observability at a glance.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Workspace observability at a glance.", "value": { "agentEvents": { "available": true, "total": 18420, "byEvent": [ { "event": "invocation", "count": 12010 } ] }, "spans": { "available": true, "series": [ { "bucket": "2026-09-01T00:00:00.000Z", "count": 4120 } ] }, "metrics": { "available": true, "distinctMetrics": 42, "top": [ "http.server.duration", "agent.tokens" ] }, "logs": { "available": true, "hasRecent": true }, "slos": { "count": 3, "items": [ { "sloId": "slo_api_latency", "name": "API p95 < 300ms", "objectivePct": 99.5, "window": "30d", "metric": "http.server.duration", "createdAt": "2026-07-01T00:00:00.000Z" } ] }, "generatedAt": "2026-09-01T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.slos.list": { "post": { "operationId": "tranquility_slos_list", "summary": "List the workspace's SLO definitions (latency, error-rate, cost-per-outcome, mandate-burn — one engine, any denomination).", "x-trustvice-description-key": "actions.tranquility.slos.list.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "All SLOs.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "All SLOs.", "value": { "slos": [ { "sloId": "slo_api_latency", "name": "API p95 < 300ms", "objectivePct": 99.5, "window": "30d", "metric": "http.server.duration", "createdAt": "2026-07-01T00:00:00.000Z" } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.slos.create": { "post": { "operationId": "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.", "x-trustvice-description-key": "actions.tranquility.slos.create.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "sliSeries": { "type": "string", "minLength": 1, "description": "The named series to measure (e.g. agent.tool.latency_ms, goal.cost_usd, mandate.burn_ratio)." }, "sliSelector": { "description": "Filters: framework/agent/endpoint/tool.", "type": "object", "properties": {}, "additionalProperties": {} }, "denomination": { "type": "string", "enum": [ "ratio", "ms", "usd", "count", "burn" ] }, "comparator": { "type": "string", "enum": [ "lte", "gte" ] }, "threshold": { "type": "number" }, "targetPct": { "type": "number", "minimum": 0, "maximum": 100 }, "windowSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "burnWindows": { "type": "array", "items": { "type": "object", "properties": { "long": { "type": "number" }, "short": { "type": "number" }, "factor": { "type": "number" } }, "required": [ "long", "short", "factor" ] } }, "enabled": { "type": "boolean" } }, "required": [ "name", "sliSeries", "threshold" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "A dollar-denominated SLO.", "value": { "name": "resolution cost", "sliSeries": "goal.cost_usd", "denomination": "usd", "comparator": "lte", "threshold": 0.85, "targetPct": 95 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "A dollar-denominated SLO.", "value": { "slo": { "sloId": "slo_api_latency", "name": "API p95 < 300ms", "objectivePct": 99.5, "window": "30d", "metric": "http.server.duration", "createdAt": "2026-07-01T00:00:00.000Z" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.slos.get": { "post": { "operationId": "tranquility_slos_get", "summary": "Get one SLO definition + its recent evaluations (attainment, error budget, burn rate, status, coverage).", "x-trustvice-description-key": "actions.tranquility.slos.get.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sloId": { "type": "string", "minLength": 1 } }, "required": [ "sloId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "SLO detail.", "value": { "sloId": "tyslo_x" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "SLO detail.", "value": { "slo": { "sloId": "slo_api_latency", "name": "API p95 < 300ms", "objectivePct": 99.5, "window": "30d", "metric": "http.server.duration", "createdAt": "2026-07-01T00:00:00.000Z" }, "evaluations": [ { "evaluatedAt": "2026-09-01T00:00:00.000Z", "achievedPct": 99.71, "met": true } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.slos.evaluate": { "post": { "operationId": "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).", "x-trustvice-description-key": "actions.tranquility.slos.evaluate.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sloId": { "type": "string", "minLength": 1 }, "points": { "type": "array", "items": { "type": "object", "properties": { "ts": { "type": "string" }, "value": { "type": "number" }, "weight": { "type": "number" } }, "required": [ "ts", "value" ] }, "description": "The SLI measurements to evaluate." }, "coverage": { "description": "How complete the pushed series is — honest, embedded in any sealed attestation.", "type": "object", "properties": { "samplingPct": { "type": "number" }, "dropWindows": { "type": "number" }, "complete": { "type": "boolean" }, "detailLevel": { "type": "string", "enum": [ "safe", "extended", "forensic" ] } } }, "seal": { "description": "Mint the evaluation as a signed VerifiableArtifact.", "type": "boolean" } }, "required": [ "sloId", "points" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Evaluate + attest.", "value": { "sloId": "tyslo_x", "points": [ { "ts": "2026-07-21T00:00:00Z", "value": 340 } ], "seal": true } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Evaluate + attest.", "value": { "evaluation": { "evaluatedAt": "2026-09-01T00:00:00.000Z", "achievedPct": 99.71, "met": true }, "result": { "objectivePct": 99.5, "achievedPct": 99.71, "errorBudgetRemainingPct": 42 }, "artifactId": "art_01M1F0000000000000000009" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.goals.list": { "post": { "operationId": "tranquility_goals_list", "summary": "List goals (business outcomes) with their rolled cost decomposition + outcome stamp.", "x-trustvice-description-key": "actions.tranquility.goals.list.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "open", "resolved", "abandoned", "escalated", "failed" ] }, "costCenter": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Resolved goals + their cost.", "value": { "outcome": "resolved" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Resolved goals + their cost.", "value": { "goals": [ { "goalId": "goal_01M1F0000000000000000001", "label": "Resolve ticket #4417", "outcome": "resolved", "costTotalUm": 18400, "openedAt": "2026-08-01T09:00:00.000Z", "closedAt": "2026-08-01T09:12:00.000Z" } ], "count": 1 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.goals.create": { "post": { "operationId": "tranquility_goals_create", "summary": "Open a goal — a business outcome (ticket / booking / refund / conversation) whose full pursuit cost the Goal Ledger will stitch.", "x-trustvice-description-key": "actions.tranquility.goals.create.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "goalId": { "type": "string" }, "externalRef": { "type": "string" }, "kind": { "type": "string" }, "agentId": { "type": "string" }, "costCenter": { "type": "string" }, "feature": { "type": "string" }, "customerRef": { "type": "string" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Open a support-ticket goal.", "value": { "externalRef": "ticket-42", "kind": "ticket", "costCenter": "cc-support" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Open a support-ticket goal.", "value": { "goalId": "goal_01M1F0000000000000000001" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.goals.events.append": { "post": { "operationId": "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.", "x-trustvice-description-key": "actions.tranquility.goals.events.append.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "goalId": { "type": "string", "minLength": 1 }, "events": { "type": "array", "items": { "type": "object", "properties": { "eventType": { "type": "string", "enum": [ "turn", "tool.call", "retry", "blocked", "human", "delivery", "outcome" ] }, "costUm": { "description": "Cost in micro-dollars (USD*1e6).", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sourceRef": { "type": "string" }, "occurredAt": { "type": "string" }, "isRetry": { "type": "boolean" }, "isLoopRepeat": { "type": "boolean" }, "blocked": { "type": "boolean" }, "eventId": { "type": "string" } }, "required": [ "eventType" ] }, "description": "One or more cost events." } }, "required": [ "goalId", "events" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Log a tool call's cost.", "value": { "goalId": "tygoal_x", "events": [ { "eventType": "tool.call", "costUm": 1200 } ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Log a tool call's cost.", "value": { "inserted": true, "goal": { "goalId": "goal_01M1F0000000000000000001", "label": "Resolve ticket #4417", "outcome": "resolved", "costTotalUm": 18400, "openedAt": "2026-08-01T09:00:00.000Z", "closedAt": "2026-08-01T09:12:00.000Z" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.goals.close": { "post": { "operationId": "tranquility_goals_close", "summary": "Stamp a goal's terminal outcome (resolved / abandoned / escalated / failed) — the attribution the Goal Ledger exists for.", "x-trustvice-description-key": "actions.tranquility.goals.close.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "goalId": { "type": "string", "minLength": 1 }, "outcome": { "type": "string", "enum": [ "resolved", "abandoned", "escalated", "failed" ] } }, "required": [ "goalId", "outcome" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Resolve a goal.", "value": { "goalId": "tygoal_x", "outcome": "resolved" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Resolve a goal.", "value": { "goal": { "goalId": "goal_01M1F0000000000000000001", "label": "Resolve ticket #4417", "outcome": "resolved", "costTotalUm": 18400, "openedAt": "2026-08-01T09:00:00.000Z", "closedAt": "2026-08-01T09:12:00.000Z" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.goals.summary": { "post": { "operationId": "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.", "x-trustvice-description-key": "actions.tranquility.goals.summary.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "costCenter": { "type": "string" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Unit economics summary.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Unit economics summary.", "value": { "byOutcome": [ { "outcome": "resolved", "count": 412, "totalCostUm": 7580000, "avgCostUm": 18398 }, { "outcome": "abandoned", "count": 18, "totalCostUm": 410000, "avgCostUm": 22778 } ], "costPerResolvedUm": 18398, "waste": { "productiveUm": 5100000, "retryUm": 1200000, "loopUm": 380000, "blockedUm": 240000, "humanUm": 610000, "deliveryUm": 460000 }, "totalGoals": 430, "productiveEfficiencyPct": 73.2 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.agent.records": { "post": { "operationId": "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.", "x-trustvice-description-key": "actions.tranquility.agent.records.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "frameworkId": { "type": "string" }, "pattern": { "type": "string" }, "event": { "type": "string" }, "agentId": { "type": "string" }, "before": { "type": "string" }, "beforeId": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Recent LangChain tool calls.", "value": { "frameworkId": "langchain", "event": "tool.call" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Recent LangChain tool calls.", "value": { "records": [ { "recordId": "0f5b0a1c…", "agentId": "did:web:example.com:agent:support", "event": "invocation", "occurredAt": "2026-09-01T11:59:00.000Z" } ], "count": 1 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.agent.frameworks": { "post": { "operationId": "tranquility_agent_frameworks", "summary": "The supported agent-framework catalog this workspace can observe (the 180-framework matrix, live from the witness catalog).", "x-trustvice-description-key": "actions.tranquility.agent.frameworks.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Framework coverage.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Framework coverage.", "value": { "frameworks": [ { "frameworkId": "langchain", "count": 11002 } ], "sampledRecords": 18420 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.metrics.query": { "post": { "operationId": "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.", "x-trustvice-description-key": "actions.tranquility.metrics.query.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "A single metric name to filter to.", "type": "string" }, "since": { "type": "string" }, "until": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 500 }, "cursor": { "type": "string" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Recent points for one metric.", "value": { "name": "http.server.duration" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Recent points for one metric.", "value": { "series": [ { "metric": "http.server.duration", "points": [ { "t": "2026-09-01T11:00:00.000Z", "v": 214.5 } ] } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.metrics.names": { "post": { "operationId": "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.", "x-trustvice-description-key": "actions.tranquility.metrics.names.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "since": { "type": "string" }, "until": { "type": "string" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Which metrics exist.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Which metrics exist.", "value": { "names": [ "http.server.duration", "agent.tokens" ], "metricCount": 42 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.logs.search": { "post": { "operationId": "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.", "x-trustvice-description-key": "actions.tranquility.logs.search.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "minSeverity": { "description": "OTLP SeverityNumber floor (13 = WARN, 17 = ERROR).", "type": "integer", "minimum": 1, "maximum": 24 }, "traceId": { "description": "32-hex trace id to correlate logs to a trace.", "type": "string" }, "since": { "type": "string" }, "until": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 500 }, "cursor": { "type": "string" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Errors and worse.", "value": { "minSeverity": 17 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Errors and worse.", "value": { "logs": [ { "t": "2026-09-01T11:59:12.000Z", "level": "error", "body": "upstream timeout", "attributes": { "service": "api-gateway" } } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.agent.tools": { "post": { "operationId": "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.", "x-trustvice-description-key": "actions.tranquility.agent.tools.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "frameworkId": { "type": "string" }, "agentId": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Tool reliability + latency, honestly scoped.", "value": { "frameworkId": "langchain" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Tool reliability + latency, honestly scoped.", "value": { "tools": [ { "tool": "search_docs", "calls": 3120, "failures": 41, "p95Ms": 180 } ], "sampledRecords": 18420 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.agent.fleet": { "post": { "operationId": "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.", "x-trustvice-description-key": "actions.tranquility.agent.fleet.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Which agents are healthy, degraded, or quiet.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Which agents are healthy, degraded, or quiet.", "value": { "fleet": { "agents": 12, "active24h": 9, "failing": 1 }, "sampledRecords": 18420 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.agent.failures": { "post": { "operationId": "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.", "x-trustvice-description-key": "actions.tranquility.agent.failures.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Top failure clusters across the fleet.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Top failure clusters across the fleet.", "value": { "clusters": [ { "signature": "upstream timeout", "count": 41, "firstSeen": "2026-08-30T02:10:00.000Z", "lastSeen": "2026-09-01T11:59:12.000Z" } ], "sampledRecords": 18420 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.agent.runTree": { "post": { "operationId": "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.", "x-trustvice-description-key": "actions.tranquility.agent.runTree.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "runId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "required": [ "runId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "A single agent run as a DAG.", "value": { "runId": "R1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "A single agent run as a DAG.", "value": { "tree": { "id": "run:abc", "children": [ { "id": "span:1", "name": "search_docs", "durationMs": 180, "children": [] } ] }, "sampledRecords": 18420 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.cognition.guardrailPressure": { "post": { "operationId": "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.", "x-trustvice-description-key": "actions.tranquility.cognition.guardrailPressure.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "evaluations": { "type": "array", "items": { "type": "object", "properties": { "clause": { "type": "string" }, "outcome": { "type": "string", "enum": [ "allow", "deny" ] }, "margin": { "type": "number" }, "agentId": { "type": "string" }, "at": { "type": "string" } }, "required": [ "clause", "outcome", "at" ] }, "description": "Per-step outcomes from the governed action chain." }, "nearMissThreshold": { "description": "Margin strictly below which an ALLOW is a near-miss; without it near-miss is unposeable, never guessed.", "type": "number" }, "knownClauses": { "description": "The full declared clause catalogue, so clauses that never fired surface as dead.", "type": "array", "items": { "type": "string" } } }, "required": [ "evaluations" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Hot-clause vs dead-policy map.", "value": { "evaluations": [ { "clause": "pii.redact", "outcome": "deny", "at": "2026-07-21T00:00:00Z" } ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Hot-clause vs dead-policy map.", "value": { "pressure": { "evaluated": 240, "blocked": 3, "nearMisses": 18, "byClause": [ { "clause": "no_pii_egress", "nearMisses": 12 } ] } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.cognition.blastRadius": { "post": { "operationId": "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.", "x-trustvice-description-key": "actions.tranquility.cognition.blastRadius.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "actionIds": { "type": "array", "items": { "type": "string" }, "description": "The plan's ordered action ids." }, "actionMeta": { "description": "Per-action safety metadata.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "safetyLevel": { "type": "string", "enum": [ "read", "mutation", "destructive" ] }, "idempotent": { "type": "boolean" }, "confirmationRequired": { "type": "boolean" } }, "required": [ "safetyLevel", "idempotent", "confirmationRequired" ] } } }, "required": [ "actionIds" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Score a plan before it runs.", "value": { "actionIds": [ "files.delete", "email.send" ], "actionMeta": { "files.delete": { "safetyLevel": "destructive", "idempotent": false, "confirmationRequired": true }, "email.send": { "safetyLevel": "mutation", "idempotent": false, "confirmationRequired": false } } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Score a plan before it runs.", "value": { "blastRadius": { "actions": 4, "reversible": 3, "irreversible": 1, "maxScope": "workspace" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.cognition.charterConformance": { "post": { "operationId": "tranquility_cognition_charterConformance", "summary": "Diff an agent's observed behavior against its declared charter (allowed tools / autonomy ceiling / allowed tones) — charter-as-SLO. A pure diff with a COVERAGE statement: an undeclared dimension is unposeable, and a no-charter case returns undefined, never a fabricated 100%.", "x-trustvice-description-key": "actions.tranquility.cognition.charterConformance.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "observed": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "string" } }, "maxAutonomyObserved": { "type": "number" }, "tones": { "type": "array", "items": { "type": "string" } } }, "required": [ "tools" ] }, "declared": { "type": "object", "properties": { "allowedTools": { "type": "array", "items": { "type": "string" } }, "autonomyCeiling": { "type": "number" }, "allowedTones": { "type": "array", "items": { "type": "string" } } } } }, "required": [ "observed", "declared" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Detect off-charter tool use.", "value": { "observed": { "tools": [ "search", "email.send" ] }, "declared": { "allowedTools": [ "search" ] } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Detect off-charter tool use.", "value": { "conformance": { "declared": 12, "observed": 11, "conforming": 10, "deviations": [ { "clause": "escalate_on_refund", "observed": "auto_approved" } ] } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.cognition.vocabularyDrift": { "post": { "operationId": "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.", "x-trustvice-description-key": "actions.tranquility.cognition.vocabularyDrift.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "topN": { "description": "Max candidate terms to resolve against canon (ranked by frequency). Default 50.", "type": "integer", "minimum": 1, "maximum": 200 }, "limit": { "description": "Records to sample from the agent stream. Default 500.", "type": "integer", "minimum": 1, "maximum": 1000 } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Which named concepts the fleet uses are drifting or ungoverned.", "value": { "topN": 25 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Which named concepts the fleet uses are drifting or ungoverned.", "value": { "vocabulary": { "terms": [ { "normalized": "active user", "occurrences": 42 } ] }, "driftFindings": [ { "term": "active user", "status": "governed-drifting" } ], "summary": { "candidates": 1, "governedDrifting": 1, "ungoverned": 0, "unresolved": 0 }, "canonSource": { "available": true }, "sampledRecords": 18420 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.evidence.usage.seal": { "post": { "operationId": "tranquility_evidence_usage_seal", "summary": "Seal the cost-per-outcome summary as a signed, offline-verifiable usage/chargeback ledger (ty-usage-ledger).", "x-trustvice-description-key": "actions.tranquility.evidence.usage.seal.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "costCenter": { "type": "string" }, "period": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "start", "end" ] } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Signed chargeback statement.", "value": { "costCenter": "cc-support" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Signed chargeback statement.", "value": { "artifactId": "art_01M1F0000000000000000010", "summary": { "byOutcome": [ { "outcome": "resolved", "count": 412, "totalCostUm": 7580000, "avgCostUm": 18398 }, { "outcome": "abandoned", "count": 18, "totalCostUm": 410000, "avgCostUm": 22778 } ], "costPerResolvedUm": 18398, "waste": { "productiveUm": 5100000, "retryUm": 1200000, "loopUm": 380000, "blockedUm": 240000, "humanUm": 610000, "deliveryUm": 460000 }, "totalGoals": 430, "productiveEfficiencyPct": 73.2 } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.evidence.coverage.seal": { "post": { "operationId": "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).", "x-trustvice-description-key": "actions.tranquility.evidence.coverage.seal.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "metric": { "type": "string", "minLength": 1 }, "value": { "type": "number" }, "unit": { "type": "string" }, "window": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "start", "end" ] }, "coverage": { "type": "object", "properties": { "samplingPct": { "type": "number" }, "dropWindows": { "type": "number" }, "complete": { "type": "boolean" }, "detailLevel": { "type": "string", "enum": [ "safe", "extended", "forensic" ] } } } }, "required": [ "metric", "value" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Signed coverage-stated figure.", "value": { "metric": "p95", "value": 340, "unit": "ms" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Signed coverage-stated figure.", "value": { "artifactId": "art_01M1F0000000000000000011", "sealed": { "metric": "p95", "value": 340, "coverage": { "samplingPct": 100, "complete": true } } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.artifacts.list": { "post": { "operationId": "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.", "x-trustvice-description-key": "actions.tranquility.artifacts.list.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subjectKind": { "description": "slo | usage | coverage | alert | incident", "type": "string" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Signed SLO attestations.", "value": { "subjectKind": "slo" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Signed SLO attestations.", "value": { "artifacts": [ { "artifact_id": "art_01M1F0000000000000000010", "kind": "usage_ledger", "subject_kind": "usage", "subject_id": "all", "leaf_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tops_ref": null, "minted_at": "2026-09-01T12:00:00.000Z" } ], "count": 1 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.views.list": { "post": { "operationId": "tranquility_views_list", "summary": "List saved views / custom monitors for a surface.", "x-trustvice-description-key": "actions.tranquility.views.list.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "surface": { "type": "string" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Agent-surface views.", "value": { "surface": "agent" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Agent-surface views.", "value": { "views": [ { "viewId": "view_1", "name": "Agent errors", "surface": "agent", "spec": {} } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/tranquility.views.create": { "post": { "operationId": "tranquility_views_create", "summary": "Save a view / custom monitor (a signal + selector + panel spec) for reuse on a dashboard surface.", "x-trustvice-description-key": "actions.tranquility.views.create.description", "tags": [ "tranquility" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "surface": { "type": "string" }, "spec": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "name" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Save a monitor.", "value": { "name": "tool heatmap", "surface": "agent", "spec": { "panel": "heatmap" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} }, "examples": { "example_0": { "summary": "Save a monitor.", "value": { "viewId": "view_1" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/placard.compose": { "post": { "operationId": "placard_compose", "summary": "Compose a content-addressed AI disclosure notice and register it. The returned id IS the sha256 of the canonical bytes, so what was shown stays checkable. Refuses a notice missing its statutory core, and refuses to compose unsigned.", "x-trustvice-description-key": "actions.placard.compose.description", "tags": [ "placard" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "subject": { "type": "string", "minLength": 1 }, "channels": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "web", "chat", "email", "voice", "messaging", "video", "document", "api", "agentic", "machine" ] } }, "texts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "minLength": 2 }, "elements": { "type": "object", "propertyNames": { "type": "string", "enum": [ "artificialNature", "onWhoseBehalf", "capabilitiesAndLimits", "humanFallback", "whereToLearnMore" ] }, "additionalProperties": { "type": "string", "minLength": 1 } } }, "required": [ "locale", "elements" ] } } }, "required": [ "workspaceId", "subject", "channels", "texts" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Compose a one-locale chat notice.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "subject": "support-assistant", "channels": [ "chat" ], "texts": [ { "locale": "en", "elements": { "artificialNature": "You are speaking with an AI assistant, not a person." } } ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "placardId": { "type": "string", "pattern": "^plc_[A-Za-z0-9_-]{43}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "subject": { "type": "string" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "web", "chat", "email", "voice", "messaging", "video", "document", "api", "agentic", "machine" ] } }, "texts": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "minLength": 2 }, "elements": { "type": "object", "propertyNames": { "type": "string", "enum": [ "artificialNature", "onWhoseBehalf", "capabilitiesAndLimits", "humanFallback", "whereToLearnMore" ] }, "additionalProperties": { "type": "string", "minLength": 1 } } }, "required": [ "locale", "elements" ], "additionalProperties": false } }, "composedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "signature": { "type": "string" }, "signatureKeyId": { "type": "string" }, "canonical": { "type": "string" } }, "required": [ "placardId", "workspaceId", "subject", "version", "channels", "texts", "composedAt", "signature", "signatureKeyId", "canonical" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Compose a one-locale chat notice.", "value": { "placardId": "plc_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "workspaceId": "ws_DEMODEFAULT0000000000", "subject": "support-assistant", "version": 1, "channels": [ "chat" ], "texts": [ { "locale": "en", "elements": { "artificialNature": "You are speaking with an AI assistant, not a person." } } ], "composedAt": "2026-07-29T10:00:00.000Z", "signature": "…", "signatureKeyId": "…", "canonical": "{}" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "placard.compose" ] }, { "OAuth2": [ "placard.compose" ] }, { "WorkspaceApiKey": [ "placard.compose" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/placard.list": { "post": { "operationId": "placard_list", "summary": "List this workspace's composed placards, newest first.", "x-trustvice-description-key": "actions.placard.list.description", "tags": [ "placard" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List placards.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "placards": { "type": "array", "items": { "type": "object", "properties": { "placardId": { "type": "string", "pattern": "^plc_[A-Za-z0-9_-]{43}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "subject": { "type": "string" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "web", "chat", "email", "voice", "messaging", "video", "document", "api", "agentic", "machine" ] } }, "texts": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "minLength": 2 }, "elements": { "type": "object", "propertyNames": { "type": "string", "enum": [ "artificialNature", "onWhoseBehalf", "capabilitiesAndLimits", "humanFallback", "whereToLearnMore" ] }, "additionalProperties": { "type": "string", "minLength": 1 } } }, "required": [ "locale", "elements" ], "additionalProperties": false } }, "composedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "signature": { "type": "string" }, "signatureKeyId": { "type": "string" } }, "required": [ "placardId", "workspaceId", "subject", "version", "channels", "texts", "composedAt", "signature", "signatureKeyId" ], "additionalProperties": {} } } }, "required": [ "placards" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List placards.", "value": { "placards": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "placard.view" ] }, { "OAuth2": [ "placard.view" ] }, { "WorkspaceApiKey": [ "placard.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/placard.coverage.get": { "post": { "operationId": "placard_coverage_get", "summary": "Is a subject covered on a channel? Answers `covered`, `not-covered`, or `unknown` — and `unknown` never collapses to covered, because an unreadable answer is not a satisfied duty.", "x-trustvice-description-key": "actions.placard.coverage.get.description", "tags": [ "placard" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "subject": { "type": "string", "minLength": 1 }, "channel": { "type": "string", "enum": [ "web", "chat", "email", "voice", "messaging", "video", "document", "api", "agentic", "machine" ] } }, "required": [ "workspaceId", "subject", "channel" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Check coverage before an interaction.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "subject": "support-assistant", "channel": "chat" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "state": { "type": "string", "const": "covered" }, "placardId": { "type": "string", "pattern": "^plc_[A-Za-z0-9_-]{43}$" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "state", "placardId", "version" ], "additionalProperties": false }, { "type": "object", "properties": { "state": { "type": "string", "const": "not-covered" }, "reason": { "type": "string" } }, "required": [ "state", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "state": { "type": "string", "const": "unknown" }, "reason": { "type": "string" } }, "required": [ "state", "reason" ], "additionalProperties": false } ] }, "examples": { "example_0": { "summary": "Check coverage before an interaction.", "value": { "state": "not-covered", "reason": "No placard registered for this subject on this channel." } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "placard.coverage.view" ] }, { "OAuth2": [ "placard.coverage.view" ] }, { "WorkspaceApiKey": [ "placard.coverage.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/placard.delivery.record": { "post": { "operationId": "placard_delivery_record", "summary": "Record that a placard was delivered. `priorTurns` is REQUIRED, not defaulted — zero means the notice preceded the first interaction, and defaulting it would silently mark every delivery on time.", "x-trustvice-description-key": "actions.placard.delivery.record.description", "tags": [ "placard" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "placardId": { "type": "string", "pattern": "^plc_[A-Za-z0-9_-]{43}$" }, "channel": { "type": "string", "enum": [ "web", "chat", "email", "voice", "messaging", "video", "document", "api", "agentic", "machine" ] }, "subjectRef": { "type": "string", "minLength": 1 }, "priorTurns": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "locale": { "type": "string", "minLength": 2 } }, "required": [ "workspaceId", "placardId", "channel", "subjectRef", "priorTurns" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Record an on-time delivery.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "placardId": "plc_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "channel": "chat", "subjectRef": "sess_abc", "priorTurns": 0 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deliveryId": { "type": "string" }, "placardId": { "type": "string", "pattern": "^plc_[A-Za-z0-9_-]{43}$" }, "channel": { "type": "string", "enum": [ "web", "chat", "email", "voice", "messaging", "video", "document", "api", "agentic", "machine" ] }, "subjectRef": { "type": "string" }, "priorTurns": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "localeServed": { "type": [ "string", "null" ] }, "localeFallback": { "type": "boolean" } }, "required": [ "deliveryId", "placardId", "channel", "subjectRef", "priorTurns", "localeServed", "localeFallback" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Record an on-time delivery.", "value": { "deliveryId": "plcd_abc", "placardId": "plc_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "channel": "chat", "subjectRef": "sess_abc", "priorTurns": 0, "localeServed": null, "localeFallback": false } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "placard.delivery.record" ] }, { "OAuth2": [ "placard.delivery.record" ] }, { "WorkspaceApiKey": [ "placard.delivery.record" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/placard.delivery.acknowledge": { "post": { "operationId": "placard_delivery_acknowledge", "summary": "Record that the person acknowledged a delivered notice. Only meaningful on surfaces that can carry an acknowledgement.", "x-trustvice-description-key": "actions.placard.delivery.acknowledge.description", "tags": [ "placard" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "deliveryId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId", "deliveryId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Record an acknowledgement.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "deliveryId": "plcd_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deliveryId": { "type": "string" }, "acknowledged": { "type": "boolean", "const": true } }, "required": [ "deliveryId", "acknowledged" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Record an acknowledgement.", "value": { "deliveryId": "plcd_abc", "acknowledged": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "placard.delivery.record" ] }, { "OAuth2": [ "placard.delivery.record" ] }, { "WorkspaceApiKey": [ "placard.delivery.record" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/placard.deliveries.get": { "post": { "operationId": "placard_deliveries_get", "summary": "The delivery and acknowledgement state for one interaction. A late delivery reports as `delivered-late` and is never rounded up to `delivered`.", "x-trustvice-description-key": "actions.placard.deliveries.get.description", "tags": [ "placard" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "subjectRef": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId", "subjectRef" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read one interaction's disclosure state.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "subjectRef": "sess_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "delivery": { "type": "string" }, "acknowledgement": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "placardId": { "type": "string", "pattern": "^plc_[A-Za-z0-9_-]{43}$" }, "channel": { "type": "string", "enum": [ "web", "chat", "email", "voice", "messaging", "video", "document", "api", "agentic", "machine" ] }, "subjectRef": { "type": "string" }, "deliveredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "acknowledgedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "priorTurns": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "placardId", "channel", "subjectRef", "deliveredAt", "priorTurns" ], "additionalProperties": false } } }, "required": [ "delivery", "acknowledgement", "rows" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read one interaction's disclosure state.", "value": { "delivery": "unknown", "acknowledgement": "unknown", "rows": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "placard.delivery.view" ] }, { "OAuth2": [ "placard.delivery.view" ] }, { "WorkspaceApiKey": [ "placard.delivery.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/placard.resolve": { "post": { "operationId": "placard_resolve", "summary": "PUBLIC. Fetch a placard by id. No account needed — anyone holding the id can read exactly what notice was composed.", "x-trustvice-description-key": "actions.placard.resolve.description", "tags": [ "placard" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "placardId": { "type": "string", "pattern": "^plc_[A-Za-z0-9_-]{43}$" } }, "required": [ "placardId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Resolve a placard with no account.", "value": { "placardId": "plc_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "placardId": { "type": "string", "pattern": "^plc_[A-Za-z0-9_-]{43}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "subject": { "type": "string" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "web", "chat", "email", "voice", "messaging", "video", "document", "api", "agentic", "machine" ] } }, "texts": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "minLength": 2 }, "elements": { "type": "object", "propertyNames": { "type": "string", "enum": [ "artificialNature", "onWhoseBehalf", "capabilitiesAndLimits", "humanFallback", "whereToLearnMore" ] }, "additionalProperties": { "type": "string", "minLength": 1 } } }, "required": [ "locale", "elements" ], "additionalProperties": false } }, "composedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "signature": { "type": "string" }, "signatureKeyId": { "type": "string" }, "canonical": { "type": "string" } }, "required": [ "placardId", "workspaceId", "subject", "version", "channels", "texts", "composedAt", "signature", "signatureKeyId", "canonical" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Resolve a placard with no account.", "value": { "placardId": "plc_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "workspaceId": "ws_DEMODEFAULT0000000000", "subject": "support-assistant", "version": 1, "channels": [ "chat" ], "texts": [], "composedAt": "2026-07-29T10:00:00.000Z", "signature": "…", "signatureKeyId": "…", "canonical": "{}" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/placard.verify": { "post": { "operationId": "placard_verify", "summary": "PUBLIC. Check a placard's bytes against its id and its signature against the published keys. A genuinely invalid placard is a VERDICT, not an error — the call succeeds and reports `ok: false`.", "x-trustvice-description-key": "actions.placard.verify.description", "tags": [ "placard" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "placardId": { "type": "string", "pattern": "^plc_[A-Za-z0-9_-]{43}$" }, "canonical": { "type": "string", "minLength": 1 }, "signature": { "type": "string" } }, "required": [ "placardId", "canonical" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify bytes against the content address.", "value": { "placardId": "plc_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "canonical": "{}" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "placardId": { "type": "string", "pattern": "^plc_[A-Za-z0-9_-]{43}$" }, "signatureVerified": { "type": "boolean" }, "signatureKeyId": { "type": "string" }, "note": { "type": "string" } }, "required": [ "ok", "placardId", "signatureVerified" ], "additionalProperties": false }, { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "reason": { "type": "string", "enum": [ "content-address-mismatch", "bad-signature", "unknown-key", "malformed" ] }, "expected": { "type": "string" }, "actual": { "type": "string" } }, "required": [ "ok", "reason" ], "additionalProperties": false } ] }, "examples": { "example_0": { "summary": "Verify bytes against the content address.", "value": { "ok": false, "reason": "content-address-mismatch" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/placard.keys.get": { "post": { "operationId": "placard_keys_get", "summary": "PUBLIC. The JWK Set placards are signed with, for offline verification.", "x-trustvice-description-key": "actions.placard.keys.get.description", "tags": [ "placard" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read the signing keys.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "kty": { "type": "string" }, "crv": { "type": "string" }, "x": { "type": "string" }, "kid": { "type": "string", "pattern": "^[a-z0-9-]{4,64}$" }, "alg": { "type": "string" }, "use": { "type": "string" } }, "required": [ "kty", "crv", "x", "kid", "alg", "use" ], "additionalProperties": false } } }, "required": [ "keys" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read the signing keys.", "value": { "keys": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/cachet.declare": { "post": { "operationId": "cachet_declare", "summary": "Declare what an agent may do and the hard limits it asserts. Versioned and superseded, never edited — an operator cannot widen a declaration to erase yesterday's finding.", "x-trustvice-description-key": "actions.cachet.declare.description", "tags": [ "cachet" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "agentId": { "type": "string", "minLength": 1 }, "capabilities": { "type": "array", "items": { "type": "string" } }, "limits": { "type": "array", "items": { "type": "string" } } }, "required": [ "workspaceId", "agentId", "capabilities" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Declare an agent's capabilities and limits.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "agentId": "ag_support", "capabilities": [ "read.tickets", "send.reply" ], "limits": [ "never.refunds" ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "declarationId": { "type": "string" }, "agentId": { "type": "string" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "capabilities": { "type": "array", "items": { "type": "string" } }, "limits": { "type": "array", "items": { "type": "string" } }, "declaredAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "declarationId", "agentId", "version", "capabilities", "limits", "declaredAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Declare an agent's capabilities and limits.", "value": { "declarationId": "cdec_abc", "agentId": "ag_support", "version": 1, "capabilities": [ "read.tickets", "send.reply" ], "limits": [ "never.refunds" ], "declaredAt": "2026-07-29T10:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "cachet.declare" ] }, { "OAuth2": [ "cachet.declare" ] }, { "WorkspaceApiKey": [ "cachet.declare" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/cachet.observe": { "post": { "operationId": "cachet_observe", "summary": "Record a capability an agent was actually seen exercising. Bound to the declaration in force AT THE TIME, so dropping a limit later cannot clear the history.", "x-trustvice-description-key": "actions.cachet.observe.description", "tags": [ "cachet" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "agentId": { "type": "string", "minLength": 1 }, "capability": { "type": "string", "minLength": 1 }, "breachedLimit": { "type": "string" }, "runRef": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId", "agentId", "capability", "runRef" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Record one observed run.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "agentId": "ag_support", "capability": "send.reply", "runRef": "run_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "observationId": { "type": "string" }, "agentId": { "type": "string" }, "capability": { "type": "string" }, "breachedLimit": { "type": [ "string", "null" ] }, "observedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "observationId", "agentId", "capability", "breachedLimit", "observedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Record one observed run.", "value": { "observationId": "cobs_abc", "agentId": "ag_support", "capability": "send.reply", "breachedLimit": null, "observedAt": "2026-07-29T10:05:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "cachet.observe" ] }, { "OAuth2": [ "cachet.observe" ] }, { "WorkspaceApiKey": [ "cachet.observe" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/cachet.evidence.submit": { "post": { "operationId": "cachet_evidence_submit", "summary": "Present identity evidence for an agent. `verified` is REQUIRED — defaulting true would promote every presented credential, defaulting false would bury working ones. Failed evidence is retained, not dropped.", "x-trustvice-description-key": "actions.cachet.evidence.submit.description", "tags": [ "cachet" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "agentId": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "verified": { "type": "boolean" }, "failureReason": { "type": "string" } }, "required": [ "workspaceId", "agentId", "source", "verified" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Present a verified did:web credential.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "agentId": "ag_support", "source": "did-web", "verified": true } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "evidenceId": { "type": "string" }, "agentId": { "type": "string" }, "source": { "type": "string" }, "verified": { "type": "boolean" }, "presentedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "evidenceId", "agentId", "source", "verified", "presentedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Present a verified did:web credential.", "value": { "evidenceId": "cevi_abc", "agentId": "ag_support", "source": "did-web", "verified": true, "presentedAt": "2026-07-29T10:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "cachet.evidence.submit" ] }, { "OAuth2": [ "cachet.evidence.submit" ] }, { "WorkspaceApiKey": [ "cachet.evidence.submit" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/cachet.standing.get": { "post": { "operationId": "cachet_standing_get", "summary": "The current standing as an UNSIGNED preview, so an operator can see where they stand before publishing. Carries `signed: false` in the payload — it is not a cachet and nobody can verify it.", "x-trustvice-description-key": "actions.cachet.standing.get.description", "tags": [ "cachet" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "agentId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId", "agentId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Preview a standing before publishing.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "agentId": "ag_support" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "signed": { "type": "boolean", "const": false }, "note": { "type": "string" }, "agentId": { "type": "string" }, "declared": { "type": "boolean" }, "conduct": { "type": "object", "properties": { "grade": { "type": "string", "enum": [ "consistent", "unrated", "undeclared-conduct", "limit-breach" ] }, "runsObserved": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "divergence": { "type": "object", "properties": { "undeclared": { "type": "array", "items": { "type": "string" } }, "unexercised": { "type": "array", "items": { "type": "string" } }, "breaches": { "type": "array", "items": { "type": "string" } } }, "required": [ "undeclared", "unexercised", "breaches" ], "additionalProperties": false }, "basis": { "type": "string" } }, "required": [ "grade", "runsObserved", "divergence", "basis" ], "additionalProperties": false }, "identity": { "type": "object", "properties": { "grade": { "type": "string", "enum": [ "self-asserted", "domain-control", "workload-identity", "platform-attested", "business-verified", "mandate-bound", "wallet-verified" ] }, "accord": { "type": "string", "enum": [ "accurate", "understated", "overstated", "unpublished" ] }, "claimedGrade": { "anyOf": [ { "type": "string", "enum": [ "self-asserted", "domain-control", "workload-identity", "platform-attested", "business-verified", "mandate-bound", "wallet-verified" ] }, { "type": "null" } ] }, "source": { "type": [ "string", "null" ] }, "basis": { "type": "string" } }, "required": [ "grade", "accord", "claimedGrade" ], "additionalProperties": false }, "evidenceWindow": { "type": "object", "properties": { "from": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "to": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "from", "to" ], "additionalProperties": false }, "issuable": { "type": "boolean" } }, "required": [ "signed", "note", "agentId", "declared", "conduct", "identity", "evidenceWindow", "issuable" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Preview a standing before publishing.", "value": { "signed": false, "note": "This is an unsigned preview…", "agentId": "ag_support", "declared": true, "conduct": { "grade": "unrated", "runsObserved": 2, "divergence": { "undeclared": [], "unexercised": [], "breaches": [] }, "basis": "Only 2 run(s) observed…" }, "identity": { "grade": "self-asserted", "accord": "unpublished", "claimedGrade": null }, "evidenceWindow": { "from": null, "to": null }, "issuable": false } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "cachet.view" ] }, { "OAuth2": [ "cachet.view" ] }, { "WorkspaceApiKey": [ "cachet.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/cachet.issue": { "post": { "operationId": "cachet_issue", "summary": "Issue a signed, publicly resolvable standing. REFUSES an unrated conduct grade — a signed badge reads as an endorsement whatever word is inside it. `claimedGrade` is compared against the evidence and never raises the published grade.", "x-trustvice-description-key": "actions.cachet.issue.description", "tags": [ "cachet" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "agentId": { "type": "string", "minLength": 1 }, "claimedGrade": { "type": "string", "enum": [ "self-asserted", "domain-control", "workload-identity", "platform-attested", "business-verified", "mandate-bound", "wallet-verified" ] } }, "required": [ "workspaceId", "agentId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "An overstated claim publishes the evidence's grade and attaches the finding.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "agentId": "ag_support", "claimedGrade": "business-verified" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cachetId": { "type": "string", "pattern": "^cac_[A-Za-z0-9_-]{43}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "agentId": { "type": "string" }, "identity": { "type": "object", "properties": { "grade": { "type": "string", "enum": [ "self-asserted", "domain-control", "workload-identity", "platform-attested", "business-verified", "mandate-bound", "wallet-verified" ] }, "accord": { "type": "string", "enum": [ "accurate", "understated", "overstated", "unpublished" ] }, "claimedGrade": { "anyOf": [ { "type": "string", "enum": [ "self-asserted", "domain-control", "workload-identity", "platform-attested", "business-verified", "mandate-bound", "wallet-verified" ] }, { "type": "null" } ] }, "source": { "type": [ "string", "null" ] }, "basis": { "type": "string" } }, "required": [ "grade", "accord", "claimedGrade" ], "additionalProperties": false }, "conduct": { "type": "object", "properties": { "grade": { "type": "string", "enum": [ "consistent", "unrated", "undeclared-conduct", "limit-breach" ] }, "runsObserved": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "divergence": { "type": "object", "properties": { "undeclared": { "type": "array", "items": { "type": "string" } }, "unexercised": { "type": "array", "items": { "type": "string" } }, "breaches": { "type": "array", "items": { "type": "string" } } }, "required": [ "undeclared", "unexercised", "breaches" ], "additionalProperties": false }, "basis": { "type": "string" } }, "required": [ "grade", "runsObserved", "divergence", "basis" ], "additionalProperties": false }, "evidenceWindow": { "type": "object", "properties": { "from": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "to": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "from", "to" ], "additionalProperties": false }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "signature": { "type": "string" }, "signatureKeyId": { "type": "string" }, "canonical": { "type": "string" } }, "required": [ "cachetId", "workspaceId", "agentId", "identity", "conduct", "evidenceWindow", "issuedAt", "signature", "signatureKeyId", "canonical" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "An overstated claim publishes the evidence's grade and attaches the finding.", "value": { "cachetId": "cac_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "workspaceId": "ws_DEMODEFAULT0000000000", "agentId": "ag_support", "identity": { "grade": "domain-control", "accord": "overstated", "claimedGrade": "business-verified" }, "conduct": { "grade": "consistent", "runsObserved": 12, "divergence": { "undeclared": [], "unexercised": [], "breaches": [] }, "basis": "Across 12 runs…" }, "evidenceWindow": { "from": "2026-07-01T00:00:00.000Z", "to": "2026-07-28T00:00:00.000Z" }, "issuedAt": "2026-07-29T10:00:00.000Z", "signature": "…", "signatureKeyId": "…", "canonical": "{}" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "cachet.issue" ] }, { "OAuth2": [ "cachet.issue" ] }, { "WorkspaceApiKey": [ "cachet.issue" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/cachet.revoke": { "post": { "operationId": "cachet_revoke", "summary": "Withdraw an issued standing. NOT deletion — the cachet still resolves and reports that it was revoked and why, because a live citation must not 404 into 'never existed'. A reason is required.", "x-trustvice-description-key": "actions.cachet.revoke.description", "tags": [ "cachet" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "cachetId": { "type": "string", "pattern": "^cac_[A-Za-z0-9_-]{43}$" }, "reason": { "type": "string", "minLength": 10 } }, "required": [ "workspaceId", "cachetId", "reason" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Withdraw a standing without deleting it.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "cachetId": "cac_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "reason": "The agent's capability set changed materially after issuance." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cachetId": { "type": "string", "pattern": "^cac_[A-Za-z0-9_-]{43}$" }, "revoked": { "type": "boolean", "const": true }, "reason": { "type": "string" } }, "required": [ "cachetId", "revoked", "reason" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Withdraw a standing without deleting it.", "value": { "cachetId": "cac_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "revoked": true, "reason": "The agent's capability set changed materially after issuance." } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "cachet.revoke" ] }, { "OAuth2": [ "cachet.revoke" ] }, { "WorkspaceApiKey": [ "cachet.revoke" ] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "admin.action", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/cachet.list": { "post": { "operationId": "cachet_list", "summary": "List issued cachets for this workspace, optionally for one agent.", "x-trustvice-description-key": "actions.cachet.list.description", "tags": [ "cachet" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "agentId": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List issued cachets.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cachets": { "type": "array", "items": { "type": "object", "properties": { "cachetId": { "type": "string", "pattern": "^cac_[A-Za-z0-9_-]{43}$" }, "agentId": { "type": "string" }, "identity": { "type": "object", "properties": { "grade": { "type": "string", "enum": [ "self-asserted", "domain-control", "workload-identity", "platform-attested", "business-verified", "mandate-bound", "wallet-verified" ] }, "accord": { "type": "string", "enum": [ "accurate", "understated", "overstated", "unpublished" ] }, "claimedGrade": { "anyOf": [ { "type": "string", "enum": [ "self-asserted", "domain-control", "workload-identity", "platform-attested", "business-verified", "mandate-bound", "wallet-verified" ] }, { "type": "null" } ] }, "source": { "type": [ "string", "null" ] }, "basis": { "type": "string" } }, "required": [ "grade", "accord", "claimedGrade" ], "additionalProperties": false }, "conduct": { "type": "object", "properties": { "grade": { "type": "string", "enum": [ "consistent", "unrated", "undeclared-conduct", "limit-breach" ] }, "runsObserved": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "divergence": { "type": "object", "properties": { "undeclared": { "type": "array", "items": { "type": "string" } }, "unexercised": { "type": "array", "items": { "type": "string" } }, "breaches": { "type": "array", "items": { "type": "string" } } }, "required": [ "undeclared", "unexercised", "breaches" ], "additionalProperties": false }, "basis": { "type": "string" } }, "required": [ "grade", "runsObserved", "divergence", "basis" ], "additionalProperties": false }, "evidenceWindow": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "from", "to" ], "additionalProperties": false }, "evidenceAgeDays": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "revoked": { "type": "boolean" } }, "required": [ "cachetId", "agentId", "identity", "conduct", "evidenceWindow", "issuedAt", "revoked" ], "additionalProperties": {} } } }, "required": [ "cachets" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List issued cachets.", "value": { "cachets": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "cachet.view" ] }, { "OAuth2": [ "cachet.view" ] }, { "WorkspaceApiKey": [ "cachet.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/cachet.agents.list": { "post": { "operationId": "cachet_agents_list", "summary": "Every agent Cachet knows about, from either side. An agent that was OBSERVED but never DECLARED appears here — listing only declared agents would hide the finding worth showing first.", "x-trustvice-description-key": "actions.cachet.agents.list.description", "tags": [ "cachet" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "An observed-but-undeclared agent surfaces here.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "object", "properties": { "agentId": { "type": "string" }, "declared": { "type": "boolean" }, "conductGrade": { "type": "string", "enum": [ "consistent", "unrated", "undeclared-conduct", "limit-breach" ] }, "identityGrade": { "type": "string", "enum": [ "self-asserted", "domain-control", "workload-identity", "platform-attested", "business-verified", "mandate-bound", "wallet-verified" ] }, "runsObserved": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "issuable": { "type": "boolean" } }, "required": [ "agentId", "declared", "conductGrade", "identityGrade", "runsObserved", "issuable" ], "additionalProperties": false } } }, "required": [ "agents" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "An observed-but-undeclared agent surfaces here.", "value": { "agents": [ { "agentId": "ag_rogue", "declared": false, "conductGrade": "undeclared-conduct", "identityGrade": "self-asserted", "runsObserved": 9, "issuable": true } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "cachet.view" ] }, { "OAuth2": [ "cachet.view" ] }, { "WorkspaceApiKey": [ "cachet.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/cachet.resolve": { "post": { "operationId": "cachet_resolve", "summary": "PUBLIC. Fetch a standing by id. A revoked cachet still resolves and says so — deleting it would make a live citation read as 'never existed' rather than 'withdrawn'.", "x-trustvice-description-key": "actions.cachet.resolve.description", "tags": [ "cachet" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cachetId": { "type": "string", "pattern": "^cac_[A-Za-z0-9_-]{43}$" } }, "required": [ "cachetId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Resolve a standing with no account.", "value": { "cachetId": "cac_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cachetId": { "type": "string", "pattern": "^cac_[A-Za-z0-9_-]{43}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "agentId": { "type": "string" }, "identity": { "type": "object", "properties": { "grade": { "type": "string", "enum": [ "self-asserted", "domain-control", "workload-identity", "platform-attested", "business-verified", "mandate-bound", "wallet-verified" ] }, "accord": { "type": "string", "enum": [ "accurate", "understated", "overstated", "unpublished" ] }, "claimedGrade": { "anyOf": [ { "type": "string", "enum": [ "self-asserted", "domain-control", "workload-identity", "platform-attested", "business-verified", "mandate-bound", "wallet-verified" ] }, { "type": "null" } ] }, "source": { "type": [ "string", "null" ] }, "basis": { "type": "string" } }, "required": [ "grade", "accord", "claimedGrade" ], "additionalProperties": false }, "conduct": { "type": "object", "properties": { "grade": { "type": "string", "enum": [ "consistent", "unrated", "undeclared-conduct", "limit-breach" ] }, "runsObserved": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "divergence": { "type": "object", "properties": { "undeclared": { "type": "array", "items": { "type": "string" } }, "unexercised": { "type": "array", "items": { "type": "string" } }, "breaches": { "type": "array", "items": { "type": "string" } } }, "required": [ "undeclared", "unexercised", "breaches" ], "additionalProperties": false }, "basis": { "type": "string" } }, "required": [ "grade", "runsObserved", "divergence", "basis" ], "additionalProperties": false }, "evidenceWindow": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "to": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" } }, "required": [ "from", "to" ], "additionalProperties": false }, "evidenceAgeDays": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "signature": { "type": "string" }, "signatureKeyId": { "type": "string" }, "canonical": { "type": "string" }, "revoked": { "type": "boolean" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "revocationReason": { "type": [ "string", "null" ] } }, "required": [ "cachetId", "workspaceId", "agentId", "identity", "conduct", "evidenceWindow", "evidenceAgeDays", "issuedAt", "signature", "signatureKeyId", "canonical", "revoked", "revokedAt", "revocationReason" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Resolve a standing with no account.", "value": { "cachetId": "cac_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "workspaceId": "ws_DEMODEFAULT0000000000", "agentId": "ag_support", "identity": { "grade": "domain-control", "accord": "accurate", "claimedGrade": "domain-control" }, "conduct": { "grade": "consistent", "runsObserved": 12, "divergence": { "undeclared": [], "unexercised": [], "breaches": [] }, "basis": "…" }, "evidenceWindow": { "from": "2026-07-01T00:00:00.000Z", "to": "2026-07-28T00:00:00.000Z" }, "evidenceAgeDays": 1, "issuedAt": "2026-07-29T10:00:00.000Z", "signature": "…", "signatureKeyId": "…", "canonical": "{}", "revoked": false, "revokedAt": null, "revocationReason": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/cachet.verify": { "post": { "operationId": "cachet_verify", "summary": "PUBLIC. Check a cachet's bytes against its id and its signature against the published keys — and report whether it has been REVOKED, because cryptographic validity is not currency.", "x-trustvice-description-key": "actions.cachet.verify.description", "tags": [ "cachet" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cachetId": { "type": "string", "pattern": "^cac_[A-Za-z0-9_-]{43}$" }, "canonical": { "type": "string", "minLength": 1 }, "signature": { "type": "string" } }, "required": [ "cachetId", "canonical" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify bytes against the content address.", "value": { "cachetId": "cac_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "canonical": "{}" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "cachetId": { "type": "string", "pattern": "^cac_[A-Za-z0-9_-]{43}$" }, "signatureVerified": { "type": "boolean" }, "signatureKeyId": { "type": "string" }, "revoked": { "type": "boolean" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "revocationReason": { "type": [ "string", "null" ] }, "registryChecked": { "type": "boolean" }, "note": { "type": "string" } }, "required": [ "ok", "cachetId", "signatureVerified" ], "additionalProperties": false }, { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "reason": { "type": "string", "enum": [ "content-address-mismatch", "bad-signature", "unknown-key", "malformed" ] }, "expected": { "type": "string" }, "actual": { "type": "string" } }, "required": [ "ok", "reason" ], "additionalProperties": false } ] }, "examples": { "example_0": { "summary": "Verify bytes against the content address.", "value": { "ok": false, "reason": "content-address-mismatch" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/cachet.keys.get": { "post": { "operationId": "cachet_keys_get", "summary": "PUBLIC. The JWK Set cachets are signed with, for offline verification.", "x-trustvice-description-key": "actions.cachet.keys.get.description", "tags": [ "cachet" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read the signing keys.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "kty": { "type": "string" }, "crv": { "type": "string" }, "x": { "type": "string" }, "kid": { "type": "string", "pattern": "^[a-z0-9-]{4,64}$" }, "alg": { "type": "string" }, "use": { "type": "string" } }, "required": [ "kty", "crv", "x", "kid", "alg", "use" ], "additionalProperties": false } } }, "required": [ "keys" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read the signing keys.", "value": { "keys": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/emissary.publish": { "post": { "operationId": "emissary_publish", "summary": "Publish a signed, content-addressed declaration of what you permit AI crawlers and agents to do. Refuses a declaration that states nothing, declares two stances on one subject, or leaves a conditional without a condition. This is a STATEMENT, not an enforcement mechanism.", "x-trustvice-description-key": "actions.emissary.publish.description", "tags": [ "emissary" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "domain": { "type": "string", "minLength": 1 }, "directives": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string", "enum": [ "train", "infer", "quote", "index", "embed", "evaluate" ] }, "stance": { "type": "string", "enum": [ "allow", "deny", "conditional" ] }, "condition": { "type": "string", "minLength": 1 } }, "required": [ "subject", "stance" ] } }, "contact": { "type": "string" }, "licence": { "type": "string" }, "notes": { "type": "string" } }, "required": [ "workspaceId", "domain", "directives" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Deny training, allow indexing.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "domain": "example.com", "directives": [ { "subject": "train", "stance": "deny" }, { "subject": "index", "stance": "allow" } ], "contact": "ai@example.com" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "declarationId": { "type": "string", "pattern": "^emd_[A-Za-z0-9_-]{43}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "domain": { "type": "string" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "directives": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string", "enum": [ "train", "infer", "quote", "index", "embed", "evaluate" ] }, "stance": { "type": "string", "enum": [ "allow", "deny", "conditional" ] }, "condition": { "type": "string", "minLength": 1 } }, "required": [ "subject", "stance" ], "additionalProperties": false } }, "contact": { "type": [ "string", "null" ] }, "licence": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "publishedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "signature": { "type": "string" }, "signatureKeyId": { "type": "string" }, "retired": { "type": "boolean" }, "retiredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "canonical": { "type": "string" } }, "required": [ "declarationId", "workspaceId", "domain", "version", "directives", "contact", "licence", "notes", "publishedAt", "signature", "signatureKeyId", "retired", "retiredAt", "canonical" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Deny training, allow indexing.", "value": { "declarationId": "emd_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "workspaceId": "ws_DEMODEFAULT0000000000", "domain": "example.com", "version": 1, "directives": [ { "subject": "index", "stance": "allow" }, { "subject": "train", "stance": "deny" } ], "contact": "ai@example.com", "licence": null, "notes": null, "publishedAt": "2026-07-29T10:00:00.000Z", "signature": "…", "signatureKeyId": "…", "retired": false, "retiredAt": null, "canonical": "{}" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "emissary.publish" ] }, { "OAuth2": [ "emissary.publish" ] }, { "WorkspaceApiKey": [ "emissary.publish" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/emissary.list": { "post": { "operationId": "emissary_list", "summary": "List this workspace's declarations, newest first — including retired versions, which still resolve.", "x-trustvice-description-key": "actions.emissary.list.description", "tags": [ "emissary" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List declarations.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "declarations": { "type": "array", "items": { "type": "object", "properties": { "declarationId": { "type": "string", "pattern": "^emd_[A-Za-z0-9_-]{43}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "domain": { "type": "string" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "directives": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string", "enum": [ "train", "infer", "quote", "index", "embed", "evaluate" ] }, "stance": { "type": "string", "enum": [ "allow", "deny", "conditional" ] }, "condition": { "type": "string", "minLength": 1 } }, "required": [ "subject", "stance" ], "additionalProperties": false } }, "contact": { "type": [ "string", "null" ] }, "licence": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "publishedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "signature": { "type": "string" }, "signatureKeyId": { "type": "string" }, "retired": { "type": "boolean" }, "retiredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] } }, "required": [ "declarationId", "workspaceId", "domain", "version", "directives", "contact", "licence", "notes", "publishedAt", "signature", "signatureKeyId", "retired", "retiredAt" ], "additionalProperties": {} } } }, "required": [ "declarations" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List declarations.", "value": { "declarations": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "emissary.view" ] }, { "OAuth2": [ "emissary.view" ] }, { "WorkspaceApiKey": [ "emissary.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/emissary.current.get": { "post": { "operationId": "emissary_current_get", "summary": "The live declaration for a domain. Nothing published is reported as a GAP, never as a permissive default — silence is not permission.", "x-trustvice-description-key": "actions.emissary.current.get.description", "tags": [ "emissary" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "domain": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId", "domain" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read the live declaration.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "domain": "example.com" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "declarationId": { "type": "string", "pattern": "^emd_[A-Za-z0-9_-]{43}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "domain": { "type": "string" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "directives": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string", "enum": [ "train", "infer", "quote", "index", "embed", "evaluate" ] }, "stance": { "type": "string", "enum": [ "allow", "deny", "conditional" ] }, "condition": { "type": "string", "minLength": 1 } }, "required": [ "subject", "stance" ], "additionalProperties": false } }, "contact": { "type": [ "string", "null" ] }, "licence": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "publishedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "signature": { "type": "string" }, "signatureKeyId": { "type": "string" }, "retired": { "type": "boolean" }, "retiredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "canonical": { "type": "string" } }, "required": [ "declarationId", "workspaceId", "domain", "version", "directives", "contact", "licence", "notes", "publishedAt", "signature", "signatureKeyId", "retired", "retiredAt", "canonical" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read the live declaration.", "value": { "declarationId": "emd_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "workspaceId": "ws_DEMODEFAULT0000000000", "domain": "example.com", "version": 1, "directives": [], "contact": null, "licence": null, "notes": null, "publishedAt": "2026-07-29T10:00:00.000Z", "signature": "…", "signatureKeyId": "…", "retired": false, "retiredAt": null, "canonical": "{}" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "emissary.view" ] }, { "OAuth2": [ "emissary.view" ] }, { "WorkspaceApiKey": [ "emissary.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/emissary.fetches.list": { "post": { "operationId": "emissary_fetches_list", "summary": "The raw fetch ledger. Every row carries its attribution grade, and `operator` (CONFIRMED) is separate from `claimedOperator` (what the User-Agent said) — a User-Agent is typed by the client and proves nothing.", "x-trustvice-description-key": "actions.emissary.fetches.list.description", "tags": [ "emissary" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "declarationId": { "type": "string", "pattern": "^emd_[A-Za-z0-9_-]{43}$" }, "limit": { "type": "integer", "minimum": 1, "maximum": 500 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "A self-declared fetch: the claim is recorded, the operator is not.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fetches": { "type": "array", "items": { "type": "object", "properties": { "fetchId": { "type": "string" }, "declarationId": { "type": "string", "pattern": "^emd_[A-Za-z0-9_-]{43}$" }, "attributionGrade": { "type": "string", "enum": [ "unidentified", "self-declared", "ip-confirmed", "signature-verified" ] }, "operator": { "type": [ "string", "null" ] }, "claimedOperator": { "type": [ "string", "null" ] }, "contradicted": { "type": "boolean" }, "userAgent": { "type": [ "string", "null" ] }, "reverseDns": { "type": [ "string", "null" ] }, "forwardConfirmed": { "type": "boolean" }, "signatureKeyId": { "type": [ "string", "null" ] }, "basis": { "type": "string" }, "fetchedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "variant": { "type": "string", "enum": [ "json", "text" ] } }, "required": [ "fetchId", "declarationId", "attributionGrade", "operator", "claimedOperator", "contradicted", "userAgent", "reverseDns", "forwardConfirmed", "signatureKeyId", "basis", "fetchedAt", "variant" ], "additionalProperties": false } } }, "required": [ "fetches" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "A self-declared fetch: the claim is recorded, the operator is not.", "value": { "fetches": [ { "fetchId": "emf_abc", "declarationId": "emd_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "attributionGrade": "self-declared", "operator": null, "claimedOperator": "OpenAI", "contradicted": false, "userAgent": "Mozilla/5.0 (compatible; GPTBot/1.2)", "reverseDns": null, "forwardConfirmed": false, "signatureKeyId": null, "basis": "The User-Agent claims OpenAI. Nothing verified it…", "fetchedAt": "2026-07-29T10:00:00.000Z", "variant": "text" } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "emissary.fetches.view" ] }, { "OAuth2": [ "emissary.fetches.view" ] }, { "WorkspaceApiKey": [ "emissary.fetches.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/emissary.audience.get": { "post": { "operationId": "emissary_audience_get", "summary": "The graded audience summary. Counts split BY GRADE and never total into one 'N agents fetched your declaration' — that headline is how the category promotes User-Agent strings into facts. An unreadable ledger returns `unknown`, never zero.", "x-trustvice-description-key": "actions.emissary.audience.get.description", "tags": [ "emissary" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "declarationId": { "type": "string", "pattern": "^emd_[A-Za-z0-9_-]{43}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Confirmed and merely-claimed operators never merge.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "byGrade": { "type": "object", "propertyNames": { "type": "string", "enum": [ "unidentified", "self-declared", "ip-confirmed", "signature-verified" ] }, "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "required": [ "unidentified", "self-declared", "ip-confirmed", "signature-verified" ] }, "confirmedOperators": { "type": "array", "items": { "type": "object", "properties": { "operator": { "type": "string" }, "fetches": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "operator", "fetches" ], "additionalProperties": false } }, "claimedOnlyOperators": { "type": "array", "items": { "type": "object", "properties": { "operator": { "type": "string" }, "fetches": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "operator", "fetches" ], "additionalProperties": false } }, "contradictions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "citable": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "caveat": { "type": "string" } }, "required": [ "total", "byGrade", "confirmedOperators", "claimedOnlyOperators", "contradictions", "citable", "caveat" ], "additionalProperties": false }, { "type": "object", "properties": { "unknown": { "type": "boolean", "const": true }, "reason": { "type": "string" } }, "required": [ "unknown", "reason" ], "additionalProperties": false } ] }, "examples": { "example_0": { "summary": "Confirmed and merely-claimed operators never merge.", "value": { "total": 7, "byGrade": { "unidentified": 1, "self-declared": 2, "ip-confirmed": 3, "signature-verified": 1 }, "confirmedOperators": [ { "operator": "OpenAI", "fetches": 2 } ], "claimedOnlyOperators": [ { "operator": "Perplexity", "fetches": 1 } ], "contradictions": 1, "citable": 4, "caveat": "4 of 7 fetches were verified against something the client does not control…" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "emissary.audience.view" ] }, { "OAuth2": [ "emissary.audience.view" ] }, { "WorkspaceApiKey": [ "emissary.audience.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/emissary.agents.list": { "post": { "operationId": "emissary_agents_list", "summary": "The known-agent registry, with the BEST grade each operator could ever reach given what is registered — so an operator with no suffixes and no keys is told why its rows never clear the citable floor.", "x-trustvice-description-key": "actions.emissary.agents.list.description", "tags": [ "emissary" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "No registered keys means this operator can never reach signature-verified.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "object", "properties": { "operator": { "type": "string" }, "userAgentMarkers": { "type": "array", "items": { "type": "string" } }, "domainSuffixes": { "type": "array", "items": { "type": "string" } }, "signingKeyIds": { "type": "array", "items": { "type": "string" } }, "bestAchievableGrade": { "type": "string", "enum": [ "unidentified", "self-declared", "ip-confirmed", "signature-verified" ] } }, "required": [ "operator", "userAgentMarkers", "domainSuffixes", "signingKeyIds", "bestAchievableGrade" ], "additionalProperties": false } } }, "required": [ "agents" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "No registered keys means this operator can never reach signature-verified.", "value": { "agents": [ { "operator": "OpenAI", "userAgentMarkers": [ "GPTBot" ], "domainSuffixes": [ "openai.com" ], "signingKeyIds": [], "bestAchievableGrade": "ip-confirmed" } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "emissary.view" ] }, { "OAuth2": [ "emissary.view" ] }, { "WorkspaceApiKey": [ "emissary.view" ] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/emissary.agents.register": { "post": { "operationId": "emissary_agents_register", "summary": "Register or replace a known AI-agent operator. Requires at least one fingerprint — a User-Agent marker, a reverse-DNS suffix, or a signing key — because with none, no fetch could ever be matched to it.", "x-trustvice-description-key": "actions.emissary.agents.register.description", "tags": [ "emissary" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "operator": { "type": "string", "minLength": 1 }, "userAgentMarkers": { "type": "array", "items": { "type": "string" } }, "domainSuffixes": { "type": "array", "items": { "type": "string" } }, "signingKeys": { "type": "array", "items": { "type": "object", "properties": { "keyId": { "type": "string", "minLength": 1 }, "jwk": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "keyId", "jwk" ] } } }, "required": [ "workspaceId", "operator" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Register an operator so its fetches can reach ip-confirmed.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "operator": "Anthropic", "userAgentMarkers": [ "ClaudeBot" ], "domainSuffixes": [ "anthropic.com" ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentKey": { "type": "string" }, "operator": { "type": "string" }, "userAgentMarkers": { "type": "array", "items": { "type": "string" } }, "domainSuffixes": { "type": "array", "items": { "type": "string" } }, "signingKeys": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "agentKey", "operator", "userAgentMarkers", "domainSuffixes", "signingKeys" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Register an operator so its fetches can reach ip-confirmed.", "value": { "agentKey": "ema_anthropic_ws_DEMODEFAULT0000000000", "operator": "Anthropic", "userAgentMarkers": [ "ClaudeBot" ], "domainSuffixes": [ "anthropic.com" ], "signingKeys": 0 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "emissary.agents.manage" ] }, { "OAuth2": [ "emissary.agents.manage" ] }, { "WorkspaceApiKey": [ "emissary.agents.manage" ] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "admin.action", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/emissary.resolve": { "post": { "operationId": "emissary_resolve", "summary": "PUBLIC. Fetch a declaration by id, as JSON or as the rendered text form. Every fetch is ledgered with a graded attribution. A declaration nobody can fetch without credentials would tell no crawler anything.", "x-trustvice-description-key": "actions.emissary.resolve.description", "tags": [ "emissary" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "declarationId": { "type": "string", "pattern": "^emd_[A-Za-z0-9_-]{43}$" }, "variant": { "type": "string", "enum": [ "json", "text" ] } }, "required": [ "declarationId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Resolve a declaration with no account.", "value": { "declarationId": "emd_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "declarationId": { "type": "string", "pattern": "^emd_[A-Za-z0-9_-]{43}$" }, "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "domain": { "type": "string" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "directives": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string", "enum": [ "train", "infer", "quote", "index", "embed", "evaluate" ] }, "stance": { "type": "string", "enum": [ "allow", "deny", "conditional" ] }, "condition": { "type": "string", "minLength": 1 } }, "required": [ "subject", "stance" ], "additionalProperties": false } }, "contact": { "type": [ "string", "null" ] }, "licence": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "publishedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "signature": { "type": "string" }, "signatureKeyId": { "type": "string" }, "retired": { "type": "boolean" }, "retiredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "canonical": { "type": "string" } }, "required": [ "declarationId", "workspaceId", "domain", "version", "directives", "contact", "licence", "notes", "publishedAt", "signature", "signatureKeyId", "retired", "retiredAt", "canonical" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Resolve a declaration with no account.", "value": { "declarationId": "emd_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "workspaceId": "ws_DEMODEFAULT0000000000", "domain": "example.com", "version": 1, "directives": [ { "subject": "train", "stance": "deny" } ], "contact": null, "licence": null, "notes": null, "publishedAt": "2026-07-29T10:00:00.000Z", "signature": "…", "signatureKeyId": "…", "retired": false, "retiredAt": null, "canonical": "{}" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/emissary.verify": { "post": { "operationId": "emissary_verify", "summary": "PUBLIC. Check a declaration's bytes against its id and its signature against the published keys — and report whether it has been RETIRED, because validity is not currency.", "x-trustvice-description-key": "actions.emissary.verify.description", "tags": [ "emissary" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "declarationId": { "type": "string", "pattern": "^emd_[A-Za-z0-9_-]{43}$" }, "canonical": { "type": "string", "minLength": 1 }, "signature": { "type": "string" } }, "required": [ "declarationId", "canonical" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify bytes against the content address.", "value": { "declarationId": "emd_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "canonical": "{}" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "declarationId": { "type": "string", "pattern": "^emd_[A-Za-z0-9_-]{43}$" }, "signatureVerified": { "type": "boolean" }, "signatureKeyId": { "type": "string" }, "retired": { "type": "boolean" }, "retiredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, { "type": "null" } ] }, "registryChecked": { "type": "boolean" }, "note": { "type": "string" } }, "required": [ "ok", "declarationId", "signatureVerified" ], "additionalProperties": false }, { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "reason": { "type": "string", "enum": [ "content-address-mismatch", "bad-signature", "unknown-key", "malformed" ] }, "expected": { "type": "string" }, "actual": { "type": "string" } }, "required": [ "ok", "reason" ], "additionalProperties": false } ] }, "examples": { "example_0": { "summary": "Verify bytes against the content address.", "value": { "ok": false, "reason": "content-address-mismatch" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/emissary.keys.get": { "post": { "operationId": "emissary_keys_get", "summary": "PUBLIC. The JWK Set declarations are signed with, for offline verification.", "x-trustvice-description-key": "actions.emissary.keys.get.description", "tags": [ "emissary" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false }, "examples": { "example_0": { "summary": "Read the signing keys.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "kty": { "type": "string" }, "crv": { "type": "string" }, "x": { "type": "string" }, "kid": { "type": "string", "pattern": "^[a-z0-9-]{4,64}$" }, "alg": { "type": "string" }, "use": { "type": "string" } }, "required": [ "kty", "crv", "x", "kid", "alg", "use" ], "additionalProperties": false } } }, "required": [ "keys" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read the signing keys.", "value": { "keys": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": null, "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/c2pa.sign": { "post": { "operationId": "c2pa_sign", "summary": "Sign a content hash into a C2PA manifest — COSE_Sign1 over the deterministic-CBOR claim, returned as embeddable bytes.", "x-trustvice-description-key": "actions.c2pa.sign.description", "tags": [ "c2pa" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "contentSha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "mimeType": { "type": "string", "minLength": 1 }, "title": { "type": "string", "maxLength": 500 }, "assertions": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "data": {} }, "required": [ "label", "data" ], "additionalProperties": false } } }, "required": [ "workspaceId", "contentSha256", "mimeType" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Sign a content hash. Needs a provisioned regional signing key — absent, the worker answers an honest 503 rather than an unsigned manifest.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "contentSha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "mimeType": "image/png", "title": "Q3 results chart" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "manifest": { "type": "object", "properties": { "label": { "type": "string" }, "vendor": { "type": "string" }, "format": { "type": "string" }, "claim": {}, "claimSignature": { "type": "object", "properties": { "algorithm": { "type": "string", "const": "EdDSA" }, "keyId": { "type": "string" }, "signatureValue": { "type": "string" }, "signingTime": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "signerDid": { "type": "string" } }, "required": [ "algorithm", "keyId", "signatureValue", "signingTime", "signerDid" ], "additionalProperties": false } }, "required": [ "label", "vendor", "format", "claim", "claimSignature" ], "additionalProperties": false }, "manifestCborBase64Url": { "type": "string" }, "signedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "persisted": { "type": "boolean" }, "manifestUrl": { "type": "string" } }, "required": [ "manifest", "manifestCborBase64Url", "signedAt", "persisted" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Sign a content hash. Needs a provisioned regional signing key — absent, the worker answers an honest 503 rather than an unsigned manifest.", "value": { "manifest": { "label": "c2pa:ws_DEMODEFAULT0000000000:e3b0c442", "vendor": "trustvice", "format": "c2pa:manifest@2.1", "claim": {}, "claimSignature": { "algorithm": "EdDSA", "keyId": "c2pa-2026-q3-enam", "signatureValue": "0oRDoQEnoQRQ...", "signingTime": "2026-05-22T12:00:00.000Z", "signerDid": "did:web:trustvice.com" } }, "manifestCborBase64Url": "0oRDoQEnoQRQ...", "signedAt": "2026-05-22T12:00:00.000Z", "persisted": true, "manifestUrl": "/v1/c2pa/manifest/ws_DEMODEFAULT0000000000/c2pa:ws_DEMODEFAULT0000000000:e3b0c442" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_invocation", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/c2pa.verify": { "post": { "operationId": "c2pa_verify", "summary": "Verify a C2PA manifest against the published signer keys, and optionally assert it covers the content you have.", "x-trustvice-description-key": "actions.c2pa.verify.description", "tags": [ "c2pa" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "manifestCborBase64Url": { "type": "string", "minLength": 1 }, "expectedContentSha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "required": [ "workspaceId", "manifestCborBase64Url" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify a manifest. Needs no signing key — this answers in regions where signing is unprovisioned.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "manifestCborBase64Url": "0oRDoQEnoQRQ..." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "activeManifestLabel": { "type": "string" }, "signedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "signerDid": { "type": "string" }, "contentHashMatches": { "type": "boolean" }, "lineageDepth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "entpoindReceiptId": { "type": "string" }, "otsVerified": { "type": "boolean" } }, "required": [ "ok", "activeManifestLabel", "signedAt", "signerDid", "contentHashMatches", "lineageDepth" ], "additionalProperties": false }, { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "reason": { "type": "string", "enum": [ "no_manifest", "signature_invalid", "signer_not_trusted", "content_hash_mismatch", "malformed" ] }, "detail": { "type": "string" } }, "required": [ "ok", "reason" ], "additionalProperties": false } ] }, "examples": { "example_0": { "summary": "Verify a manifest. Needs no signing key — this answers in regions where signing is unprovisioned.", "value": { "ok": true, "activeManifestLabel": "c2pa:ws_DEMODEFAULT0000000000:e3b0c442", "signedAt": "2026-05-22T12:00:00.000Z", "signerDid": "did:web:trustvice.com", "contentHashMatches": true, "lineageDepth": 0 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/receipts.issue": { "post": { "operationId": "receipts_issue", "summary": "Mint a signed verifiable artifact — a receipt an auditor can check without trusting us, anchored into the Merkle batch.", "x-trustvice-description-key": "actions.receipts.issue.description", "tags": [ "receipts" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "kind": { "type": "string", "minLength": 1 }, "source": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "subject": {}, "claims": {} }, "required": [ "workspaceId", "kind" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Mint a Proof-of-Erasure. Needs a provisioned regional signing key — absent, the worker answers an honest 503 rather than an unsigned receipt. `topsRef` is null until the anchor batch runs.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "kind": "proof-of-erasure", "source": { "subjectRef": "user_9f2a", "erasedAt": "2026-05-22T12:00:00.000Z" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "artifactId": { "type": "string" }, "bundle": {}, "leafHash": { "type": "string" }, "topsRef": { "type": [ "string", "null" ] }, "signatureKeyId": { "type": "string" } }, "required": [ "artifactId", "bundle", "leafHash", "topsRef", "signatureKeyId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Mint a Proof-of-Erasure. Needs a provisioned regional signing key — absent, the worker answers an honest 503 rather than an unsigned receipt. `topsRef` is null until the anchor batch runs.", "value": { "artifactId": "01J9Z6M2K7QW8X0YB3C4D5E6F7", "bundle": {}, "leafHash": "a3f1c8e2…", "topsRef": null, "signatureKeyId": "entpoind-2026-q3-enam" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_invocation", "x-trustvice-idempotent": false, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/receipts.get": { "post": { "operationId": "receipts_get", "summary": "Read one verifiable artifact by id, including its anchor reference once the batch has run.", "x-trustvice-description-key": "actions.receipts.get.description", "tags": [ "receipts" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "artifactId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId", "artifactId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "An artifact belonging to another workspace answers 404, not 403 — the id space is not an enumeration oracle.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "artifactId": "01J9Z6M2K7QW8X0YB3C4D5E6F7" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "artifact": {}, "kind": { "type": "string" }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "leafHash": { "type": "string" }, "topsRef": { "type": [ "string", "null" ] } }, "required": [ "artifact", "kind", "issuedAt", "leafHash", "topsRef" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "An artifact belonging to another workspace answers 404, not 403 — the id space is not an enumeration oracle.", "value": { "artifact": {}, "kind": "proof-of-erasure", "issuedAt": "2026-05-22T12:00:00.000Z", "leafHash": "a3f1c8e2…", "topsRef": "tops_01J9…" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/receipts.list": { "post": { "operationId": "receipts_list", "summary": "List this workspace's verifiable artifacts, newest first, optionally filtered to one kind.", "x-trustvice-description-key": "actions.receipts.list.description", "tags": [ "receipts" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "kind": { "type": "string", "enum": [ "provable-residency", "proof-of-erasure", "oversight", "ai-bom", "consumer-disclosure", "verifiable-invoice", "continuity-of-witness", "exhibit", "regression", "drift-alarm", "conformity-attestation", "living-dossier", "incident-report", "regulatory-canon-drift", "actor-score", "agent-passport", "handshake-notary", "signed-retrieval", "memory-attestation", "interdiction" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "The list is a projection — it carries no claims and no signature. Fetch the artifact to verify one.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "kind": "proof-of-erasure", "limit": 50 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "artifacts": { "type": "array", "items": { "type": "object", "properties": { "artifactId": { "type": "string" }, "kind": { "type": "string" }, "subjectHash": { "type": "string" }, "issuedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "leafHash": { "type": "string" }, "topsRef": { "type": [ "string", "null" ] } }, "required": [ "artifactId", "kind", "subjectHash", "issuedAt", "leafHash", "topsRef" ], "additionalProperties": false } } }, "required": [ "artifacts" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "The list is a projection — it carries no claims and no signature. Fetch the artifact to verify one.", "value": { "artifacts": [ { "artifactId": "01J9Z6M2K7QW8X0YB3C4D5E6F7", "kind": "proof-of-erasure", "subjectHash": "9c1d…", "issuedAt": "2026-05-22T12:00:00.000Z", "leafHash": "a3f1c8e2…", "topsRef": "tops_01J9…" } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/receipts.verify": { "post": { "operationId": "receipts_verify", "summary": "Verify a signed artifact against the published keys — signature, and Merkle inclusion when you supply the anchored bundle.", "x-trustvice-description-key": "actions.receipts.verify.description", "tags": [ "receipts" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "bundle": {}, "artifact": {} }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Pure public-key work — this answers in a region where issuing is unprovisioned, and needs no signing key of ours.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "artifact": {} } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema" }, "examples": { "example_0": { "summary": "Pure public-key work — this answers in a region where issuing is unprovisioned, and needs no signing key of ours.", "value": { "ok": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/memory.put": { "post": { "operationId": "memory_put", "summary": "Write one memory entry. Requires a mandate unless writing your own namespace.", "x-trustvice-description-key": "actions.memory.put.description", "tags": [ "memory" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "agentDid": { "type": "string", "minLength": 7, "maxLength": 512, "pattern": "^did:" }, "key": { "type": "string", "minLength": 1, "maxLength": 512 }, "value": {}, "tags": { "maxItems": 32, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } }, "consentRef": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "workspaceId", "agentDid", "key", "value" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Write to your own namespace — no mandate needed.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "agentDid": "did:web:example.com:agents:ws:a1", "key": "user.name", "value": "Ada" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entry": { "type": "object", "properties": { "agentRef": { "type": "string" }, "key": { "type": "string" }, "value": {}, "contentSha256": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "version": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "agentRef", "key", "value", "contentSha256", "tags", "version", "createdAt", "updatedAt" ], "additionalProperties": {} } }, "required": [ "entry" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Write to your own namespace — no mandate needed.", "value": { "entry": { "agentRef": "did:web:example.com:agents:ws:a1", "key": "user.name", "value": "Ada", "contentSha256": "aa11", "tags": [], "version": 1, "createdAt": "2026-09-04T00:00:00.000Z", "updatedAt": "2026-09-04T00:00:00.000Z" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "mutation", "x-trustvice-confirmation-policy": "ask", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "portmind.memory_written", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/memory.get": { "post": { "operationId": "memory_get", "summary": "Read one memory entry by key.", "x-trustvice-description-key": "actions.memory.get.description", "tags": [ "memory" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "agentDid": { "type": "string", "minLength": 7, "maxLength": 512, "pattern": "^did:" }, "key": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "workspaceId", "agentDid", "key" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read one key.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "agentDid": "did:web:example.com:agents:ws:a1", "key": "user.name" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entry": { "type": "object", "properties": { "agentRef": { "type": "string" }, "key": { "type": "string" }, "value": {}, "contentSha256": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "version": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "agentRef", "key", "value", "contentSha256", "tags", "version", "createdAt", "updatedAt" ], "additionalProperties": {} } }, "required": [ "entry" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read one key.", "value": { "entry": { "agentRef": "did:web:example.com:agents:ws:a1", "key": "user.name", "value": "Ada", "contentSha256": "aa11", "tags": [], "version": 1, "createdAt": "2026-09-04T00:00:00.000Z", "updatedAt": "2026-09-04T00:00:00.000Z" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/memory.list": { "post": { "operationId": "memory_list", "summary": "List live memory entries for an agent, key-ordered.", "x-trustvice-description-key": "actions.memory.list.description", "tags": [ "memory" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "agentDid": { "type": "string", "minLength": 7, "maxLength": 512, "pattern": "^did:" }, "limit": { "default": 100, "type": "integer", "minimum": 1, "maximum": 500 } }, "required": [ "workspaceId", "agentDid" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List an agent's live memory.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "agentDid": "did:web:example.com:agents:ws:a1", "limit": 100 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "agentRef": { "type": "string" }, "key": { "type": "string" }, "value": {}, "contentSha256": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "version": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "agentRef", "key", "value", "contentSha256", "tags", "version", "createdAt", "updatedAt" ], "additionalProperties": {} } } }, "required": [ "entries" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List an agent's live memory.", "value": { "entries": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/memory.remove": { "post": { "operationId": "memory_remove", "summary": "Tombstone one memory entry. A deletion is a WRITE and needs write authority.", "x-trustvice-description-key": "actions.memory.remove.description", "tags": [ "memory" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "agentDid": { "type": "string", "minLength": 7, "maxLength": 512, "pattern": "^did:" }, "key": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "workspaceId", "agentDid", "key" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Tombstone one key; the snapshot still reflects that it is gone.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "agentDid": "did:web:example.com:agents:ws:a1", "key": "user.name" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "removed": { "type": "boolean" }, "agentRef": { "type": "string" }, "key": { "type": "string" } }, "required": [ "removed", "agentRef", "key" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Tombstone one key; the snapshot still reflects that it is gone.", "value": { "removed": true, "agentRef": "did:web:example.com:agents:ws:a1", "key": "user.name" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "destructive", "x-trustvice-confirmation-policy": "always", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "portmind.memory_removed", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/memory.snapshot": { "post": { "operationId": "memory_snapshot", "summary": "Merkle snapshot of an agent's live memory — the root a portable export verifies against.", "x-trustvice-description-key": "actions.memory.snapshot.description", "tags": [ "memory" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "agentDid": { "type": "string", "minLength": 7, "maxLength": 512, "pattern": "^did:" } }, "required": [ "workspaceId", "agentDid" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Snapshot for a verifiable export.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "agentDid": "did:web:example.com:agents:ws:a1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "snapshot": { "type": "object", "properties": { "agentRef": { "type": "string" }, "snapshotRef": { "type": "string" }, "entryCount": { "type": "number" }, "merkleRoot": { "type": "string" }, "earliestEntryAt": { "type": [ "string", "null" ] }, "latestEntryAt": { "type": [ "string", "null" ] }, "snapshotAt": { "type": "string" } }, "required": [ "agentRef", "snapshotRef", "entryCount", "merkleRoot", "earliestEntryAt", "latestEntryAt", "snapshotAt" ], "additionalProperties": {} }, "mint": { "type": "object", "properties": { "kind": { "type": "string" }, "source": {} }, "required": [ "kind", "source" ], "additionalProperties": {} } }, "required": [ "snapshot", "mint" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Snapshot for a verifiable export.", "value": { "snapshot": { "agentRef": "did:web:example.com:agents:ws:a1", "snapshotRef": "snap_abc", "entryCount": 0, "merkleRoot": "root", "earliestEntryAt": null, "latestEntryAt": null, "snapshotAt": "2026-09-04T00:00:00.000Z" }, "mint": { "kind": "memory-attestation", "source": {} } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/memory.export": { "post": { "operationId": "memory_export", "summary": "Export an agent's live memory as a portable, tamper-evident bundle.", "x-trustvice-description-key": "actions.memory.export.description", "tags": [ "memory" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "agentDid": { "type": "string", "minLength": 7, "maxLength": 512, "pattern": "^did:" } }, "required": [ "workspaceId", "agentDid" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "A portable export. Unattested until a receipt travels with it.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "agentDid": "did:web:example.com:agents:ws:a1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "bundle": { "type": "object", "properties": { "agentRef": { "type": "string", "minLength": 1 }, "entries": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "contentSha256": { "type": "string", "minLength": 1 } }, "required": [ "key", "contentSha256" ], "additionalProperties": false } }, "claimedRoot": { "type": "string", "minLength": 1 }, "exportedAt": { "type": "string", "minLength": 1 }, "exportedBy": { "type": "string", "minLength": 1 }, "origin": { "type": "string", "enum": [ "anchored", "signed", "unattested" ] }, "anchorRef": { "type": [ "string", "null" ] } }, "required": [ "agentRef", "entries", "claimedRoot", "exportedAt", "exportedBy", "origin" ], "additionalProperties": {} }, "attestationPath": { "type": "string" }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "bundle", "attestationPath", "notes" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "A portable export. Unattested until a receipt travels with it.", "value": { "bundle": { "agentRef": "did:web:example.com:agents:ws:a1", "entries": [], "claimedRoot": "root", "exportedAt": "2026-09-04T00:00:00.000Z", "exportedBy": "ws_DEMODEFAULT0000000000", "origin": "unattested", "anchorRef": null }, "attestationPath": "POST /v1/portmind/snapshot → mint the `memory-attestation` receipt at entpoind → ship it beside this bundle.", "notes": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } }, "/v1/actions/memory.import.verify": { "post": { "operationId": "memory_import_verify", "summary": "Verify a portable memory bundle that arrived from anywhere — integrity now, completeness only against a root committed to beforehand.", "x-trustvice-description-key": "actions.memory.import.verify.description", "tags": [ "memory" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Trustvice-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Trustvice-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "bundle": { "type": "object", "properties": { "agentRef": { "type": "string", "minLength": 1 }, "entries": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "contentSha256": { "type": "string", "minLength": 1 } }, "required": [ "key", "contentSha256" ], "additionalProperties": false } }, "claimedRoot": { "type": "string", "minLength": 1 }, "exportedAt": { "type": "string", "minLength": 1 }, "exportedBy": { "type": "string", "minLength": 1 }, "origin": { "type": "string", "enum": [ "anchored", "signed", "unattested" ] }, "anchorRef": { "type": [ "string", "null" ] } }, "required": [ "agentRef", "entries", "claimedRoot", "exportedAt", "exportedBy", "origin" ], "additionalProperties": {} }, "expectedRoot": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId", "bundle" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Integrity is checkable here; completeness is not, without a prior root.", "value": { "workspaceId": "ws_DEMODEFAULT0000000000", "bundle": { "agentRef": "agent_a", "entries": [ { "key": "goal", "contentSha256": "ab" } ], "claimedRoot": "root", "exportedAt": "2026-09-04T00:00:00.000Z", "exportedBy": "other-vendor", "origin": "unattested" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "verification": { "type": "object", "properties": { "agentRef": { "type": "string" }, "integrity": { "type": "string", "enum": [ "intact", "root_mismatch", "duplicate_keys" ] }, "completeness": { "type": "string", "enum": [ "matches_expected_root", "differs_from_expected_root", "unknown" ] }, "recomputedRoot": { "type": "string" }, "entryCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "origin": { "type": "string", "enum": [ "anchored", "signed", "unattested" ] }, "safeToTrustAsComplete": { "type": "boolean" }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "agentRef", "integrity", "completeness", "recomputedRoot", "entryCount", "origin", "safeToTrustAsComplete", "notes" ], "additionalProperties": {} } }, "required": [ "verification" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Integrity is checkable here; completeness is not, without a prior root.", "value": { "verification": { "agentRef": "agent_a", "integrity": "root_mismatch", "completeness": "unknown", "recomputedRoot": "computed", "entryCount": 1, "origin": "unattested", "safeToTrustAsComplete": false, "notes": [] } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Trustvice-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [] }, { "OAuth2": [] }, { "WorkspaceApiKey": [] } ], "x-trustvice-safety-level": "read", "x-trustvice-confirmation-policy": "none", "x-trustvice-rate-class": "default", "x-trustvice-audit-kind": "agent_read", "x-trustvice-idempotent": true, "x-trustvice-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill" ] } } }, "components": { "schemas": { "ErrorEnvelope": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable error message." }, "details": { "type": "object", "additionalProperties": true }, "requestId": { "type": "string", "description": "Server-assigned request id for support." } } } } }, "ConfirmationRequired": { "type": "object", "required": [ "error", "confirmation" ], "properties": { "error": { "$ref": "#/components/schemas/ErrorEnvelope/properties/error" }, "confirmation": { "type": "object", "required": [ "challengeId", "confirmationUrl", "expiresAt" ], "properties": { "challengeId": { "type": "string" }, "confirmationUrl": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" }, "reason": { "type": "string" } } } } } }, "securitySchemes": { "BearerPat": { "type": "http", "scheme": "bearer", "bearerFormat": "Trustvice PAT (tv_pat_*)", "description": "Personal access token. Scopes are derived from the actor's org + workspace roles." }, "OAuth2": { "type": "oauth2", "description": "OAuth 2.1 + PKCE + DPoP — for agentic apps acting on behalf of a Trustvice user.", "flows": { "authorizationCode": { "authorizationUrl": "https://trustvice.com/auth/authorize", "tokenUrl": "https://api.trustvice.com/v1/oauth/token", "scopes": { "admin:workspace": "Grants the `admin:workspace` OAuth/PAT scope.", "manage:entpoind": "Grants the `manage:entpoind` OAuth/PAT scope.", "read:entpoind": "Grants the `read:entpoind` OAuth/PAT scope.", "read:workspace": "Grants the `read:workspace` OAuth/PAT scope.", "write:entpoind": "Grants the `write:entpoind` OAuth/PAT scope.", "write:keys": "Grants the `write:keys` OAuth/PAT scope.", "write:webhooks": "Grants the `write:webhooks` OAuth/PAT scope.", "write:workspace": "Grants the `write:workspace` OAuth/PAT scope." } } } }, "WorkspaceApiKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Workspace-scoped API key. Prefixed `tv_*` (control plane) or `entp_*` (Trustvice Receipts data plane)." } } } }