{ "openapi": "3.1.0", "info": { "title": "Agined + Attestor API", "version": "0.32.289-agined.1", "description": "The Agined + Attestor App exposes the customer's full control surface as model-callable actions. Use it to: read audit logs and Tops feed; issue/verify Attestor cryptographic receipts; manage workspaces, API keys, webhooks, alerts; request EU AI Act Article 12 exports; submit GDPR DSRs; manage billing. Destructive and billing-impacting actions require an X-Agined-Confirmation (the App SDK will surface a confirmation modal). Every action exposed here is also reachable via MCP, ChatGPT Apps, Gemini Extensions, Perplexity, Claude Cowork, and A2A — see AGENTS.md for the catalogue. Auto-generated from `@agined/contracts@0.32.289-agined.1` on 2026-11-10T21:32:07.834Z.", "contact": { "name": "Agined", "url": "https://agined.com", "email": "support@agined.com" }, "license": { "name": "Agined Terms of Service", "url": "https://agined.com/legal" }, "x-agined-generated-at": "2026-11-10T21:32:07.834Z", "x-agined-contracts-version": "0.32.289-agined.1" }, "servers": [ { "url": "https://api.agined.com", "description": "Production gateway." }, { "url": "https://api.staging.agined.com", "description": "Staging gateway." } ], "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, packs, top-ups, invoices, cost centers." }, { "name": "keys", "description": "Personal access tokens, workspace API keys (av_ + atst_)." }, { "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": "attestor", "description": "8 Attestor primitives + workspace-level Attestor 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": { "/api/v1/actions/account.session.list": { "post": { "operationId": "account_session_list", "summary": "List active sessions on this account.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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": "^acct_[A-Za-z0-9_-]{11,}$" }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/account.session.revoke": { "post": { "operationId": "account_session_revoke", "summary": "Revoke an active session by id (cannot be disabled — safety floor).", "x-agined-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-Agined-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": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "admin.action", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/account.profile.get": { "post": { "operationId": "account_profile_get", "summary": "Get the authenticated account's profile.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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": "^acct_[A-Za-z0-9_-]{11,}$" }, "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", "pt", "it" ] }, "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": "acct_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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/account.profile.update": { "post": { "operationId": "account_profile_update", "summary": "Update account profile (display name, avatar URL).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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": "^acct_[A-Za-z0-9_-]{11,}$" }, "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": "acct_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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "admin.action", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-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": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "admin.action", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/account.email.change.pending": { "post": { "operationId": "account_email_change_pending", "summary": "The email change currently in flight for this account, if any, and which address still has to confirm it.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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": "The new address confirmed; the old one has not.", "value": {} }, "example_1": { "summary": "No change in flight.", "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": "The new address confirmed; the old one has not.", "value": { "pending": { "newEmail": "new@example.com", "requestedAt": "2026-08-26T12:00:00.000Z", "expiresAt": "2026-08-27T12:00:00.000Z", "awaitingOldAddress": true, "awaitingNewAddress": false } } }, "example_1": { "summary": "No change in flight.", "value": { "pending": 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/account.passkey.list": { "post": { "operationId": "account_passkey_list", "summary": "List registered passkeys.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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" }, "authenticatorAttachment": { "type": "string", "enum": [ "platform", "cross-platform" ] } }, "required": [ "credentialId", "nickname", "createdAt", "lastUsedAt", "backupEligible", "authenticatorAttachment" ], "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/account.passkey.revoke": { "post": { "operationId": "account_passkey_revoke", "summary": "Revoke a registered passkey.", "x-agined-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-Agined-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": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "admin.action", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-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": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "admin.action", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest" ] } }, "/api/v1/actions/account.locale.set": { "post": { "operationId": "account_locale_set", "summary": "Set the account-level preferred locale (overrides browser default).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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", "pt", "it" ] } }, "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", "pt", "it" ] } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/account.display-preferences.set": { "post": { "operationId": "account_display-preferences_set", "summary": "Set the account-level theme and timezone.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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 } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Switch to the dark theme.", "value": { "theme": "dark" } } } } } }, "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", "null" ] } }, "required": [ "theme", "timezone" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Switch to the dark theme.", "value": { "theme": "dark", "timezone": 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/account.notifications.get": { "post": { "operationId": "account_notifications_get", "summary": "Read notification preferences.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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" }, "shadowSessionStarted": { "type": "boolean" }, "shadowDailyDigest": { "type": "boolean" }, "invitationAlerts": { "type": "boolean" }, "quotaWarnings": { "type": "boolean" }, "privacyRightsAlerts": { "type": "boolean" }, "digestCadence": { "type": "string", "enum": [ "off", "daily", "weekly" ] } }, "required": [ "marketingEmails", "securityAlerts", "billingAlerts", "productUpdates", "agentSessionStarted", "agentSessionAnomaly", "shadowSessionStarted", "shadowDailyDigest", "invitationAlerts", "quotaWarnings", "privacyRightsAlerts", "digestCadence" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read prefs.", "value": { "marketingEmails": false, "securityAlerts": true, "billingAlerts": true, "productUpdates": false, "agentSessionStarted": true, "agentSessionAnomaly": true, "shadowSessionStarted": true, "shadowDailyDigest": false, "invitationAlerts": true, "quotaWarnings": true, "privacyRightsAlerts": 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/account.notifications.update": { "post": { "operationId": "account_notifications_update", "summary": "Update notification preferences.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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" }, "shadowSessionStarted": { "type": "boolean" }, "shadowDailyDigest": { "type": "boolean" }, "invitationAlerts": { "type": "boolean" }, "quotaWarnings": { "type": "boolean" }, "privacyRightsAlerts": { "type": "boolean" }, "digestCadence": { "type": "string", "enum": [ "off", "daily", "weekly" ] } }, "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" }, "shadowSessionStarted": { "type": "boolean" }, "shadowDailyDigest": { "type": "boolean" }, "invitationAlerts": { "type": "boolean" }, "quotaWarnings": { "type": "boolean" }, "privacyRightsAlerts": { "type": "boolean" }, "digestCadence": { "type": "string", "enum": [ "off", "daily", "weekly" ] } }, "required": [ "marketingEmails", "securityAlerts", "billingAlerts", "productUpdates", "agentSessionStarted", "agentSessionAnomaly", "shadowSessionStarted", "shadowDailyDigest", "invitationAlerts", "quotaWarnings", "privacyRightsAlerts", "digestCadence" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Turn on anomaly alerts.", "value": { "marketingEmails": false, "securityAlerts": true, "billingAlerts": true, "productUpdates": false, "agentSessionStarted": true, "agentSessionAnomaly": true, "shadowSessionStarted": true, "shadowDailyDigest": false, "invitationAlerts": true, "quotaWarnings": true, "privacyRightsAlerts": 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/account.token.list": { "post": { "operationId": "account_token_list", "summary": "List your Personal Access Tokens (PATs).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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": "^(?:av|tv)_pat_(?:demo_[0-9A-HJKMNP-TV-Z]{26}|[0-9a-f]{10})$" }, "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", "null" ] }, "last4": { "type": "string" } }, "required": [ "id", "prefix", "label", "scopes", "createdAt", "expiresAt", "lastUsedAt", "revokedAt", "last4" ], "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/account.token.issue": { "post": { "operationId": "account_token_issue", "summary": "Issue a new Personal Access Token. Cleartext shown ONCE.", "x-agined-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-Agined-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": "Agined-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:tools" ], "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": "^(?:av|tv)_pat_(?:demo_[0-9A-HJKMNP-TV-Z]{26}|[0-9a-f]{10})$" }, "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", "null" ] }, "last4": { "type": "string" } }, "required": [ "id", "prefix", "label", "scopes", "createdAt", "expiresAt", "lastUsedAt", "revokedAt", "last4" ], "additionalProperties": false }, "cleartext": { "type": "string" } }, "required": [ "token", "cleartext" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Mint a new PAT; cleartext shown once.", "value": { "token": { "id": "av_pat_a1b2c3d4e5", "prefix": "av_pat_abc", "label": "CI pipeline", "scopes": [ "read:workspace", "write:tools" ], "createdAt": "2026-05-22T12:00:00.000Z", "expiresAt": "2026-08-20T12:00:00.000Z", "lastUsedAt": null, "revokedAt": null, "ipCidrBinding": null, "last4": "9f2c" }, "cleartext": "av_pat_abc_REDACTED_EXAMPLE_ONLY" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "mandate", "x-agined-rate-class": "default", "x-agined-audit-kind": "key.issued", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest" ] } }, "/api/v1/actions/account.token.revoke": { "post": { "operationId": "account_token_revoke", "summary": "Revoke a PAT (cannot be disabled — safety floor).", "x-agined-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-Agined-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": "Agined-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": "^(?:av|tv)_pat_(?:demo_[0-9A-HJKMNP-TV-Z]{26}|[0-9a-f]{10})$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "tokenId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Revoke a PAT.", "value": { "tokenId": "av_pat_a1b2c3d4e5" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "key.revoked", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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 }, "clientLogoUrl": { "type": [ "string", "null" ] }, "attenuatedSubGrants": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "clientId", "clientName", "scopes", "grantedAt", "lastUsedAt", "expiresAt", "dpopBound", "delegationDepthAllowed", "clientLogoUrl", "attenuatedSubGrants" ], "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-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": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "key.revoked", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/account.delete": { "post": { "operationId": "account_delete", "summary": "Schedule account deletion after a grace window (30 days by default). Organizations you solely own are scheduled with it; ones with other members are reported back instead. Requires WebAuthn step-up.", "x-agined-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-Agined-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": "Agined-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; the shared org needs an ownership transfer first.", "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": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "organizationsScheduled": { "type": "array", "items": { "type": "object", "properties": { "organizationId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "organizationId", "name" ], "additionalProperties": false } }, "organizationsBlocked": { "type": "array", "items": { "type": "object", "properties": { "organizationId": { "type": "string" }, "name": { "type": "string" }, "otherMemberCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "organizationId", "name", "otherMemberCount" ], "additionalProperties": false } } }, "required": [ "scheduledDeletionAt", "gracePeriodDays", "organizationsScheduled", "organizationsBlocked" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Start account deletion with grace period; the shared org needs an ownership transfer first.", "value": { "scheduledDeletionAt": "2026-06-21T00:00:00.000Z", "gracePeriodDays": 30, "organizationsScheduled": [ { "organizationId": "org_solo", "name": "Jake's Workspace" } ], "organizationsBlocked": [ { "organizationId": "org_team", "name": "Acme Corp", "otherMemberCount": 4 } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "mandate", "x-agined-rate-class": "default", "x-agined-audit-kind": "admin.action", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/org.get": { "post": { "operationId": "org_get", "summary": "Get the current organization's details.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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_[A-Za-z0-9_-]{11,}$" }, "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", "pt", "it" ] } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/org.update": { "post": { "operationId": "org_update", "summary": "Update organization name + locale.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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", "pt", "it" ] } }, "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_[A-Za-z0-9_-]{11,}$" }, "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", "pt", "it" ] } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "admin.action", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/org.locale.set": { "post": { "operationId": "org_locale_set", "summary": "Set the organization-default locale (inherited by new workspaces).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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", "pt", "it" ] } }, "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", "pt", "it" ] } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/org.member.list": { "post": { "operationId": "org_member_list", "summary": "List organization members.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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": "^acct_[A-Za-z0-9_-]{11,}$" }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/org.member.invite": { "post": { "operationId": "org_member_invite", "summary": "Invite a new member to the organization. Sends a verification email.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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": "^acct_[A-Za-z0-9_-]{11,}$" }, "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": "acct_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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "member.invited", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-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": "Agined-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": "^acct_[A-Za-z0-9_-]{11,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "accountId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Remove a member.", "value": { "accountId": "acct_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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "member.removed", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/org.member.role.change": { "post": { "operationId": "org_member_role_change", "summary": "Change an org member's role.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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": "^acct_[A-Za-z0-9_-]{11,}$" }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ] } }, "required": [ "accountId", "role" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Promote to admin.", "value": { "accountId": "acct_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": "^acct_[A-Za-z0-9_-]{11,}$" }, "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": "acct_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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "member.role_changed", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/org.invitations.list": { "post": { "operationId": "org_invitations_list", "summary": "List pending/expired invitations.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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": "^acct_[A-Za-z0-9_-]{11,}$" }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/org.invitations.resend": { "post": { "operationId": "org_invitations_resend", "summary": "Resend a pending invitation (subject to 5-minute cooldown).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "member.invited", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/org.invitations.revoke": { "post": { "operationId": "org_invitations_revoke", "summary": "Revoke a pending invitation.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "member.removed", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/org.transfer-ownership": { "post": { "operationId": "org_transfer-ownership", "summary": "Transfer org ownership to another admin. Requires WebAuthn step-up + reason.", "x-agined-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-Agined-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": "Agined-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": "^acct_[A-Za-z0-9_-]{11,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "newOwnerAccountId", "reason" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Hand off org ownership.", "value": { "newOwnerAccountId": "acct_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_[A-Za-z0-9_-]{11,}$" }, "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", "pt", "it" ] } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "admin.action", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/org.delete.schedule": { "post": { "operationId": "org_delete_schedule", "summary": "Schedule organization deletion in 30 days. Cancellable within the grace window.", "x-agined-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-Agined-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": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "admin.action", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/org.delete.cancel": { "post": { "operationId": "org_delete_cancel", "summary": "Cancel a previously-scheduled org deletion (within grace).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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_[A-Za-z0-9_-]{11,}$" }, "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", "pt", "it" ] } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "admin.action", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/org.audit.list": { "post": { "operationId": "org_audit_list", "summary": "Read org-level audit log entries (admin actions, member changes, billing).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-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": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "mandate", "x-agined-rate-class": "default", "x-agined-audit-kind": "org.sso_config_changed", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/org.sso.connections.delete": { "post": { "operationId": "org_sso_connections_delete", "summary": "Delete an SSO connection by id (org-scoped).", "x-agined-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-Agined-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": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "org.sso_config_changed", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "org.sso_config_changed", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "org.sso_config_changed", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-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": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "mandate", "x-agined-rate-class": "default", "x-agined-audit-kind": "org.sso_config_changed", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/org.sso.domains.delete": { "post": { "operationId": "org_sso_domains_delete", "summary": "Remove a captured SSO domain (org-scoped).", "x-agined-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-Agined-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": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "org.sso_config_changed", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-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": "Agined-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://auth.agined.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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "mandate", "x-agined-rate-class": "default", "x-agined-audit-kind": "org.sso_config_changed", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/org.sso.scim-tokens.revoke": { "post": { "operationId": "org_sso_scim-tokens_revoke", "summary": "Revoke a SCIM bearer token by id.", "x-agined-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-Agined-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": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "org.sso_config_changed", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/workspace.list": { "post": { "operationId": "workspace_list", "summary": "List all workspaces in the current organization.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/workspace.get": { "post": { "operationId": "workspace_get", "summary": "Get the full state of a single workspace by id.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read the active workspace's full state.", "value": { "workspaceId": "ws_demo_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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "name": "Default workspace", "organizationId": "org_demo00000000000000000000", "jurisdiction": "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/workspace.create": { "post": { "operationId": "workspace_create", "summary": "Create a new workspace in the current organization.", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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", "pt", "it" ] } }, "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", "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_new0000000000", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "workspace.created", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/workspace.update": { "post": { "operationId": "workspace_update", "summary": "Update workspace settings (name, retention, locale, Tools controls).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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", "pt", "it" ] }, "toolsAutoOverageEnabled": { "type": "boolean" }, "toolsAutoOverageCapMultiplier": { "type": "integer", "minimum": 1, "maximum": 10 }, "toolsBillingMode": { "type": "string", "enum": [ "combined", "separate" ] }, "attestorAutoOverageEnabled": { "type": "boolean" }, "attestorAutoOverageCapMultiplier": { "type": "integer", "minimum": 1, "maximum": 10 }, "attestorBillingMode": { "type": "string", "enum": [ "combined", "separate" ] } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Enable Tools auto-overage with a 3× cap.", "value": { "workspaceId": "ws_demo_default", "toolsAutoOverageEnabled": true, "toolsAutoOverageCapMultiplier": 3 } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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 Tools auto-overage with a 3× cap.", "value": { "id": "ws_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "workspace.renamed", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/workspace.rename": { "post": { "operationId": "workspace_rename", "summary": "Rename a workspace (convenience alias of workspace.update).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "workspaceId", "name" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Rename a workspace.", "value": { "workspaceId": "ws_demo_default", "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "workspace.renamed", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/workspace.delete.schedule": { "post": { "operationId": "workspace_delete_schedule", "summary": "Schedule a workspace for deletion in 30 days (grace period).", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "workspace.scheduled_deletion", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/workspace.delete.cancel": { "post": { "operationId": "workspace_delete_cancel", "summary": "Cancel a previously-scheduled workspace deletion (within grace).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Cancel deletion within the grace window.", "value": { "workspaceId": "ws_demo_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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "workspace.deletion_canceled", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/workspace.region.binding-proof": { "post": { "operationId": "workspace_region_binding-proof", "summary": "Download the OpenTimestamps proof of the workspace's region binding.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Pull the region-binding OTS proof for offline verification.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/workspace.member.list": { "post": { "operationId": "workspace_member_list", "summary": "List members of a workspace with their roles.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List workspace members.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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": "^acct_[A-Za-z0-9_-]{11,}$" }, "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": "acct_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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/workspace.member.add": { "post": { "operationId": "workspace_member_add", "summary": "Add an organization member to a workspace with a specific role.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "accountId": { "type": "string", "pattern": "^acct_[A-Za-z0-9_-]{11,}$" }, "role": { "type": "string", "enum": [ "admin", "member", "auditor" ] } }, "required": [ "workspaceId", "accountId", "role" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Add a member.", "value": { "workspaceId": "ws_demo_default", "accountId": "acct_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": "^acct_[A-Za-z0-9_-]{11,}$" }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "auditor" ] } }, "required": [ "accountId", "role" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Add a member.", "value": { "accountId": "acct_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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "member.joined", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/workspace.member.role.change": { "post": { "operationId": "workspace_member_role_change", "summary": "Change a workspace member's role.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "accountId": { "type": "string", "pattern": "^acct_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "accountId": "acct_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": "^acct_[A-Za-z0-9_-]{11,}$" }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "auditor" ] } }, "required": [ "accountId", "role" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Promote a member to admin.", "value": { "accountId": "acct_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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "member.role_changed", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/workspace.member.remove": { "post": { "operationId": "workspace_member_remove", "summary": "Remove a member from a workspace.", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "accountId": { "type": "string", "pattern": "^acct_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId", "accountId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Remove a workspace member.", "value": { "workspaceId": "ws_demo_default", "accountId": "acct_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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "member.removed", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/workspace.transfer-ownership": { "post": { "operationId": "workspace_transfer-ownership", "summary": "Transfer workspace ownership to another admin.", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "newOwnerAccountId": { "type": "string", "pattern": "^acct_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "newOwnerAccountId": "acct_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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "admin.action", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/workspace.attestor.enable": { "post": { "operationId": "workspace_attestor_enable", "summary": "Enable Attestor on a workspace (requires an org-level Attestor subscription).", "x-agined-description-key": "actions.workspace.attestor.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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Enable Attestor on a workspace.", "value": { "workspaceId": "ws_demo_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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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 Attestor on a workspace.", "value": { "id": "ws_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "workspace.renamed", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/workspace.attestor.disable": { "post": { "operationId": "workspace_attestor_disable", "summary": "Disable Attestor on a workspace.", "x-agined-description-key": "actions.workspace.attestor.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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Turn off Attestor on this workspace.", "value": { "workspaceId": "ws_demo_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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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 Attestor on this workspace.", "value": { "id": "ws_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "workspace.renamed", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/workspace.regions.list": { "post": { "operationId": "workspace_regions_list", "summary": "List the available regions a workspace can be created in.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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 all 21 supported regions 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 all 21 supported regions for region picker UIs.", "value": { "regions": [ { "id": "cloudflare-d1:weur", "label": "Western Europe", "countryCode": "DE", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.subscription.get": { "post": { "operationId": "billing_subscription_get", "summary": "Get the org's current subscription.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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_[A-Za-z0-9_-]{11,}$" }, "plan": { "type": "string" }, "status": { "type": "string", "enum": [ "trialing", "active", "past_due", "canceled", "unpaid", "suspended" ] }, "currentPeriodStart": { "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" } ] }, "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" } ] }, "cancelAtPeriodEnd": { "type": "boolean" } }, "required": [ "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.subscription.upgrade": { "post": { "operationId": "billing_subscription_upgrade", "summary": "Upgrade to a higher tier. Prorates charges; takes effect immediately.", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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_[A-Za-z0-9_-]{11,}$" }, "plan": { "type": "string" }, "status": { "type": "string", "enum": [ "trialing", "active", "past_due", "canceled", "unpaid", "suspended" ] }, "currentPeriodStart": { "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" } ] }, "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" } ] }, "cancelAtPeriodEnd": { "type": "boolean" } }, "required": [ "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "plan.changed", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.subscription.downgrade": { "post": { "operationId": "billing_subscription_downgrade", "summary": "Downgrade to a lower tier. Effective at next billing period.", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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_[A-Za-z0-9_-]{11,}$" }, "plan": { "type": "string" }, "status": { "type": "string", "enum": [ "trialing", "active", "past_due", "canceled", "unpaid", "suspended" ] }, "currentPeriodStart": { "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" } ] }, "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" } ] }, "cancelAtPeriodEnd": { "type": "boolean" } }, "required": [ "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "plan.changed", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.subscription.cancel": { "post": { "operationId": "billing_subscription_cancel", "summary": "Cancel subscription at current period end. Workspace remains accessible until then.", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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_[A-Za-z0-9_-]{11,}$" }, "plan": { "type": "string" }, "status": { "type": "string", "enum": [ "trialing", "active", "past_due", "canceled", "unpaid", "suspended" ] }, "currentPeriodStart": { "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" } ] }, "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" } ] }, "cancelAtPeriodEnd": { "type": "boolean" } }, "required": [ "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "plan.changed", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.subscription.reactivate": { "post": { "operationId": "billing_subscription_reactivate", "summary": "Reactivate a subscription that's been scheduled to cancel.", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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_[A-Za-z0-9_-]{11,}$" }, "plan": { "type": "string" }, "status": { "type": "string", "enum": [ "trialing", "active", "past_due", "canceled", "unpaid", "suspended" ] }, "currentPeriodStart": { "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" } ] }, "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" } ] }, "cancelAtPeriodEnd": { "type": "boolean" } }, "required": [ "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "plan.changed", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.invoices.list": { "post": { "operationId": "billing_invoices_list", "summary": "List invoices.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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_[A-Za-z0-9_-]{11,}$" }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.invoices.get": { "post": { "operationId": "billing_invoices_get", "summary": "Get a single invoice.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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_[A-Za-z0-9_-]{11,}$" }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.invoices.download": { "post": { "operationId": "billing_invoices_download", "summary": "Get a signed download URL for the invoice PDF.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Download invoice PDF.", "value": { "url": "https://billing.example.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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.payment-method.get": { "post": { "operationId": "billing_payment-method_get", "summary": "Get the current default payment method (masked).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": { "brand": { "type": "string" }, "last4": { "type": "string" }, "expMonth": { "type": "integer", "minimum": 1, "maximum": 12 }, "expYear": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "brand", "last4", "expMonth", "expYear" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read masked payment method.", "value": { "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.payment-method.update-url": { "post": { "operationId": "billing_payment-method_update-url", "summary": "Get a signed URL to the hosted payment-method update page. The update happens there, not in Agined.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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 the billing 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" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Get the billing portal URL.", "value": { "url": "https://billing.example.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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.packs.list": { "post": { "operationId": "billing_packs_list", "summary": "List available top-up packs (runs, Number One queries, Tools calls).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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", "tools-calls", "attestor-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", "tools-calls", "attestor-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.packs.purchase": { "post": { "operationId": "billing_packs_purchase", "summary": "Purchase a top-up pack.", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "packId", "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Buy a 1k-run pack — complete payment at checkoutUrl; the credit lands via webhook.", "value": { "packId": "runs_1k", "workspaceId": "ws_demo_default" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "checkoutUrl": { "type": "string", "format": "uri" }, "sessionId": { "type": "string" } }, "required": [ "checkoutUrl", "sessionId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Buy a 1k-run pack — complete payment at checkoutUrl; the credit lands via webhook.", "value": { "checkoutUrl": "https://billing.example.com/c/pay/cs_test_REDACTED", "sessionId": "cs_test_REDACTED" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "pack.purchased", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.auto-topup.get": { "post": { "operationId": "billing_auto-topup_get", "summary": "Get auto-topup configuration.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read auto-topup config.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "auto_topup.configured", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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_[A-Za-z0-9_-]{11,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string" }, "taggableProducts": { "type": "array", "items": { "type": "string", "enum": [ "tools", "agined", "attestor", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.cost-centers.create": { "post": { "operationId": "billing_cost-centers_create", "summary": "Create a cost center.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": [ "tools" ], "type": "array", "items": { "type": "string", "enum": [ "tools" ] } }, "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_[A-Za-z0-9_-]{11,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string" }, "taggableProducts": { "type": "array", "items": { "type": "string", "enum": [ "tools", "agined", "attestor", "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": [ "tools" ], "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.cost-centers.update": { "post": { "operationId": "billing_cost-centers_update", "summary": "Update a cost center.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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_[A-Za-z0-9_-]{11,}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string" }, "taggableProducts": { "type": "array", "items": { "type": "string", "enum": [ "tools", "agined", "attestor", "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": [ "tools" ], "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.cost-centers.delete": { "post": { "operationId": "billing_cost-centers_delete", "summary": "Delete a cost center. Tagged charges keep historical tag.", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.notarian.subscribe": { "post": { "operationId": "billing_notarian_subscribe", "summary": "Subscribe to the Notarian add-on (per-tier subscription pricing).", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Subscribe to Notarian.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "notarian.subscribed", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.notarian.unsubscribe": { "post": { "operationId": "billing_notarian_unsubscribe", "summary": "Unsubscribe from Notarian at next billing period.", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Unsubscribe Notarian.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "notarian.canceled", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.retention-extension.unsubscribe": { "post": { "operationId": "billing_retention-extension_unsubscribe", "summary": "Cancel the paid retention extension. Coverage continues until the paid-through date.", "x-agined-description-key": "actions.billing.retention-extension.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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Cancel the retention extension; coverage runs to the paid-through date.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "unsubscribed": { "type": "boolean" }, "effectiveAt": { "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": [ "unsubscribed", "effectiveAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Cancel the retention extension; coverage runs to the paid-through date.", "value": { "unsubscribed": true, "effectiveAt": "2026-09-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "retention.updated", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.multi-workspace.subscribe": { "post": { "operationId": "billing_multi-workspace_subscribe", "summary": "Subscribe the organization to the multi-workspace add-on, allowing more than one workspace.", "x-agined-description-key": "actions.billing.multi-workspace.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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "Buy the multi-workspace add-on.", "value": {} } } } } }, "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": "Buy the multi-workspace add-on.", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.multi-workspace.unsubscribe": { "post": { "operationId": "billing_multi-workspace_unsubscribe", "summary": "Cancel the multi-workspace add-on at the end of the current period.", "x-agined-description-key": "actions.billing.multi-workspace.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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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 } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Cancel the multi-workspace add-on.", "value": {} } } } } }, "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": "Cancel the multi-workspace add-on.", "value": { "unsubscribed": true, "effectiveAt": "2026-09-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Subscribe Infinite Memory.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.infinite-memory.unsubscribe": { "post": { "operationId": "billing_infinite-memory_unsubscribe", "summary": "Unsubscribe Infinite Memory at next billing period.", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Unsubscribe Infinite Memory.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "retention.updated", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.attestor.tier.set": { "post": { "operationId": "billing_attestor_tier_set", "summary": "Set the Attestor subscription tier for the org.", "x-agined-description-key": "actions.billing.attestor.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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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 Attestor 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_[A-Za-z0-9_-]{11,}$" }, "plan": { "type": "string" }, "status": { "type": "string", "enum": [ "trialing", "active", "past_due", "canceled", "unpaid", "suspended" ] }, "currentPeriodStart": { "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" } ] }, "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" } ] }, "cancelAtPeriodEnd": { "type": "boolean" } }, "required": [ "organizationId", "plan", "status", "currentPeriodStart", "currentPeriodEnd", "cancelAtPeriodEnd" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Set Attestor tier.", "value": { "subscriptionId": "sub_atst_abc", "organizationId": "org_demo00000000000000000000", "plan": "scale", "status": "active", "currentPeriodStart": "2026-05-22T12:00:00.000Z", "currentPeriodEnd": "2026-06-22T12:00:00.000Z", "cancelAtPeriodEnd": false } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "plan.changed", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.attestor.tier.get": { "post": { "operationId": "billing_attestor_tier_get", "summary": "Get the current Attestor tier.", "x-agined-description-key": "actions.billing.attestor.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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 Attestor 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 Attestor 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.attestor.top-up.purchase": { "post": { "operationId": "billing_attestor_top-up_purchase", "summary": "Purchase an Attestor top-up pack (extra call quota for the current month).", "x-agined-description-key": "actions.billing.attestor.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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "packId": { "type": "string" } }, "required": [ "workspaceId", "packId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Buy 100k Attestor calls.", "value": { "workspaceId": "ws_demo_default", "packId": "attestor_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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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 Attestor calls.", "value": { "topUpId": "tu_atst_abc", "workspaceId": "ws_demo_default", "packKind": "attestor-calls", "unitCount": 100000, "priceUsdMinor": 1900, "purchasedAt": "2026-05-22T12:00:00.000Z", "unitsRemaining": 100000, "forfeitedAt": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "pack.purchased", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.attestor.auto-overage.set": { "post": { "operationId": "billing_attestor_auto-overage_set", "summary": "Configure auto-overage for an Attestor-enabled workspace.", "x-agined-description-key": "actions.billing.attestor.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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "auto_topup.configured", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.attestor.billing-mode.set": { "post": { "operationId": "billing_attestor_billing-mode_set", "summary": "Set the Attestor billing mode (combined vs separate subscription).", "x-agined-description-key": "actions.billing.attestor.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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 subscriptions for Agined + Attestor.", "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 subscriptions for Agined + Attestor.", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.attestor.usage.current": { "post": { "operationId": "billing_attestor_usage_current", "summary": "Get current Attestor usage for the org (calls used + remaining quota + auto-overage status).", "x-agined-description-key": "actions.billing.attestor.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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 Attestor 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 Attestor 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.ledger-bundles.subscribe": { "post": { "operationId": "billing_ledger-bundles_subscribe", "summary": "Subscribe to the LedgerBundles add-on (per-tier subscription pricing).", "x-agined-description-key": "actions.billing.ledger-bundles.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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Subscribe to LedgerBundles.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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 LedgerBundles.", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "ledger-bundles.subscribed", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/billing.ledger-bundles.unsubscribe": { "post": { "operationId": "billing_ledger-bundles_unsubscribe", "summary": "Unsubscribe from LedgerBundles at next billing period.", "x-agined-description-key": "actions.billing.ledger-bundles.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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Unsubscribe LedgerBundles.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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 LedgerBundles.", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "ledger-bundles.canceled", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/keys.list": { "post": { "operationId": "keys_list", "summary": "List workspace API keys (active + revoked filter).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "includeRevoked": { "default": false, "type": "boolean" }, "product": { "type": "string", "enum": [ "agined", "attestor" ] } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List active keys.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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": "^(av|atst|entp)_[a-z0-9_]{4,}_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "product": { "type": "string", "enum": [ "agined", "attestor" ] }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/keys.get": { "post": { "operationId": "keys_get", "summary": "Get a single workspace API key by id.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "keyId": { "type": "string", "pattern": "^(av|atst|entp)_[a-z0-9_]{4,}_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId", "keyId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Fetch one key.", "value": { "workspaceId": "ws_demo_default", "keyId": "av_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": "^(av|atst|entp)_[a-z0-9_]{4,}_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "product": { "type": "string", "enum": [ "agined", "attestor" ] }, "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": "av_workspace_abc20charsforexampleid", "workspaceId": "ws_demo_default", "product": "agined", "label": "Prod key", "prefix": "av_abc", "scopes": [ "ingest:write" ], "createdAt": "2026-05-22T12:00:00.000Z", "lastUsedAt": null, "expiresAt": null, "revokedAt": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/keys.issue": { "post": { "operationId": "keys_issue", "summary": "Issue a new workspace API key. Cleartext returned ONCE.", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "product": { "default": "agined", "type": "string", "enum": [ "agined", "attestor" ] }, "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_demo_default", "product": "agined", "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": "^(av|atst|entp)_[a-z0-9_]{4,}_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "product": { "type": "string", "enum": [ "agined", "attestor" ] }, "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": "av_workspace_abc20charsforexampleid", "workspaceId": "ws_demo_default", "product": "agined", "label": "Prod ingest key", "prefix": "av_abc", "scopes": [ "ingest:write" ], "createdAt": "2026-05-22T12:00:00.000Z", "lastUsedAt": null, "expiresAt": "2027-05-22T12:00:00.000Z", "revokedAt": null }, "cleartext": "av_abc_REDACTED_EXAMPLE_ONLY" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "key.issued", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/keys.revoke": { "post": { "operationId": "keys_revoke", "summary": "Revoke a workspace API key. Propagates in ≤30s.", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "keyId": { "type": "string", "pattern": "^(av|atst|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_demo_default", "keyId": "av_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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "key.revoked", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "keyId": { "type": "string", "pattern": "^(av|atst|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_demo_default", "keyId": "av_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": "^(av|atst|entp)_[a-z0-9_]{4,}_[0-9A-Z]{20,}$" }, "newKey": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^(av|atst|entp)_[a-z0-9_]{4,}_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "product": { "type": "string", "enum": [ "agined", "attestor" ] }, "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": "av_workspace_abc20charsforexampleid", "newKey": { "id": "av_workspace_def20charsforexampleid", "workspaceId": "ws_demo_default", "product": "agined", "label": "Prod ingest key", "prefix": "av_def", "scopes": [ "ingest:write" ], "createdAt": "2026-05-22T12:00:00.000Z", "lastUsedAt": null, "expiresAt": null, "revokedAt": null }, "cleartext": "av_def_REDACTED_EXAMPLE_ONLY", "graceUntil": "2026-05-22T12:05:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "key.rotated", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/keys.scopes.list": { "post": { "operationId": "keys_scopes_list", "summary": "List the available scope grants for workspace API keys.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": [ "agined", "attestor" ] } }, "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": [ "agined", "attestor" ] }, "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": "agined", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "keyId": { "type": "string", "pattern": "^(av|atst|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_demo_default", "keyId": "av_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": "/api/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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "expensive", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/keys.last-used.get": { "post": { "operationId": "keys_last-used_get", "summary": "Quick lookup: when was this key last used?", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "keyId": { "type": "string", "pattern": "^(av|atst|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_demo_default", "keyId": "av_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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/keys.attestor.list": { "post": { "operationId": "keys_attestor_list", "summary": "Convenience: list only the Attestor-product workspace keys.", "x-agined-description-key": "actions.keys.attestor.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "includeRevoked": { "default": false, "type": "boolean" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List Attestor-only keys.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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": "^(av|atst|entp)_[a-z0-9_]{4,}_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "product": { "type": "string", "enum": [ "agined", "attestor" ] }, "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 Attestor-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/keys.attestor.issue": { "post": { "operationId": "keys_attestor_issue", "summary": "Issue an Attestor-product workspace key (atst_*). Cleartext shown ONCE.", "x-agined-description-key": "actions.keys.attestor.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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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 an Attestor key.", "value": { "workspaceId": "ws_demo_default", "label": "Attestor attestation key", "scopes": [ "attestor:agent-call:write", "attestor: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": "^(av|atst|entp)_[a-z0-9_]{4,}_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "product": { "type": "string", "enum": [ "agined", "attestor" ] }, "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 an Attestor key.", "value": { "key": { "id": "atst_workspace_abc20charsforexampleid", "workspaceId": "ws_demo_default", "product": "attestor", "label": "Attestor attestation key", "prefix": "atst_abc", "scopes": [ "attestor:agent-call:write", "attestor:content-attest:write" ], "createdAt": "2026-05-22T12:00:00.000Z", "lastUsedAt": null, "expiresAt": "2026-08-20T12:00:00.000Z", "revokedAt": null }, "cleartext": "atst_abc_REDACTED_EXAMPLE_ONLY" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "key.issued", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/keys.ingest-secret.list": { "post": { "operationId": "keys_ingest-secret_list", "summary": "List this workspace's ingest secrets (metadata only — never the secret value).", "x-agined-description-key": "actions.keys.ingest-secret.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "includeRevoked": { "default": false, "type": "boolean" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "See which platforms can deliver.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "secrets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "platformId": { "type": "string", "pattern": "^(webhook|cloud-event|marketplace):[a-z0-9][a-z0-9-]{0,39}$" }, "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))$" }, "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", "platformId", "createdAt", "revokedAt" ], "additionalProperties": false } } }, "required": [ "secrets" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "See which platforms can deliver.", "value": { "secrets": [ { "id": "wis_abc123", "workspaceId": "ws_demo_default", "platformId": "webhook:vapi", "createdAt": "2026-09-03T12:00:00.000Z", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/keys.ingest-secret.issue": { "post": { "operationId": "keys_ingest-secret_issue", "summary": "Issue an ingest secret for a platform. Any active secret for that platform is revoked. Cleartext returned ONCE.", "x-agined-description-key": "actions.keys.ingest-secret.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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "platformId": { "type": "string", "pattern": "^(webhook|cloud-event|marketplace):[a-z0-9][a-z0-9-]{0,39}$" } }, "required": [ "workspaceId", "platformId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Generate the secret a Vapi webhook signs with.", "value": { "workspaceId": "ws_demo_default", "platformId": "webhook:vapi" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "secret": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "platformId": { "type": "string", "pattern": "^(webhook|cloud-event|marketplace):[a-z0-9][a-z0-9-]{0,39}$" }, "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))$" }, "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", "platformId", "createdAt", "revokedAt" ], "additionalProperties": false }, "cleartext": { "type": "string" }, "revokedSecretId": { "type": [ "string", "null" ] } }, "required": [ "secret", "cleartext", "revokedSecretId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Generate the secret a Vapi webhook signs with.", "value": { "secret": { "id": "wis_def456", "workspaceId": "ws_demo_default", "platformId": "webhook:vapi", "createdAt": "2026-09-03T12:00:00.000Z", "revokedAt": null }, "cleartext": "wis_REDACTED_EXAMPLE_ONLY", "revokedSecretId": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "key.issued", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/keys.ingest-secret.revoke": { "post": { "operationId": "keys_ingest-secret_revoke", "summary": "Revoke an ingest secret without issuing a replacement. Deliveries for that platform then fail closed.", "x-agined-description-key": "actions.keys.ingest-secret.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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "secretId": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "secretId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Stop accepting deliveries for a platform.", "value": { "workspaceId": "ws_demo_default", "secretId": "wis_def456", "reason": "Rotating after a partner offboarding." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "revoked": { "type": "boolean", "const": true }, "secretId": { "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))$" } }, "required": [ "revoked", "secretId", "revokedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Stop accepting deliveries for a platform.", "value": { "revoked": true, "secretId": "wis_def456", "revokedAt": "2026-09-03T12: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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "key.revoked", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/webhooks.list": { "post": { "operationId": "webhooks_list", "summary": "List webhook endpoints for a workspace.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "enabledOnly": { "default": false, "type": "boolean" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List webhooks.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "url": { "type": "string", "format": "uri" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "record.created", "lens.hit", "notary.anchored", "ledger-bundles.anchored", "pack.purchased", "plan.changed", "member.invited", "member.removed", "key.issued", "key.revoked", "alert.fired", "export.ready", "export.failed" ] } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/webhooks.get": { "post": { "operationId": "webhooks_get", "summary": "Get a single webhook endpoint.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "webhookId": { "type": "string", "pattern": "^wh_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId", "webhookId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read a webhook.", "value": { "workspaceId": "ws_demo_default", "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "url": { "type": "string", "format": "uri" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "record.created", "lens.hit", "notary.anchored", "ledger-bundles.anchored", "pack.purchased", "plan.changed", "member.invited", "member.removed", "key.issued", "key.revoked", "alert.fired", "export.ready", "export.failed" ] } }, "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_demo_default", "url": "https://example.com/webhook", "label": "Production hook", "events": [ "alert.fired" ], "enabled": true, "secretPrefix": "whsec_ab", "createdAt": "2026-05-22T12:00:00.000Z", "updatedAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/webhooks.create": { "post": { "operationId": "webhooks_create", "summary": "Register a new webhook endpoint. Returns the signing secret cleartext ONCE.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "url": { "type": "string", "format": "uri" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "events": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "record.created", "lens.hit", "notary.anchored", "ledger-bundles.anchored", "pack.purchased", "plan.changed", "member.invited", "member.removed", "key.issued", "key.revoked", "alert.fired", "export.ready", "export.failed" ] } } }, "required": [ "workspaceId", "url", "label", "events" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Create + receive signing secret.", "value": { "workspaceId": "ws_demo_default", "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "url": { "type": "string", "format": "uri" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "record.created", "lens.hit", "notary.anchored", "ledger-bundles.anchored", "pack.purchased", "plan.changed", "member.invited", "member.removed", "key.issued", "key.revoked", "alert.fired", "export.ready", "export.failed" ] } }, "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_demo_default", "url": "https://example.com/webhook", "label": "Prod hook", "events": [ "alert.fired", "export.ready" ], "enabled": true, "secretPrefix": "whsec_ab", "createdAt": "2026-05-22T12:00:00.000Z", "updatedAt": "2026-05-22T12:00:00.000Z" }, "signingSecretCleartext": "whsec_REDACTED_EXAMPLE_ONLY" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "webhook.created", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/webhooks.update": { "post": { "operationId": "webhooks_update", "summary": "Update a webhook's URL, label, or event subscriptions.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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", "enum": [ "record.created", "lens.hit", "notary.anchored", "ledger-bundles.anchored", "pack.purchased", "plan.changed", "member.invited", "member.removed", "key.issued", "key.revoked", "alert.fired", "export.ready", "export.failed" ] } } }, "required": [ "workspaceId", "webhookId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Narrow subscription set.", "value": { "workspaceId": "ws_demo_default", "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "url": { "type": "string", "format": "uri" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "record.created", "lens.hit", "notary.anchored", "ledger-bundles.anchored", "pack.purchased", "plan.changed", "member.invited", "member.removed", "key.issued", "key.revoked", "alert.fired", "export.ready", "export.failed" ] } }, "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_demo_default", "url": "https://example.com/webhook", "label": "Prod hook", "events": [ "alert.fired" ], "enabled": true, "secretPrefix": "whsec_ab", "createdAt": "2026-05-22T12:00:00.000Z", "updatedAt": "2026-05-22T12:05:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "webhook.updated", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/webhooks.delete": { "post": { "operationId": "webhooks_delete", "summary": "Delete a webhook endpoint. Pending deliveries are abandoned.", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "webhook.deleted", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/webhooks.enable": { "post": { "operationId": "webhooks_enable", "summary": "Enable or disable a webhook without deleting it.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "url": { "type": "string", "format": "uri" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "events": { "type": "array", "items": { "type": "string", "enum": [ "record.created", "lens.hit", "notary.anchored", "ledger-bundles.anchored", "pack.purchased", "plan.changed", "member.invited", "member.removed", "key.issued", "key.revoked", "alert.fired", "export.ready", "export.failed" ] } }, "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_demo_default", "url": "https://example.com/webhook", "label": "Prod hook", "events": [ "alert.fired" ], "enabled": false, "secretPrefix": "whsec_ab", "createdAt": "2026-05-22T12:00:00.000Z", "updatedAt": "2026-05-22T12:10:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "webhook.updated", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "expensive", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "webhook.updated", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/webhooks.deliveries.list": { "post": { "operationId": "webhooks_deliveries_list", "summary": "List delivery attempts for a webhook (success + failure history).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/webhooks.deliveries.retry": { "post": { "operationId": "webhooks_deliveries_retry", "summary": "Retry a specific failed delivery.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/alerts.list": { "post": { "operationId": "alerts_list", "summary": "List alert rules for a workspace.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "enabledOnly": { "default": false, "type": "boolean" }, "typeFilter": { "type": "string" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List alerts.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "type": { "type": "string" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "enabled": { "type": "boolean" }, "config": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] }, "quotaKind": { "type": "string", "enum": [ "runs", "number-one" ] } }, "required": [ "type", "thresholdPercent", "quotaKind" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "pack_balance_low" }, "thresholdRuns": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "packKind": { "type": "string", "enum": [ "runs", "number-one" ] } }, "required": [ "type", "thresholdRuns", "packKind" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "payment_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_succeeded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_cap_hit" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "hash_chain_mismatch" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "webhook_delivery_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "notarian_anchor_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "lens_hit" }, "lensId": { "type": "string", "minLength": 1 } }, "required": [ "type", "lensId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "scheduled_for_deletion" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "admin_read" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "member_role_change" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "key_issued" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "key_revoked" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_abuse_flagged" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_abuse_suspended" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] } }, "required": [ "type", "thresholdPercent" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_monitor_check_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_tls_vantages_disagree" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "mandate_expiring" }, "daysBefore": { "anyOf": [ { "type": "number", "const": 1 }, { "type": "number", "const": 3 }, { "type": "number", "const": 7 }, { "type": "number", "const": 14 }, { "type": "number", "const": 30 } ] } }, "required": [ "type", "daysBefore" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "ledger_bundles_anchor_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_abuse_flagged" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_abuse_suspended" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] } }, "required": [ "type", "thresholdPercent" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_monitor_check_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false } ] }, "channels": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "email" }, "addresses": { "minItems": 1, "type": "array", "items": { "type": "string", "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", "addresses" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "webhook" }, "webhookId": { "type": "string", "minLength": 1 } }, "required": [ "kind", "webhookId" ], "additionalProperties": false } ] } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/alerts.get": { "post": { "operationId": "alerts_get", "summary": "Get a single alert rule.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "type": { "type": "string" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "enabled": { "type": "boolean" }, "config": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] }, "quotaKind": { "type": "string", "enum": [ "runs", "number-one" ] } }, "required": [ "type", "thresholdPercent", "quotaKind" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "pack_balance_low" }, "thresholdRuns": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "packKind": { "type": "string", "enum": [ "runs", "number-one" ] } }, "required": [ "type", "thresholdRuns", "packKind" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "payment_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_succeeded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_cap_hit" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "hash_chain_mismatch" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "webhook_delivery_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "notarian_anchor_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "lens_hit" }, "lensId": { "type": "string", "minLength": 1 } }, "required": [ "type", "lensId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "scheduled_for_deletion" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "admin_read" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "member_role_change" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "key_issued" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "key_revoked" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_abuse_flagged" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_abuse_suspended" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] } }, "required": [ "type", "thresholdPercent" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_monitor_check_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_tls_vantages_disagree" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "mandate_expiring" }, "daysBefore": { "anyOf": [ { "type": "number", "const": 1 }, { "type": "number", "const": 3 }, { "type": "number", "const": 7 }, { "type": "number", "const": 14 }, { "type": "number", "const": 30 } ] } }, "required": [ "type", "daysBefore" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "ledger_bundles_anchor_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_abuse_flagged" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_abuse_suspended" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] } }, "required": [ "type", "thresholdPercent" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_monitor_check_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false } ] }, "channels": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "email" }, "addresses": { "minItems": 1, "type": "array", "items": { "type": "string", "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", "addresses" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "webhook" }, "webhookId": { "type": "string", "minLength": 1 } }, "required": [ "kind", "webhookId" ], "additionalProperties": false } ] } }, "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_demo_default", "type": "quota_threshold", "label": "80% quota", "enabled": true, "config": { "type": "quota_threshold", "thresholdPercent": 80, "quotaKind": "runs" }, "channels": [], "lastFiredAt": null, "firedCount": 0, "createdAt": "2026-05-22T12:00:00.000Z", "updatedAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/alerts.create": { "post": { "operationId": "alerts_create", "summary": "Create a new alert rule.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "type": { "type": "string", "enum": [ "quota_threshold", "pack_balance_low", "payment_failed", "auto_topup_succeeded", "auto_topup_failed", "auto_topup_cap_hit", "hash_chain_mismatch", "webhook_delivery_failing", "notarian_anchor_failed", "lens_hit", "scheduled_for_deletion", "admin_read", "member_role_change", "key_issued", "key_revoked", "tools_abuse_flagged", "tools_abuse_suspended", "tools_quota_threshold", "tools_monitor_check_failing", "tools_tls_vantages_disagree", "mandate_expiring", "ledger_bundles_anchor_failed", "attestor_abuse_flagged", "attestor_abuse_suspended", "attestor_quota_threshold", "attestor_monitor_check_failing" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "config": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] }, "quotaKind": { "type": "string", "enum": [ "runs", "number-one" ] } }, "required": [ "type", "thresholdPercent", "quotaKind" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "pack_balance_low" }, "thresholdRuns": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "packKind": { "type": "string", "enum": [ "runs", "number-one" ] } }, "required": [ "type", "thresholdRuns", "packKind" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "payment_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_succeeded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_cap_hit" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "hash_chain_mismatch" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "webhook_delivery_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "notarian_anchor_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "lens_hit" }, "lensId": { "type": "string", "minLength": 1 } }, "required": [ "type", "lensId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "scheduled_for_deletion" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "admin_read" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "member_role_change" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "key_issued" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "key_revoked" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_abuse_flagged" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_abuse_suspended" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] } }, "required": [ "type", "thresholdPercent" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_monitor_check_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_tls_vantages_disagree" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "mandate_expiring" }, "daysBefore": { "anyOf": [ { "type": "number", "const": 1 }, { "type": "number", "const": 3 }, { "type": "number", "const": 7 }, { "type": "number", "const": 14 }, { "type": "number", "const": 30 } ] } }, "required": [ "type", "daysBefore" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "ledger_bundles_anchor_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_abuse_flagged" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_abuse_suspended" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] } }, "required": [ "type", "thresholdPercent" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_monitor_check_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false } ] }, "channels": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "email" }, "addresses": { "minItems": 1, "type": "array", "items": { "type": "string", "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", "addresses" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "webhook" }, "webhookId": { "type": "string", "minLength": 1 } }, "required": [ "kind", "webhookId" ], "additionalProperties": false } ] } } }, "required": [ "workspaceId", "type", "label", "config", "channels" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Create alert.", "value": { "workspaceId": "ws_demo_default", "type": "quota_threshold", "label": "80% quota", "config": { "type": "quota_threshold", "thresholdPercent": 80, "quotaKind": "runs" }, "channels": [ { "kind": "email", "addresses": [ "ops@example.com" ] } ] } } } } } }, "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "type": { "type": "string" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "enabled": { "type": "boolean" }, "config": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] }, "quotaKind": { "type": "string", "enum": [ "runs", "number-one" ] } }, "required": [ "type", "thresholdPercent", "quotaKind" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "pack_balance_low" }, "thresholdRuns": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "packKind": { "type": "string", "enum": [ "runs", "number-one" ] } }, "required": [ "type", "thresholdRuns", "packKind" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "payment_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_succeeded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_cap_hit" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "hash_chain_mismatch" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "webhook_delivery_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "notarian_anchor_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "lens_hit" }, "lensId": { "type": "string", "minLength": 1 } }, "required": [ "type", "lensId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "scheduled_for_deletion" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "admin_read" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "member_role_change" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "key_issued" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "key_revoked" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_abuse_flagged" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_abuse_suspended" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] } }, "required": [ "type", "thresholdPercent" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_monitor_check_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_tls_vantages_disagree" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "mandate_expiring" }, "daysBefore": { "anyOf": [ { "type": "number", "const": 1 }, { "type": "number", "const": 3 }, { "type": "number", "const": 7 }, { "type": "number", "const": 14 }, { "type": "number", "const": 30 } ] } }, "required": [ "type", "daysBefore" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "ledger_bundles_anchor_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_abuse_flagged" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_abuse_suspended" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] } }, "required": [ "type", "thresholdPercent" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_monitor_check_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false } ] }, "channels": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "email" }, "addresses": { "minItems": 1, "type": "array", "items": { "type": "string", "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", "addresses" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "webhook" }, "webhookId": { "type": "string", "minLength": 1 } }, "required": [ "kind", "webhookId" ], "additionalProperties": false } ] } }, "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_demo_default", "type": "quota_threshold", "label": "80% quota", "enabled": true, "config": { "type": "quota_threshold", "thresholdPercent": 80, "quotaKind": "runs" }, "channels": [ { "kind": "email", "addresses": [ "ops@example.com" ] } ], "lastFiredAt": null, "firedCount": 0, "createdAt": "2026-05-22T12:00:00.000Z", "updatedAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "alert.created", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/alerts.update": { "post": { "operationId": "alerts_update", "summary": "Update an alert's label / config / channels / enabled flag.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "alertId": { "type": "string", "pattern": "^alert_[0-9A-Z]{20,}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "enabled": { "type": "boolean" }, "config": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] }, "quotaKind": { "type": "string", "enum": [ "runs", "number-one" ] } }, "required": [ "type", "thresholdPercent", "quotaKind" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "pack_balance_low" }, "thresholdRuns": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "packKind": { "type": "string", "enum": [ "runs", "number-one" ] } }, "required": [ "type", "thresholdRuns", "packKind" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "payment_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_succeeded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_cap_hit" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "hash_chain_mismatch" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "webhook_delivery_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "notarian_anchor_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "lens_hit" }, "lensId": { "type": "string", "minLength": 1 } }, "required": [ "type", "lensId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "scheduled_for_deletion" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "admin_read" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "member_role_change" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "key_issued" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "key_revoked" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_abuse_flagged" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_abuse_suspended" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] } }, "required": [ "type", "thresholdPercent" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_monitor_check_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_tls_vantages_disagree" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "mandate_expiring" }, "daysBefore": { "anyOf": [ { "type": "number", "const": 1 }, { "type": "number", "const": 3 }, { "type": "number", "const": 7 }, { "type": "number", "const": 14 }, { "type": "number", "const": 30 } ] } }, "required": [ "type", "daysBefore" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "ledger_bundles_anchor_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_abuse_flagged" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_abuse_suspended" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] } }, "required": [ "type", "thresholdPercent" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_monitor_check_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false } ] }, "channels": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "email" }, "addresses": { "minItems": 1, "type": "array", "items": { "type": "string", "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", "addresses" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "webhook" }, "webhookId": { "type": "string", "minLength": 1 } }, "required": [ "kind", "webhookId" ], "additionalProperties": false } ] } } }, "required": [ "workspaceId", "alertId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Update alert.", "value": { "workspaceId": "ws_demo_default", "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "type": { "type": "string" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "enabled": { "type": "boolean" }, "config": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] }, "quotaKind": { "type": "string", "enum": [ "runs", "number-one" ] } }, "required": [ "type", "thresholdPercent", "quotaKind" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "pack_balance_low" }, "thresholdRuns": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "packKind": { "type": "string", "enum": [ "runs", "number-one" ] } }, "required": [ "type", "thresholdRuns", "packKind" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "payment_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_succeeded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_cap_hit" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "hash_chain_mismatch" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "webhook_delivery_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "notarian_anchor_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "lens_hit" }, "lensId": { "type": "string", "minLength": 1 } }, "required": [ "type", "lensId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "scheduled_for_deletion" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "admin_read" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "member_role_change" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "key_issued" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "key_revoked" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_abuse_flagged" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_abuse_suspended" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] } }, "required": [ "type", "thresholdPercent" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_monitor_check_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_tls_vantages_disagree" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "mandate_expiring" }, "daysBefore": { "anyOf": [ { "type": "number", "const": 1 }, { "type": "number", "const": 3 }, { "type": "number", "const": 7 }, { "type": "number", "const": 14 }, { "type": "number", "const": 30 } ] } }, "required": [ "type", "daysBefore" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "ledger_bundles_anchor_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_abuse_flagged" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_abuse_suspended" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] } }, "required": [ "type", "thresholdPercent" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_monitor_check_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false } ] }, "channels": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "email" }, "addresses": { "minItems": 1, "type": "array", "items": { "type": "string", "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", "addresses" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "webhook" }, "webhookId": { "type": "string", "minLength": 1 } }, "required": [ "kind", "webhookId" ], "additionalProperties": false } ] } }, "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_demo_default", "type": "quota_threshold", "label": "Renamed", "enabled": true, "config": {}, "channels": [], "lastFiredAt": null, "firedCount": 0, "createdAt": "2026-05-22T12:00:00.000Z", "updatedAt": "2026-05-22T12:05:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "alert.updated", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/alerts.delete": { "post": { "operationId": "alerts_delete", "summary": "Delete an alert rule.", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "alert.deleted", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/alerts.enable": { "post": { "operationId": "alerts_enable", "summary": "Enable an alert rule.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "alertId": { "type": "string", "pattern": "^alert_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId", "alertId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Enable.", "value": { "workspaceId": "ws_demo_default", "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "type": { "type": "string" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "enabled": { "type": "boolean" }, "config": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] }, "quotaKind": { "type": "string", "enum": [ "runs", "number-one" ] } }, "required": [ "type", "thresholdPercent", "quotaKind" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "pack_balance_low" }, "thresholdRuns": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "packKind": { "type": "string", "enum": [ "runs", "number-one" ] } }, "required": [ "type", "thresholdRuns", "packKind" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "payment_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_succeeded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_cap_hit" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "hash_chain_mismatch" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "webhook_delivery_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "notarian_anchor_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "lens_hit" }, "lensId": { "type": "string", "minLength": 1 } }, "required": [ "type", "lensId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "scheduled_for_deletion" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "admin_read" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "member_role_change" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "key_issued" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "key_revoked" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_abuse_flagged" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_abuse_suspended" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] } }, "required": [ "type", "thresholdPercent" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_monitor_check_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_tls_vantages_disagree" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "mandate_expiring" }, "daysBefore": { "anyOf": [ { "type": "number", "const": 1 }, { "type": "number", "const": 3 }, { "type": "number", "const": 7 }, { "type": "number", "const": 14 }, { "type": "number", "const": 30 } ] } }, "required": [ "type", "daysBefore" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "ledger_bundles_anchor_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_abuse_flagged" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_abuse_suspended" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] } }, "required": [ "type", "thresholdPercent" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_monitor_check_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false } ] }, "channels": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "email" }, "addresses": { "minItems": 1, "type": "array", "items": { "type": "string", "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", "addresses" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "webhook" }, "webhookId": { "type": "string", "minLength": 1 } }, "required": [ "kind", "webhookId" ], "additionalProperties": false } ] } }, "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_demo_default", "type": "quota_threshold", "label": "Quota", "enabled": true, "config": {}, "channels": [], "lastFiredAt": null, "firedCount": 0, "createdAt": "2026-05-22T12:00:00.000Z", "updatedAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "alert.updated", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/alerts.disable": { "post": { "operationId": "alerts_disable", "summary": "Disable an alert rule without deleting it.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "alertId": { "type": "string", "pattern": "^alert_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId", "alertId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Disable.", "value": { "workspaceId": "ws_demo_default", "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "type": { "type": "string" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "enabled": { "type": "boolean" }, "config": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] }, "quotaKind": { "type": "string", "enum": [ "runs", "number-one" ] } }, "required": [ "type", "thresholdPercent", "quotaKind" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "pack_balance_low" }, "thresholdRuns": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "packKind": { "type": "string", "enum": [ "runs", "number-one" ] } }, "required": [ "type", "thresholdRuns", "packKind" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "payment_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_succeeded" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "auto_topup_cap_hit" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "hash_chain_mismatch" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "webhook_delivery_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "notarian_anchor_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "lens_hit" }, "lensId": { "type": "string", "minLength": 1 } }, "required": [ "type", "lensId" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "scheduled_for_deletion" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "admin_read" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "member_role_change" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "key_issued" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "key_revoked" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_abuse_flagged" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_abuse_suspended" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] } }, "required": [ "type", "thresholdPercent" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_monitor_check_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "tools_tls_vantages_disagree" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "mandate_expiring" }, "daysBefore": { "anyOf": [ { "type": "number", "const": 1 }, { "type": "number", "const": 3 }, { "type": "number", "const": 7 }, { "type": "number", "const": 14 }, { "type": "number", "const": 30 } ] } }, "required": [ "type", "daysBefore" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "ledger_bundles_anchor_failed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_abuse_flagged" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_abuse_suspended" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_quota_threshold" }, "thresholdPercent": { "anyOf": [ { "type": "number", "const": 50 }, { "type": "number", "const": 75 }, { "type": "number", "const": 80 }, { "type": "number", "const": 90 }, { "type": "number", "const": 95 }, { "type": "number", "const": 100 } ] } }, "required": [ "type", "thresholdPercent" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "attestor_monitor_check_failing" }, "consecutiveFailures": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "windowMinutes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "type", "consecutiveFailures", "windowMinutes" ], "additionalProperties": false } ] }, "channels": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "email" }, "addresses": { "minItems": 1, "type": "array", "items": { "type": "string", "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", "addresses" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "webhook" }, "webhookId": { "type": "string", "minLength": 1 } }, "required": [ "kind", "webhookId" ], "additionalProperties": false } ] } }, "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_demo_default", "type": "quota_threshold", "label": "Quota", "enabled": false, "config": {}, "channels": [], "lastFiredAt": null, "firedCount": 0, "createdAt": "2026-05-22T12:00:00.000Z", "updatedAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "alert.updated", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/alerts.test-fire": { "post": { "operationId": "alerts_test-fire", "summary": "Fire a synthetic test of an alert to verify channels.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "alertId": { "type": "string", "pattern": "^alert_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId", "alertId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Test fire.", "value": { "workspaceId": "ws_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/alerts.kinds.list": { "post": { "operationId": "alerts_kinds_list", "summary": "List all supported alert kinds + their config shapes + severity classifications.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/alerts.history.list": { "post": { "operationId": "alerts_history_list", "summary": "List historical firings for a given alert rule.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/exports.list": { "post": { "operationId": "exports_list", "summary": "List exports for a workspace.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "status": { "type": "string", "enum": [ "queued", "running", "ready", "failed", "expired" ] }, "kind": { "type": "string", "enum": [ "audit-log", "tools-receipts", "attestor-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_demo_default" } } } } } }, "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "kind": { "type": "string", "enum": [ "audit-log", "tools-receipts", "attestor-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" }, "schemaVersion": { "type": "string" }, "errorMessage": { "type": "string" }, "anchorProof": { "type": "object", "properties": { "superRoot": { "type": "string" }, "inclusionProof": { "type": "array", "items": { "type": "object", "properties": { "sibling": { "type": "string" }, "position": { "type": "string", "enum": [ "left", "right" ] } }, "required": [ "sibling", "position" ], "additionalProperties": false } }, "calendars": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string", "enum": [ "pending", "anchored", "failed" ] }, "anchoredAt": { "type": "string" }, "bitcoinBlockHeight": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "bitcoinBlockHash": { "type": [ "string", "null" ] } }, "required": [ "superRoot", "inclusionProof", "calendars", "state", "anchoredAt", "bitcoinBlockHeight", "bitcoinBlockHash" ], "additionalProperties": false } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/exports.get": { "post": { "operationId": "exports_get", "summary": "Get a single export's status + metadata.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "exportId": { "type": "string" } }, "required": [ "workspaceId", "exportId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read export status.", "value": { "workspaceId": "ws_demo_default", "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "kind": { "type": "string", "enum": [ "audit-log", "tools-receipts", "attestor-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" }, "schemaVersion": { "type": "string" }, "errorMessage": { "type": "string" }, "anchorProof": { "type": "object", "properties": { "superRoot": { "type": "string" }, "inclusionProof": { "type": "array", "items": { "type": "object", "properties": { "sibling": { "type": "string" }, "position": { "type": "string", "enum": [ "left", "right" ] } }, "required": [ "sibling", "position" ], "additionalProperties": false } }, "calendars": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string", "enum": [ "pending", "anchored", "failed" ] }, "anchoredAt": { "type": "string" }, "bitcoinBlockHeight": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "bitcoinBlockHash": { "type": [ "string", "null" ] } }, "required": [ "superRoot", "inclusionProof", "calendars", "state", "anchoredAt", "bitcoinBlockHeight", "bitcoinBlockHash" ], "additionalProperties": false } }, "required": [ "exportId", "workspaceId", "kind", "status", "format", "requestedAt", "readyAt", "expiresAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read export status.", "value": { "exportId": "exp_abc", "workspaceId": "ws_demo_default", "kind": "audit-log", "status": "ready", "format": "json", "requestedAt": "2026-05-22T12:00:00.000Z", "readyAt": "2026-05-22T12:10:00.000Z", "expiresAt": "2026-05-29T12:10:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/exports.request": { "post": { "operationId": "exports_request", "summary": "Request a new compliance export. Returns the export id; status polls reveal readiness.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "kind": { "type": "string", "enum": [ "audit-log", "tools-receipts", "attestor-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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "expensive", "x-agined-audit-kind": "export.requested", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "exportId": { "type": "string" } }, "required": [ "workspaceId", "exportId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Get signed download URL.", "value": { "workspaceId": "ws_demo_default", "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.agined.com/exports/abc", "expiresAt": "2026-05-22T13:00:00.000Z", "sha256": "abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "export.completed", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/exports.verify": { "post": { "operationId": "exports_verify", "summary": "Verify an export's Ed25519 signature + OTS Bitcoin proof. Offline-verifiable.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab", "signature": "...", "signingKeyId": "agined-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" } }, "anchor": { "type": "object", "properties": { "checked": { "type": "string", "const": "inclusion_only" }, "inclusionValid": { "type": "boolean" }, "superRoot": { "type": "string" }, "state": { "anyOf": [ { "type": "string", "enum": [ "pending", "anchored", "failed" ] }, { "type": "null" } ] }, "bitcoinBlockHeight": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "reason": { "type": "string" } }, "required": [ "checked", "inclusionValid" ], "additionalProperties": false } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/exports.attestor.receipt-bundle.request": { "post": { "operationId": "exports_attestor_receipt-bundle_request", "summary": "Request a portable Attestor-receipt bundle — JSON manifest + receipt files + public key JWK + verify README. Verifiable with @attestor/verify.", "x-agined-description-key": "actions.exports.attestor.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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 Attestor receipts.", "value": { "workspaceId": "ws_demo_default", "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 Attestor receipts.", "value": { "exportId": "exp_atst_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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "expensive", "x-agined-audit-kind": "export.requested", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "expensive", "x-agined-audit-kind": "export.requested", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "expensive", "x-agined-audit-kind": "export.requested", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/exports.kinds.list": { "post": { "operationId": "exports_kinds_list", "summary": "List the supported export kinds + their output formats + retention.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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", "tools-receipts", "attestor-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/exports.delete": { "post": { "operationId": "exports_delete", "summary": "Delete a completed export (frees R2 storage immediately).", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "exportId": { "type": "string" } }, "required": [ "workspaceId", "exportId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete an export.", "value": { "workspaceId": "ws_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/retention.policy.get": { "post": { "operationId": "retention_policy_get", "summary": "Get the active retention policy for a workspace.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read retention policy.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "retentionDays": 365, "isCustom": false, "appliedAt": "2026-01-01T00:00:00.000Z", "appliedBy": "plan" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/retention.policy.update": { "post": { "operationId": "retention_policy_update", "summary": "Update workspace retention days (within tier limits).", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "retentionDays": { "type": "integer", "minimum": 7, "maximum": 1825 } }, "required": [ "workspaceId", "retentionDays" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Extend retention via paid extension.", "value": { "workspaceId": "ws_demo_default", "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "retentionDays": 730, "isCustom": true, "appliedAt": "2026-05-22T12:00:00.000Z", "appliedBy": "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "mandate", "x-agined-rate-class": "default", "x-agined-audit-kind": "retention.updated", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "bucketSizeDays": { "default": 7, "type": "integer", "minimum": 1, "maximum": 30 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read age distribution.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "expensive", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "limit": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Preview upcoming purge.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/retention.purge-history.list": { "post": { "operationId": "retention_purge-history_list", "summary": "List historical purge events with verification status.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default" } } } } } }, "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": { "id": { "type": "string" }, "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 }, "cutoffAge": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "effectiveSource": { "anyOf": [ { "type": "string", "enum": [ "tier_floor", "paid_extension" ] }, { "type": "null" } ] }, "verificationState": { "type": "string", "enum": [ "verified", "awaiting_anchor", "unanchored" ] } }, "required": [ "id", "purgedAt", "recordsPurged", "cutoffAge", "effectiveSource", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/retention.extension.subscribe": { "post": { "operationId": "retention_extension_subscribe", "summary": "Subscribe to the paid retention extension at the per-tier rate.", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "retention.updated", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/retention.extension.get": { "post": { "operationId": "retention_extension_get", "summary": "Get the current retention extension subscription (if any).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Workspace has no extension subscription.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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": "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/retention.extension.update": { "post": { "operationId": "retention_extension_update", "summary": "Update the active retention extension (change duration).", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "extendedToDays": { "type": "integer", "minimum": 7, "maximum": 1825 } }, "required": [ "workspaceId", "extendedToDays" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Bump to 5-year retention.", "value": { "workspaceId": "ws_demo_default", "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "retention.updated", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/retention.extension.cancel": { "post": { "operationId": "retention_extension_cancel", "summary": "Cancel the retention extension at the end of the current billing period.", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Cancel at period end.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "extendedToDays": 1825, "monthlyCostUsdMinor": 2400, "perGbMonthlyCostUsdMinor": 1000, "storageGbBilled": 2.4, "startedAt": "2026-05-22T12:00:00.000Z", "canceledAt": "2026-05-22T12:00:00.000Z", "effectiveUntil": "2026-06-22T00:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "retention.updated", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Suggested upgrade.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/retention.audit.list": { "post": { "operationId": "retention_audit_list", "summary": "List retention-policy audit events (changes, purges, extensions).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read retention audit.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/audit.workspace.list": { "post": { "operationId": "audit_workspace_list", "summary": "List audit log entries for a workspace.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default" } } } } } }, "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-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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" }, "promptExcerpt": { "type": "string", "maxLength": 200 }, "confirmationTokenId": { "type": "string" }, "governance": { "type": "object", "properties": { "refusedBy": { "type": "string" }, "charterEnforced": { "type": "boolean" }, "charterSha256": { "type": "string" }, "conscienceEnforced": { "type": "boolean" }, "consciencePolicyVersionId": { "type": "string" }, "cordonPosture": { "type": "string", "enum": [ "off", "flag", "block" ] }, "cordonFlaggedRuleId": { "type": "string" } }, "additionalProperties": false }, "delegationChainDepth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outcome": { "type": "string", "enum": [ "success", "denied", "failed", "partial" ] }, "inputHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "storageTier": { "type": "string", "enum": [ "r2_standard", "r2_ia", "glacier_deep_archive" ] } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "expensive", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/audit.workspace.get": { "post": { "operationId": "audit_workspace_get", "summary": "Get a specific audit entry by id.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "entryId": { "type": "string", "pattern": "^aud_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, "required": [ "workspaceId", "entryId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Fetch a single entry.", "value": { "workspaceId": "ws_demo_default", "entryId": "aud_9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } } } }, "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-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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" }, "promptExcerpt": { "type": "string", "maxLength": 200 }, "confirmationTokenId": { "type": "string" }, "governance": { "type": "object", "properties": { "refusedBy": { "type": "string" }, "charterEnforced": { "type": "boolean" }, "charterSha256": { "type": "string" }, "conscienceEnforced": { "type": "boolean" }, "consciencePolicyVersionId": { "type": "string" }, "cordonPosture": { "type": "string", "enum": [ "off", "flag", "block" ] }, "cordonFlaggedRuleId": { "type": "string" } }, "additionalProperties": false }, "delegationChainDepth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outcome": { "type": "string", "enum": [ "success", "denied", "failed", "partial" ] }, "inputHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "storageTier": { "type": "string", "enum": [ "r2_standard", "r2_ia", "glacier_deep_archive" ] } }, "required": [ "id", "workspaceId", "timestamp", "kind", "outcome" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Fetch a single entry.", "value": { "id": "aud_9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f", "workspaceId": "ws_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/audit.workspace.search": { "post": { "operationId": "audit_workspace_search", "summary": "Full-text search across a workspace's audit log.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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" }, "promptExcerpt": { "type": "string", "maxLength": 200 }, "confirmationTokenId": { "type": "string" }, "governance": { "type": "object", "properties": { "refusedBy": { "type": "string" }, "charterEnforced": { "type": "boolean" }, "charterSha256": { "type": "string" }, "conscienceEnforced": { "type": "boolean" }, "consciencePolicyVersionId": { "type": "string" }, "cordonPosture": { "type": "string", "enum": [ "off", "flag", "block" ] }, "cordonFlaggedRuleId": { "type": "string" } }, "additionalProperties": false }, "delegationChainDepth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outcome": { "type": "string", "enum": [ "success", "denied", "failed", "partial" ] }, "inputHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "storageTier": { "type": "string", "enum": [ "r2_standard", "r2_ia", "glacier_deep_archive" ] } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "expensive", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "entryId": { "type": "string", "pattern": "^aud_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "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_demo_default", "entryId": "aud_9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f", "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))$" }, "shareId": { "type": "string" } }, "required": [ "shareUrl", "expiresAt", "shareId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Share with auditor.", "value": { "shareUrl": "https://agined.com/audit/share/abc", "expiresAt": "2026-05-23T12:00:00.000Z", "shareId": "9f2c1a7b3e4d5f60" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "admin.action", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/audit.workspace.shares.list": { "post": { "operationId": "audit_workspace_shares_list", "summary": "List the audit share links minted for this workspace, with their expiry and revocation state.", "x-agined-description-key": "actions.audit.workspace.shares.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "includeInactive": { "default": false, "type": "boolean" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "See what is still shared.", "value": { "workspaceId": "ws_demo_default", "includeInactive": false } } } } } }, "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" }, "tokenPrefix": { "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))$" }, "createdBy": { "type": [ "string", "null" ] }, "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" } ] }, "active": { "type": "boolean" } }, "required": [ "shareId", "tokenPrefix", "entryId", "note", "createdAt", "createdBy", "expiresAt", "revokedAt", "active" ], "additionalProperties": false } } }, "required": [ "shares" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "See what is still shared.", "value": { "shares": [ { "shareId": "9f2c1a7b3e4d5f60", "tokenPrefix": "abc12345", "entryId": "aud_9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f", "note": "Q3 audit — Foo & Co LLP", "createdAt": "2026-05-22T12:00:00.000Z", "createdBy": "acct_demo", "expiresAt": "2026-05-23T12:00:00.000Z", "revokedAt": null, "active": true } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/audit.workspace.share.revoke": { "post": { "operationId": "audit_workspace_share_revoke", "summary": "Revoke an audit share link immediately, before its expiry.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "shareId": { "type": "string", "minLength": 8, "maxLength": 64 } }, "required": [ "workspaceId", "shareId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Kill a leaked share.", "value": { "workspaceId": "ws_demo_default", "shareId": "9f2c1a7b3e4d5f60" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "shareId": { "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" } ] } }, "required": [ "shareId", "revoked", "revokedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Kill a leaked share.", "value": { "shareId": "9f2c1a7b3e4d5f60", "revoked": true, "revokedAt": "2026-05-22T18: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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "admin.action", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/audit.custody.list": { "post": { "operationId": "audit_custody_list", "summary": "List custody chain entries for a workspace (hash-chained, Ed25519-signed).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default" } } } } } }, "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_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "seq": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sourceAuditId": { "type": "string" }, "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))$" }, "action": { "type": "string" }, "actorDid": { "type": [ "string", "null" ] }, "payload": { "anyOf": [ {}, { "type": "null" } ] }, "prevHash": { "anyOf": [ { "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" } ] }, "rowHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "recordedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?: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" }, "signingKeyId": { "type": "string" } }, "required": [ "id", "seq", "sourceAuditId", "timestamp", "action", "actorDid", "payload", "prevHash", "rowHash", "recordedAt" ], "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "expensive", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/audit.custody.get": { "post": { "operationId": "audit_custody_get", "summary": "Get a custody entry by id (hash-chained via prevHash→entryHash; per-entry signature is optional — the Ed25519 seal covers a range, not each entry).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "entryId": { "type": "string", "pattern": "^cust_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, "required": [ "workspaceId", "entryId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Fetch a custody entry.", "value": { "workspaceId": "ws_demo_default", "entryId": "cust_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" } } } } } }, "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_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "seq": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "sourceAuditId": { "type": "string" }, "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))$" }, "action": { "type": "string" }, "actorDid": { "type": [ "string", "null" ] }, "payload": { "anyOf": [ {}, { "type": "null" } ] }, "prevHash": { "anyOf": [ { "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" } ] }, "rowHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "recordedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?: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" }, "signingKeyId": { "type": "string" } }, "required": [ "id", "seq", "sourceAuditId", "timestamp", "action", "actorDid", "payload", "prevHash", "rowHash", "recordedAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Fetch a custody entry.", "value": { "id": "cust_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "workspaceId": "ws_demo_default", "seq": 42, "sourceAuditId": "aud_9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f", "action": "workspace.settings.update", "actorDid": "did:web:agined.com:accounts:acc_demo00000000000000000000", "payload": { "field": "retentionDays", "from": 30, "to": 90 }, "rowHash": "1111567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "recordedAt": "2026-05-22T12:00:00.000Z", "timestamp": "2026-05-22T12:00:00.000Z", "prevHash": "0000000000000000000000000000000000000000000000000000000000000000", "entryHash": "abcd567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "signature": "...", "signingKeyId": "tools-2026-q2-enam" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/audit.tops.list": { "post": { "operationId": "audit_tops_list", "summary": "List Tops feed entries (hash-chained per entry; authenticity is the periodically Ed25519-signed + OTS Bitcoin-anchored SEAL ROOT — per-entry signature is null until its seal exists).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "kinds": { "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))$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read Tops feed.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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": "^[0-9]+$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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", "null" ] }, "signingKeyId": { "type": [ "string", "null" ] }, "otsProof": { "type": "string" }, "storageTier": { "type": "string", "enum": [ "r2_standard", "r2_ia", "glacier_deep_archive" ] } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "expensive", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/audit.tops.verify": { "post": { "operationId": "audit_tops_verify", "summary": "Verify the hash chain of this workspace's Tops entries.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "fromEntryId": { "type": "string", "pattern": "^[0-9]+$" }, "toEntryId": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify a Tops range end-to-end.", "value": { "workspaceId": "ws_demo_default", "fromEntryId": "1024", "toEntryId": "2048" } } } } } }, "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" }, "entriesChecked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "truncated": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "chainValid", "signaturesValid", "otsValid", "entriesChecked", "truncated", "errors" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify a Tops range end-to-end.", "value": { "chainValid": true, "signaturesValid": true, "otsValid": true, "errors": [], "entriesChecked": 1284, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "expensive", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/audit.shadow-sessions.list": { "post": { "operationId": "audit_shadow-sessions_list", "summary": "List Agined-staff shadow-mode sessions on a workspace.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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 Agined-staff shadow sessions.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "accountId": { "type": "string" }, "operatorDid": { "type": [ "string", "null" ] }, "origin": { "type": "string", "const": "operator_shadow" }, "costCenterId": { "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": { "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" } ] }, "revokeReason": { "type": [ "string", "null" ] }, "ipAddress": { "type": [ "string", "null" ] }, "userAgent": { "type": [ "string", "null" ] } }, "required": [ "sessionId", "workspaceId", "accountId", "operatorDid", "origin", "costCenterId", "createdAt", "expiresAt", "lastUsedAt", "revokedAt", "revokeReason", "ipAddress", "userAgent" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "sessions", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/audit.shadow-sessions.get": { "post": { "operationId": "audit_shadow-sessions_get", "summary": "Get full details + action feed of a shadow-mode session.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "sessionId": { "type": "string" } }, "required": [ "workspaceId", "sessionId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Inspect a shadow session.", "value": { "workspaceId": "ws_demo_default", "sessionId": "shadow_abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "session": { "type": "object", "properties": { "sessionId": { "type": "string" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "accountId": { "type": "string" }, "operatorDid": { "type": [ "string", "null" ] }, "origin": { "type": "string", "const": "operator_shadow" }, "costCenterId": { "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": { "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" } ] }, "revokeReason": { "type": [ "string", "null" ] }, "ipAddress": { "type": [ "string", "null" ] }, "userAgent": { "type": [ "string", "null" ] } }, "required": [ "sessionId", "workspaceId", "accountId", "operatorDid", "origin", "costCenterId", "createdAt", "expiresAt", "lastUsedAt", "revokedAt", "revokeReason", "ipAddress", "userAgent" ], "additionalProperties": {} }, "actions": { "type": "array", "items": {} } }, "required": [ "session", "actions" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Inspect a shadow session.", "value": { "session": { "sessionId": "shadow_abc", "workspaceId": "ws_demo_default", "accountId": "acct_demo00000000000000000000", "operatorDid": "did:web:agined.com:operators:ops_demo", "origin": "support-console", "costCenterId": null, "createdAt": "2026-05-22T12:00:00.000Z", "expiresAt": "2026-05-22T14:00:00.000Z", "lastUsedAt": "2026-05-22T12:31:00.000Z", "revokedAt": null, "revokeReason": null, "ipAddress": "203.0.113.7", "userAgent": "Mozilla/5.0" }, "actions": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/audit.aggregate": { "post": { "operationId": "audit_aggregate", "summary": "Group + count audit entries by a dimension (kind, transport, outcome, agentClientId).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "expensive", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/audit.kinds.list": { "post": { "operationId": "audit_kinds_list", "summary": "List all audit-kind discriminator values supported by the platform.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "source": { "type": "string", "enum": [ "all", "tops", "audit_log" ] }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "expensive", "x-agined-audit-kind": "export.requested", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default" } } } } } }, "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-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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" }, "promptExcerpt": { "type": "string", "maxLength": 200 }, "confirmationTokenId": { "type": "string" }, "governance": { "type": "object", "properties": { "refusedBy": { "type": "string" }, "charterEnforced": { "type": "boolean" }, "charterSha256": { "type": "string" }, "conscienceEnforced": { "type": "boolean" }, "consciencePolicyVersionId": { "type": "string" }, "cordonPosture": { "type": "string", "enum": [ "off", "flag", "block" ] }, "cordonFlaggedRuleId": { "type": "string" } }, "additionalProperties": false }, "delegationChainDepth": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outcome": { "type": "string", "enum": [ "success", "denied", "failed", "partial" ] }, "inputHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "storageTier": { "type": "string", "enum": [ "r2_standard", "r2_ia", "glacier_deep_archive" ] } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-…" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "mandate", "x-agined-rate-class": "default", "x-agined-audit-kind": "audit.stream.configured", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/audit.stream.delete": { "post": { "operationId": "audit_stream_delete", "summary": "Delete an audit-stream destination by id (workspace-scoped).", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "audit.stream.configured", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/tops.config.get": { "post": { "operationId": "tops_config_get", "summary": "Get the Tops config for a specific scope (org, workspace, or actor).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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_demo_default" } } } } } }, "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": [ "ingest", "export", "key_issue", "admin_read", "chat_query", "webhook_delivered", "notary_anchor", "ledger_bundles_anchor", "cron_run", "tops_config_change", "spot_observe", "spot_decide", "spot_skip", "spot_state", "spot_drift" ] } }, "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_demo_default", "enabled": true, "kinds": [ "admin_read", "key_issue" ], "environments": [ "production" ], "samplingPercent": 100, "detailLevel": "safe", "updatedAt": "2026-05-22T12:00:00.000Z", "updatedBy": "acct_demo00000000000000000000" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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", "enum": [ "ingest", "export", "key_issue", "admin_read", "chat_query", "webhook_delivered", "notary_anchor", "ledger_bundles_anchor", "cron_run", "tops_config_change", "spot_observe", "spot_decide", "spot_skip", "spot_state", "spot_drift" ] } }, "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_demo_default", "enabled": true, "kinds": [ "admin_read", "key_issue" ], "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": [ "ingest", "export", "key_issue", "admin_read", "chat_query", "webhook_delivered", "notary_anchor", "ledger_bundles_anchor", "cron_run", "tops_config_change", "spot_observe", "spot_decide", "spot_skip", "spot_state", "spot_drift" ] } }, "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_demo_default", "enabled": true, "kinds": [ "admin_read", "key_issue" ], "environments": [ "production" ], "samplingPercent": 100, "detailLevel": "extended", "updatedAt": "2026-05-22T12:00:00.000Z", "updatedBy": "acct_demo00000000000000000000" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "admin.action", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/tops.config.delete": { "post": { "operationId": "tops_config_delete", "summary": "Delete a scope-level Tops config (scope reverts to parent inheritance).", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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_demo_default" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "admin.action", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/tops.config.list": { "post": { "operationId": "tops_config_list", "summary": "List Tops configs (all scopes in an org or workspace).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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_[A-Za-z0-9_-]{11,}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "List configs.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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": [ "ingest", "export", "key_issue", "admin_read", "chat_query", "webhook_delivered", "notary_anchor", "ledger_bundles_anchor", "cron_run", "tops_config_change", "spot_observe", "spot_decide", "spot_skip", "spot_state", "spot_drift" ] } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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_[A-Za-z0-9_-]{11,}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default" } } } } } }, "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": [ "ingest", "export", "key_issue", "admin_read", "chat_query", "webhook_delivered", "notary_anchor", "ledger_bundles_anchor", "cron_run", "tops_config_change", "spot_observe", "spot_decide", "spot_skip", "spot_state", "spot_drift" ] } }, "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_demo_default", "enabled": true, "kinds": [ "admin_read" ], "environments": [ "production" ], "samplingPercent": 100, "detailLevel": "safe", "updatedAt": "2026-05-22T12:00:00.000Z", "updatedBy": "acct_demo00000000000000000000" }, "source": "workspace", "inheritedFields": [ "environments" ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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_demo_default", "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": [ "ingest", "export", "key_issue", "admin_read", "chat_query", "webhook_delivered", "notary_anchor", "ledger_bundles_anchor", "cron_run", "tops_config_change", "spot_observe", "spot_decide", "spot_skip", "spot_state", "spot_drift" ] } }, "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_demo_default", "enabled": true, "kinds": [ "ingest", "export", "key_issue", "admin_read", "spot_decide" ], "environments": [ "production" ], "samplingPercent": 100, "detailLevel": "safe", "updatedAt": "2026-05-22T12:00:00.000Z", "updatedBy": "acct_demo00000000000000000000" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "admin.action", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "kinds": { "type": "array", "items": { "type": "string", "enum": [ "ingest", "export", "key_issue", "admin_read", "chat_query", "webhook_delivered", "notary_anchor", "ledger_bundles_anchor", "cron_run", "tops_config_change", "spot_observe", "spot_decide", "spot_skip", "spot_state", "spot_drift" ] } }, "environments": { "type": "array", "items": { "type": "string" } }, "samplingPercent": { "type": "number", "minimum": 0, "maximum": 100 }, "detailLevel": { "type": "string", "enum": [ "safe", "extended", "forensic" ] } }, "required": [ "enabled", "kinds", "environments", "samplingPercent", "detailLevel" ], "additionalProperties": false }, "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": { "enabled": true, "kinds": [ "ingest", "export" ], "environments": [ "production" ], "samplingPercent": 10, "detailLevel": "safe" }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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_[A-Za-z0-9_-]{11,}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "actorId": "actor_demo00000000000000000000", "syntheticEvent": { "kind": "admin_read" } } } } } } }, "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": [ "ingest", "export", "key_issue", "admin_read", "chat_query", "webhook_delivered", "notary_anchor", "ledger_bundles_anchor", "cron_run", "tops_config_change", "spot_observe", "spot_decide", "spot_skip", "spot_state", "spot_drift" ] } }, "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_demo_default", "enabled": true, "kinds": [ "admin_read" ], "environments": [ "production" ], "samplingPercent": 100, "detailLevel": "safe", "updatedAt": "2026-05-22T12:00:00.000Z", "updatedBy": "acct_demo00000000000000000000" }, "wouldRecord": true, "wouldRecordFields": [ "kind", "timestamp" ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/tops.config.change-history.list": { "post": { "operationId": "tops_config_change-history_list", "summary": "List Tops-config change events (audit cross-link).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": { "type": "object", "properties": { "id": { "type": "string" }, "scope": { "type": "string", "enum": [ "org", "workspace", "actor" ] }, "scopeId": { "type": "string" }, "changedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$" }, "change": { "anyOf": [ { "type": "object", "properties": { "op": { "type": "string", "enum": [ "set", "preset.apply", "delete" ] }, "before": { "anyOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean" }, "kinds": { "type": "array", "items": { "type": "string", "enum": [ "ingest", "export", "key_issue", "admin_read", "chat_query", "webhook_delivered", "notary_anchor", "ledger_bundles_anchor", "cron_run", "tops_config_change", "spot_observe", "spot_decide", "spot_skip", "spot_state", "spot_drift" ] } }, "environments": { "type": "array", "items": { "type": "string" } }, "samplingPercent": { "type": "number", "minimum": 0, "maximum": 100 }, "detailLevel": { "type": "string", "enum": [ "safe", "extended", "forensic" ] } }, "required": [ "enabled", "kinds", "environments", "samplingPercent", "detailLevel" ], "additionalProperties": false }, { "type": "null" } ] }, "after": { "anyOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean" }, "kinds": { "type": "array", "items": { "type": "string", "enum": [ "ingest", "export", "key_issue", "admin_read", "chat_query", "webhook_delivered", "notary_anchor", "ledger_bundles_anchor", "cron_run", "tops_config_change", "spot_observe", "spot_decide", "spot_skip", "spot_state", "spot_drift" ] } }, "environments": { "type": "array", "items": { "type": "string" } }, "samplingPercent": { "type": "number", "minimum": 0, "maximum": 100 }, "detailLevel": { "type": "string", "enum": [ "safe", "extended", "forensic" ] } }, "required": [ "enabled", "kinds", "environments", "samplingPercent", "detailLevel" ], "additionalProperties": false }, { "type": "null" } ] }, "detailLevel": { "anyOf": [ { "type": "string", "enum": [ "safe", "extended", "forensic" ] }, { "type": "null" } ] }, "by": { "type": "string" } }, "required": [ "op", "before", "after", "detailLevel", "by" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "scope", "scopeId", "changedAt", "change" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "changes", "nextCursor" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read config change history.", "value": { "changes": [ { "id": "0f4a2b1c-0000-4000-8000-000000000000", "scope": "workspace", "scopeId": "ws_demo_default", "changedAt": "2026-05-22T12:00:00.000Z", "change": { "op": "set", "before": { "enabled": true, "kinds": [ "admin_read" ], "environments": [ "production" ], "samplingPercent": 100, "detailLevel": "safe" }, "after": { "enabled": true, "kinds": [ "admin_read" ], "environments": [ "production" ], "samplingPercent": 100, "detailLevel": "forensic" }, "detailLevel": "forensic", "by": "acct_demo00000000000000000000" } } ], "nextCursor": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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_demo_default" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Audit cross-link helper.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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_demo_default" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/tops.specimen.get": { "post": { "operationId": "tops_specimen_get", "summary": "Read this workspace's public trust page settings. `null` when nothing has ever been published.", "x-agined-description-key": "actions.tops.specimen.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "Nothing published.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "anyOf": [ { "type": "object", "properties": { "handle": { "type": "string" }, "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))$" }, "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": [ "handle", "enabled", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "page" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Nothing published.", "value": { "page": 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/tops.specimen.set": { "post": { "operationId": "tops_specimen_set", "summary": "Claim or rename the workspace's public handle, and turn the page on or off.", "x-agined-description-key": "actions.tops.specimen.set.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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "handle": { "type": "string", "minLength": 2, "maxLength": 40 }, "enabled": { "type": "boolean" } }, "required": [ "handle", "enabled" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Claim the handle without publishing yet.", "value": { "handle": "acme", "enabled": false } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "object", "properties": { "handle": { "type": "string" }, "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))$" }, "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": [ "handle", "enabled", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "page" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Claim the handle without publishing yet.", "value": { "page": { "handle": "acme", "enabled": false, "createdAt": "2026-09-03T00:00:00.000Z", "updatedAt": "2026-09-03T00: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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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_capabilities" ] }, { "OAuth2": [ "settings.edit_capabilities" ] }, { "WorkspaceApiKey": [ "settings.edit_capabilities" ] } ], "x-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_invocation", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/tops.specimen.delete": { "post": { "operationId": "tops_specimen_delete", "summary": "Take the public page down and RELEASE the handle for anyone else to claim.", "x-agined-description-key": "actions.tops.specimen.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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "Unpublish.", "value": {} } } } } }, "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": "Unpublish.", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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_capabilities" ] }, { "OAuth2": [ "settings.edit_capabilities" ] }, { "WorkspaceApiKey": [ "settings.edit_capabilities" ] } ], "x-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_invocation", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/referrals.code.get": { "post": { "operationId": "referrals_code_get", "summary": "Get your active referral code + share URL.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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" }, "shareMessage": { "type": [ "string", "null" ] } }, "required": [ "code", "shareUrl", "qrCodeDataUrl", "shareMessage" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read your referral code.", "value": { "code": "DEMO12", "shareUrl": "https://agined.com/?ref=DEMO12", "qrCodeDataUrl": "data:image/png;base64,...", "shareMessage": 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/referrals.code.regenerate": { "post": { "operationId": "referrals_code_regenerate", "summary": "Regenerate referral code. Old code stops working.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/referrals.share-message.set": { "post": { "operationId": "referrals_share-message_set", "summary": "Set the message shared alongside your referral link.", "x-agined-description-key": "actions.referrals.share-message.set.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string", "maxLength": 1000 } }, "required": [ "message" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Replace your share message.", "value": { "message": "I use Agined to run my agents — sign up with my link." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Replace your share message.", "value": { "message": "I use Agined to run my agents — sign up with my link." } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_invocation", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/referrals.share.record": { "post": { "operationId": "referrals_share_record", "summary": "Record that you shared your referral link, and where.", "x-agined-description-key": "actions.referrals.share.record.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channel": { "type": "string", "enum": [ "url", "email", "qr", "voucher_gift", "x", "linkedin", "whatsapp", "telegram", "slack", "copy", "other" ] } }, "required": [ "channel" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Record a share to Slack.", "value": { "channel": "slack" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "recorded": { "type": "boolean", "const": true }, "channel": { "type": "string", "enum": [ "url", "email", "qr", "voucher_gift", "x", "linkedin", "whatsapp", "telegram", "slack", "copy", "other" ] } }, "required": [ "recorded", "channel" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Record a share to Slack.", "value": { "recorded": true, "channel": "slack" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_invocation", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/referrals.list-sent": { "post": { "operationId": "referrals_list-sent", "summary": "List referrals you have sent.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/referrals.list-received": { "post": { "operationId": "referrals_list-received", "summary": "List referrals where you were the referee.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/referrals.balance.get": { "post": { "operationId": "referrals_balance_get", "summary": "Get your current point balance + lifetime multiplier tier.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/referrals.funnel.get": { "post": { "operationId": "referrals_funnel_get", "summary": "Get conversion funnel analytics (sent → clicked → joined → redeemed).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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 }, "joinRate": { "type": [ "number", "null" ] }, "redeemRate": { "type": [ "number", "null" ] }, "channelBreakdown": { "type": "array", "items": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "url", "email", "qr", "voucher_gift", "x", "linkedin", "whatsapp", "telegram", "slack", "copy", "other" ] }, "sent": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "clicked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "channel", "sent", "clicked" ], "additionalProperties": false } } }, "required": [ "sent", "clicked", "joined", "redeemed", "joinRate", "redeemRate", "channelBreakdown" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read funnel.", "value": { "sent": 50, "clicked": 30, "joined": 12, "redeemed": 8, "joinRate": 0.4, "redeemRate": 0.6667, "channelBreakdown": [ { "channel": "slack", "sent": 30, "clicked": 20 } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/referrals.redeem": { "post": { "operationId": "referrals_redeem", "summary": "Redeem a referral or voucher code.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/referrals.spend": { "post": { "operationId": "referrals_spend", "summary": "Spend points on a reward (run pack, add-on credit, Every.org charity, etc.).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/referrals.spend-products.list": { "post": { "operationId": "referrals_spend-products_list", "summary": "List the products you can redeem points against.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/referrals.ledger.list": { "post": { "operationId": "referrals_ledger_list", "summary": "List point transactions (earned + spent).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/number_one.conversation.create": { "post": { "operationId": "number_one_conversation_create", "summary": "Start a new Number One conversation.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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|sess)_[A-Za-z0-9_-]{8,}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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 }, "preview": { "type": "string" } }, "required": [ "conversationId", "workspaceId", "mode", "startedAt", "lastActivityAt", "messageCount" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Start a new conversation.", "value": { "conversationId": "conv_demo0000000000A", "workspaceId": "ws_demo_default", "mode": "analyst", "title": "Q3 audit review", "startedAt": "2026-05-22T12:00:00.000Z", "lastActivityAt": "2026-05-22T12:00:00.000Z", "messageCount": 0, "preview": "" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/number_one.conversation.list": { "post": { "operationId": "number_one_conversation_list", "summary": "List your conversations (most recent first).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "mode": { "type": "string", "enum": [ "calculator", "analyst", "admin" ] } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List conversations.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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|sess)_[A-Za-z0-9_-]{8,}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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 }, "preview": { "type": "string" } }, "required": [ "conversationId", "workspaceId", "mode", "startedAt", "lastActivityAt", "messageCount" ], "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/number_one.conversation.get": { "post": { "operationId": "number_one_conversation_get", "summary": "Get a conversation's metadata + recent messages.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "conversationId": { "type": "string", "pattern": "^(conv|sess)_[A-Za-z0-9_-]{8,}$" }, "messageLimit": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "workspaceId", "conversationId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read a conversation.", "value": { "workspaceId": "ws_demo_default", "conversationId": "conv_demo0000000000A" } } } } } }, "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|sess)_[A-Za-z0-9_-]{8,}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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 }, "preview": { "type": "string" } }, "required": [ "conversationId", "workspaceId", "mode", "startedAt", "lastActivityAt", "messageCount" ], "additionalProperties": {} }, "messages": { "type": "array", "items": { "type": "object", "properties": { "messageId": { "type": "string", "pattern": "^no_mem_[A-Za-z0-9_-]{8,}$" }, "conversationId": { "type": "string", "pattern": "^(conv|sess)_[A-Za-z0-9_-]{8,}$" }, "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))$" }, "mode": { "type": "string" }, "erased": { "type": "boolean" }, "contentOrigin": { "type": [ "string", "null" ] }, "trace": {} }, "required": [ "messageId", "conversationId", "role", "body", "createdAt" ], "additionalProperties": {} } } }, "required": [ "conversation", "messages" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read a conversation.", "value": { "conversation": { "conversationId": "conv_demo0000000000A", "workspaceId": "ws_demo_default", "mode": "analyst", "title": "Q3 audit review", "startedAt": "2026-05-22T12:00:00.000Z", "lastActivityAt": "2026-05-22T12:00:00.000Z", "messageCount": 0, "preview": "" }, "messages": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "conversationId": { "type": "string", "pattern": "^(conv|sess)_[A-Za-z0-9_-]{8,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "conversationId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete a conversation.", "value": { "workspaceId": "ws_demo_default", "conversationId": "conv_demo0000000000A" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/number_one.message.send": { "post": { "operationId": "number_one_message_send", "summary": "Send a user message in a Number One conversation. Returns the full buffered assistant turn.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "conversationId": { "type": "string", "pattern": "^(conv|sess)_[A-Za-z0-9_-]{8,}$" }, "body": { "type": "string", "minLength": 1, "maxLength": 50000 } }, "required": [ "workspaceId", "conversationId", "body" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Send a message.", "value": { "workspaceId": "ws_demo_default", "conversationId": "conv_demo0000000000A", "body": "What was my Tools usage last week?" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sessionId": { "type": "string", "pattern": "^(conv|sess)_[A-Za-z0-9_-]{8,}$" }, "assistantMessageId": { "anyOf": [ { "type": "string", "pattern": "^no_mem_[A-Za-z0-9_-]{8,}$" }, { "type": "null" } ] }, "decision": { "type": "string", "enum": [ "calculator", "analyst", "admin", "off_limits" ] }, "assistantBody": { "type": "string" }, "contentOrigin": { "type": [ "string", "null" ] }, "marking": {}, "quotaCostUnits": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "classification": {}, "memory": { "type": "object", "properties": { "usedBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "capBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "infinite": { "type": "boolean" }, "capExceeded": { "type": "boolean" } }, "required": [ "usedBytes", "capBytes", "infinite" ], "additionalProperties": {} }, "confirmationRequired": { "type": "boolean" }, "actionId": { "type": "string" } }, "required": [ "sessionId", "assistantMessageId", "decision", "assistantBody", "contentOrigin", "quotaCostUnits" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Send a message.", "value": { "sessionId": "conv_demo0000000000A", "assistantMessageId": "no_mem_demo0000000000A", "decision": "calculator", "assistantBody": "Your workspace ran 42 checks last week.", "contentOrigin": "computed", "quotaCostUnits": 1, "memory": { "usedBytes": 529, "capBytes": 52428800, "infinite": false, "capExceeded": false } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "expensive", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/number_one.message.list": { "post": { "operationId": "number_one_message_list", "summary": "List messages in a conversation.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "conversationId": { "type": "string", "pattern": "^(conv|sess)_[A-Za-z0-9_-]{8,}$" } }, "required": [ "workspaceId", "conversationId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List messages.", "value": { "workspaceId": "ws_demo_default", "conversationId": "conv_demo0000000000A" } } } } } }, "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": "^no_mem_[A-Za-z0-9_-]{8,}$" }, "conversationId": { "type": "string", "pattern": "^(conv|sess)_[A-Za-z0-9_-]{8,}$" }, "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))$" }, "mode": { "type": "string" }, "erased": { "type": "boolean" }, "contentOrigin": { "type": [ "string", "null" ] }, "trace": {} }, "required": [ "messageId", "conversationId", "role", "body", "createdAt" ], "additionalProperties": {} } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/number_one.mode.set": { "post": { "operationId": "number_one_mode_set", "summary": "Switch a conversation's mode (Calculator / Analyst / Admin).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "conversationId": { "type": "string", "pattern": "^(conv|sess)_[A-Za-z0-9_-]{8,}$" }, "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_demo_default", "conversationId": "conv_demo0000000000A", "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|sess)_[A-Za-z0-9_-]{8,}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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 }, "preview": { "type": "string" } }, "required": [ "conversationId", "workspaceId", "mode", "startedAt", "lastActivityAt", "messageCount" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Switch to Admin mode (requires step-up auth).", "value": { "conversationId": "conv_demo0000000000A", "workspaceId": "ws_demo_default", "mode": "admin", "title": "Q3 audit review", "startedAt": "2026-05-22T12:00:00.000Z", "lastActivityAt": "2026-05-22T12:00:00.000Z", "messageCount": 5, "preview": "Done — 3 monitors active." } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/number_one.memory.list": { "post": { "operationId": "number_one_memory_list", "summary": "List memory facts pinned in a workspace.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "pinnedOnly": { "default": false, "type": "boolean" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List memory facts.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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-Za-z0-9_-]{8,}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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" } ] }, "conversationId": { "type": [ "string", "null" ] } }, "required": [ "factId", "workspaceId", "text", "pinned", "learnedFrom", "learnedAt", "reinforcedAt", "conversationId" ], "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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. Pass factId to re-pin an existing fact, or text (optionally with conversationId provenance) to create + pin a new one.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "factId": { "type": "string", "pattern": "^fact_[A-Za-z0-9_-]{8,}$" }, "text": { "type": "string", "minLength": 1, "maxLength": 4000 }, "conversationId": { "type": "string", "pattern": "^(conv|sess)_[A-Za-z0-9_-]{8,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Re-pin an existing fact.", "value": { "workspaceId": "ws_demo_default", "factId": "fact_demo0000000000A" } }, "example_1": { "summary": "Create + pin a new fact.", "value": { "workspaceId": "ws_demo_default", "text": "Q3 audit is led by Foo & Co LLP", "conversationId": "conv_demo0000000000A" } } } } } }, "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-Za-z0-9_-]{8,}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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" } ] }, "conversationId": { "type": [ "string", "null" ] } }, "required": [ "factId", "workspaceId", "text", "pinned", "learnedFrom", "learnedAt", "reinforcedAt", "conversationId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Re-pin an existing fact.", "value": { "factId": "fact_demo0000000000A", "workspaceId": "ws_demo_default", "text": "Q3 audit is led by Foo & Co LLP", "pinned": true, "learnedFrom": "user", "learnedAt": "2026-05-22T12:00:00.000Z", "reinforcedAt": "2026-05-23T09:00:00.000Z", "conversationId": null } }, "example_1": { "summary": "Create + pin a new fact.", "value": { "factId": "fact_demo0000000000B", "workspaceId": "ws_demo_default", "text": "Q3 audit is led by Foo & Co LLP", "pinned": true, "learnedFrom": "user", "learnedAt": "2026-05-22T12:00:00.000Z", "reinforcedAt": null, "conversationId": "conv_demo0000000000A" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/number_one.memory.unpin": { "post": { "operationId": "number_one_memory_unpin", "summary": "Unpin a memory fact.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "factId": { "type": "string", "pattern": "^fact_[A-Za-z0-9_-]{8,}$" } }, "required": [ "workspaceId", "factId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Unpin.", "value": { "workspaceId": "ws_demo_default", "factId": "fact_demo0000000000A" } } } } } }, "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-Za-z0-9_-]{8,}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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" } ] }, "conversationId": { "type": [ "string", "null" ] } }, "required": [ "factId", "workspaceId", "text", "pinned", "learnedFrom", "learnedAt", "reinforcedAt", "conversationId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Unpin.", "value": { "factId": "fact_demo0000000000A", "workspaceId": "ws_demo_default", "text": "Q3 audit is led by Foo & Co LLP", "pinned": false, "learnedFrom": "user", "learnedAt": "2026-05-22T12:00:00.000Z", "reinforcedAt": null, "conversationId": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/number_one.memory.erase": { "post": { "operationId": "number_one_memory_erase", "summary": "Permanently erase a memory-ledger turn's content (ADR-014 marker — the redaction cannot be undone). memoryId is a message id from message.list; pinned facts are managed via memory.unpin instead.", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "memoryId": { "type": "string", "pattern": "^no_mem_[A-Za-z0-9_-]{8,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "memoryId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Erase a remembered turn's content.", "value": { "workspaceId": "ws_demo_default", "memoryId": "no_mem_demo0000000000A" } } } } } }, "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 remembered turn's content.", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/number_one.memory.cap.get": { "post": { "operationId": "number_one_memory_cap_get", "summary": "Get the workspace's memory usage + cap. The ledger is byte-capped (Z-07); capBytes is -1 when the Infinite Memory add-on is active.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read memory usage + cap.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "usedBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "capBytes": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "number", "const": -1 } ] }, "infinite": { "type": "boolean" } }, "required": [ "usedBytes", "capBytes", "infinite" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read memory usage + cap.", "value": { "usedBytes": 529, "capBytes": 52428800, "infinite": 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/number_one.llm-billing.get": { "post": { "operationId": "number_one_llm-billing_get", "summary": "Read whether this workspace's Number One calls run on Agined's LLM key (metered) or on its own provider key (BYOK, not metered).", "x-agined-description-key": "actions.number_one.llm-billing.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read the billing posture.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "agined_billed", "byok" ] }, "keyAvailable": { "type": "boolean" }, "metered": { "type": "boolean" } }, "required": [ "mode", "keyAvailable", "metered" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read the billing posture.", "value": { "mode": "agined_billed", "keyAvailable": false, "metered": 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/number_one.llm-billing.set": { "post": { "operationId": "number_one_llm-billing_set", "summary": "Choose whether this workspace's Number One calls run on Agined's LLM key (metered) or on its own provider key (BYOK, not metered).", "x-agined-description-key": "actions.number_one.llm-billing.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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "mode": { "type": "string", "enum": [ "agined_billed", "byok" ] } }, "required": [ "workspaceId", "mode" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Run on our own key.", "value": { "workspaceId": "ws_demo_default", "mode": "byok" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "agined_billed", "byok" ] }, "keyAvailable": { "type": "boolean" }, "metered": { "type": "boolean" } }, "required": [ "mode", "keyAvailable", "metered" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Run on our own key.", "value": { "mode": "byok", "keyAvailable": true, "metered": 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "admin.action", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/number_one.analyst.get": { "post": { "operationId": "number_one_analyst_get", "summary": "Read whether Analyst mode is enabled for this workspace.", "x-agined-description-key": "actions.number_one.analyst.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Is Analyst on?", "value": { "workspaceId": "ws_demo_default" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Is Analyst on?", "value": { "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/number_one.analyst.set": { "post": { "operationId": "number_one_analyst_set", "summary": "Turn Analyst mode on or off for everyone in this workspace.", "x-agined-description-key": "actions.number_one.analyst.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "enabled": { "type": "boolean" } }, "required": [ "workspaceId", "enabled" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Disable Analyst for the workspace.", "value": { "workspaceId": "ws_demo_default", "enabled": false } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Disable Analyst for the workspace.", "value": { "enabled": 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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_capabilities" ] }, { "OAuth2": [ "settings.edit_capabilities" ] }, { "WorkspaceApiKey": [ "settings.edit_capabilities" ] } ], "x-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "admin.action", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/number_one.assistant-posture.get": { "post": { "operationId": "number_one_assistant-posture_get", "summary": "Read which posture the assistant runs in for this workspace — membrane-protected, in-boundary or off — and which model provider its calls go to.", "x-agined-description-key": "actions.number_one.assistant-posture.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read the assistant posture.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "posture": { "type": "string", "enum": [ "membrane-protected", "in-boundary", "off" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "anthropic", "openai", "google", "mistral" ] }, { "type": "null" } ] }, "membraneKeyConfigured": { "type": "boolean" }, "inBoundaryConfigured": { "type": "boolean" } }, "required": [ "posture", "provider", "membraneKeyConfigured", "inBoundaryConfigured" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read the assistant posture.", "value": { "posture": "membrane-protected", "provider": null, "membraneKeyConfigured": true, "inBoundaryConfigured": 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/number_one.assistant-posture.set": { "post": { "operationId": "number_one_assistant-posture_set", "summary": "Choose the assistant's posture for this workspace, and which model provider its calls go to.", "x-agined-description-key": "actions.number_one.assistant-posture.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "posture": { "type": "string", "enum": [ "membrane-protected", "in-boundary", "off" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "anthropic", "openai", "google", "mistral" ] }, { "type": "null" } ] } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Disable the assistant workspace-wide.", "value": { "workspaceId": "ws_demo_default", "posture": "off" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "posture": { "type": "string", "enum": [ "membrane-protected", "in-boundary", "off" ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "anthropic", "openai", "google", "mistral" ] }, { "type": "null" } ] }, "membraneKeyConfigured": { "type": "boolean" }, "inBoundaryConfigured": { "type": "boolean" } }, "required": [ "posture", "provider", "membraneKeyConfigured", "inBoundaryConfigured" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Disable the assistant workspace-wide.", "value": { "posture": "off", "provider": null, "membraneKeyConfigured": true, "inBoundaryConfigured": 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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_capabilities" ] }, { "OAuth2": [ "settings.edit_capabilities" ] }, { "WorkspaceApiKey": [ "settings.edit_capabilities" ] } ], "x-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "admin.action", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.attest.agent-call": { "post": { "operationId": "attestor_attest_agent-call", "summary": "Issue an Attestor receipt for an agent.call primitive (outbound API call by a customer's agent).", "x-agined-description-key": "actions.attestor.attest.agent-call.description", "tags": [ "attestor" ], "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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "destination": { "type": "string", "format": "uri" }, "method": { "type": "string" }, "requestBodySha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "responseBodySha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "responseStatus": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "durationMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "agentId": { "type": "string" }, "purpose": { "type": "string" } }, "required": [ "workspaceId", "destination", "method", "requestBodySha256", "responseBodySha256", "responseStatus", "durationMs", "agentId", "purpose" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Attest an agent call.", "value": { "workspaceId": "ws_demo_default", "destination": "https://api.stripe.com/v1/charges", "method": "POST", "requestBodySha256": "abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd", "responseBodySha256": "abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890abce", "responseStatus": 200, "durationMs": 387, "agentId": "billing-bot", "purpose": "refund_processing" } } } } } }, "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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-Za-z0-9_-]{4,64}$" }, "body": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "receiptId", "workspaceId", "kind", "issuedAt", "signature", "signatureKeyId", "body" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Attest an agent call.", "value": { "receiptId": "01H8X4P9R7Z2C1A1F2A8VBJYV2", "workspaceId": "ws_demo_default", "kind": "agent.call", "issuedAt": "2026-05-22T12:00:00.000Z", "signature": "...", "signatureKeyId": "attestor-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.attest.agent-call" ] }, { "OAuth2": [ "attestor.attest.agent-call" ] }, { "WorkspaceApiKey": [ "attestor.attest.agent-call" ] } ], "x-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.attest.content": { "post": { "operationId": "attestor_attest_content", "summary": "Attest a content blob (text, image hash, document). Returns a signed receipt.", "x-agined-description-key": "actions.attestor.attest.content.description", "tags": [ "attestor" ], "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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "contentSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "contentType": { "type": "string" }, "policyId": { "type": "string" }, "purpose": { "type": "string" } }, "required": [ "workspaceId", "contentSha256", "contentType", "purpose" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Attest content.", "value": { "workspaceId": "ws_demo_default", "contentSha256": "abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd", "contentType": "text/plain", "purpose": "marketing_copy_approval" } } } } } }, "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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-Za-z0-9_-]{4,64}$" }, "body": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "receiptId", "workspaceId", "kind", "issuedAt", "signature", "signatureKeyId", "body" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Attest content.", "value": { "receiptId": "01H8X4P9R7Z2C1A1F2A8VBJYV3", "workspaceId": "ws_demo_default", "kind": "content.attest", "issuedAt": "2026-05-22T12:00:00.000Z", "signature": "...", "signatureKeyId": "attestor-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.attest.content" ] }, { "OAuth2": [ "attestor.attest.content" ] }, { "WorkspaceApiKey": [ "attestor.attest.content" ] } ], "x-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.attest.llm": { "post": { "operationId": "attestor_attest_llm", "summary": "Attest an LLM inference (model + prompt hash + response hash + provider).", "x-agined-description-key": "actions.attestor.attest.llm.description", "tags": [ "attestor" ], "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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "modelId": { "type": "string" }, "providerId": { "type": "string" }, "promptSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "responseSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "latencyMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "promptTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "completionTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "workspaceId", "modelId", "providerId", "promptSha256", "responseSha256", "latencyMs", "promptTokens", "completionTokens" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Attest LLM call.", "value": { "workspaceId": "ws_demo_default", "modelId": "claude-opus-4.7", "providerId": "anthropic", "promptSha256": "abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd", "responseSha256": "abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890abce", "latencyMs": 1500, "promptTokens": 1200, "completionTokens": 850 } } } } } }, "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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-Za-z0-9_-]{4,64}$" }, "body": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "receiptId", "workspaceId", "kind", "issuedAt", "signature", "signatureKeyId", "body" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Attest LLM call.", "value": { "receiptId": "01H8X4P9R7Z2C1A1F2A8VBJYV4", "workspaceId": "ws_demo_default", "kind": "llm.attest", "issuedAt": "2026-05-22T12:00:00.000Z", "signature": "...", "signatureKeyId": "attestor-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.attest.llm" ] }, { "OAuth2": [ "attestor.attest.llm" ] }, { "WorkspaceApiKey": [ "attestor.attest.llm" ] } ], "x-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.attest.commit": { "post": { "operationId": "attestor_attest_commit", "summary": "Attest a Git commit (commit hash + author + repo URL). Pairs with the @attestor/attest-commit GitHub Action.", "x-agined-description-key": "actions.attestor.attest.commit.description", "tags": [ "attestor" ], "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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "commitSha": { "type": "string" }, "repoUrl": { "type": "string", "format": "uri" }, "author": { "type": "string" }, "message": { "type": "string", "maxLength": 5000 } }, "required": [ "workspaceId", "commitSha", "repoUrl", "author", "message" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Attest a Git commit.", "value": { "workspaceId": "ws_demo_default", "commitSha": "abc1234567890abcdef1234567890abcdef1234567", "repoUrl": "https://github.com/example/repo", "author": "alice@example.com", "message": "Refactor billing service" } } } } } }, "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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-Za-z0-9_-]{4,64}$" }, "body": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "receiptId", "workspaceId", "kind", "issuedAt", "signature", "signatureKeyId", "body" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Attest a Git commit.", "value": { "receiptId": "01H8X4P9R7Z2C1A1F2A8VBJYV5", "workspaceId": "ws_demo_default", "kind": "commit.attest", "issuedAt": "2026-05-22T12:00:00.000Z", "signature": "...", "signatureKeyId": "attestor-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.attest.commit" ] }, { "OAuth2": [ "attestor.attest.commit" ] }, { "WorkspaceApiKey": [ "attestor.attest.commit" ] } ], "x-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.deliver.webhook": { "post": { "operationId": "attestor_deliver_webhook", "summary": "Issue a receipt for an outbound webhook delivery attempt.", "x-agined-description-key": "actions.attestor.deliver.webhook.description", "tags": [ "attestor" ], "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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "webhookId": { "type": "string" }, "destination": { "type": "string", "format": "uri" }, "payloadSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "statusCode": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "attemptNumber": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "workspaceId", "webhookId", "destination", "payloadSha256", "statusCode", "attemptNumber" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Attest webhook delivery.", "value": { "workspaceId": "ws_demo_default", "webhookId": "wh_abc", "destination": "https://example.com/webhook", "payloadSha256": "abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd", "statusCode": 200, "attemptNumber": 1 } } } } } }, "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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-Za-z0-9_-]{4,64}$" }, "body": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "receiptId", "workspaceId", "kind", "issuedAt", "signature", "signatureKeyId", "body" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Attest webhook delivery.", "value": { "receiptId": "01H8X4P9R7Z2C1A1F2A8VBJYV6", "workspaceId": "ws_demo_default", "kind": "webhook.deliver", "issuedAt": "2026-05-22T12:00:00.000Z", "signature": "...", "signatureKeyId": "attestor-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.deliver.webhook" ] }, { "OAuth2": [ "attestor.deliver.webhook" ] }, { "WorkspaceApiKey": [ "attestor.deliver.webhook" ] } ], "x-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.monitor.http.add": { "post": { "operationId": "attestor_monitor_http_add", "summary": "Register a new HTTP monitor (1-minute minimum interval).", "x-agined-description-key": "actions.attestor.monitor.http.add.description", "tags": [ "attestor" ], "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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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": "^mon_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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": "mon_demo00000000000000000000", "workspaceId": "ws_demo_default", "url": "https://api.example.com/health", "method": "GET", "intervalSeconds": 60, "expectedStatusCodes": [ 200 ], "enabled": true, "createdAt": "2026-05-22T12:00:00.000Z", "lastCheckAt": null } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.monitors.create" ] }, { "OAuth2": [ "attestor.monitors.create" ] }, { "WorkspaceApiKey": [ "attestor.monitors.create" ] } ], "x-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.monitor.http.list": { "post": { "operationId": "attestor_monitor_http_list", "summary": "List HTTP monitors in a workspace.", "x-agined-description-key": "actions.attestor.monitor.http.list.description", "tags": [ "attestor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "enabledOnly": { "default": false, "type": "boolean" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List monitors.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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": "^mon_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.monitors.view" ] }, { "OAuth2": [ "attestor.monitors.view" ] }, { "WorkspaceApiKey": [ "attestor.monitors.view" ] } ], "x-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.monitor.http.run-now": { "post": { "operationId": "attestor_monitor_http_run-now", "summary": "Run a monitor check immediately (bypasses the scheduled interval).", "x-agined-description-key": "actions.attestor.monitor.http.run-now.description", "tags": [ "attestor" ], "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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "monitorId": { "type": "string", "pattern": "^mon_[0-9A-Z]{20,}$" } }, "required": [ "workspaceId", "monitorId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Run a monitor check now.", "value": { "workspaceId": "ws_demo_default", "monitorId": "mon_demo00000000000000000000" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.monitors.create" ] }, { "OAuth2": [ "attestor.monitors.create" ] }, { "WorkspaceApiKey": [ "attestor.monitors.create" ] } ], "x-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "expensive", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.monitor.http.remove": { "post": { "operationId": "attestor_monitor_http_remove", "summary": "Delete an HTTP monitor.", "x-agined-description-key": "actions.attestor.monitor.http.remove.description", "tags": [ "attestor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "monitorId": { "type": "string", "pattern": "^mon_[0-9A-Z]{20,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "monitorId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete monitor.", "value": { "workspaceId": "ws_demo_default", "monitorId": "mon_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 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.monitors.delete" ] }, { "OAuth2": [ "attestor.monitors.delete" ] }, { "WorkspaceApiKey": [ "attestor.monitors.delete" ] } ], "x-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.watch.dns.add": { "post": { "operationId": "attestor_watch_dns_add", "summary": "Register a DNS watch (detects record drift; signs every check as a receipt).", "x-agined-description-key": "actions.attestor.watch.dns.add.description", "tags": [ "attestor" ], "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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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": "^dnsw_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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": "dnsw_demo00000000000000000000", "workspaceId": "ws_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.dns.create" ] }, { "OAuth2": [ "attestor.dns.create" ] }, { "WorkspaceApiKey": [ "attestor.dns.create" ] } ], "x-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.watch.dns.list": { "post": { "operationId": "attestor_watch_dns_list", "summary": "List DNS watches in a workspace.", "x-agined-description-key": "actions.attestor.watch.dns.list.description", "tags": [ "attestor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List DNS watches.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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": "^dnsw_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.dns.view" ] }, { "OAuth2": [ "attestor.dns.view" ] }, { "WorkspaceApiKey": [ "attestor.dns.view" ] } ], "x-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.watch.dns.remove": { "post": { "operationId": "attestor_watch_dns_remove", "summary": "Delete a DNS watch.", "x-agined-description-key": "actions.attestor.watch.dns.remove.description", "tags": [ "attestor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "dnsWatchId": { "type": "string", "pattern": "^dnsw_[0-9A-Z]{20,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "dnsWatchId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete DNS watch.", "value": { "workspaceId": "ws_demo_default", "dnsWatchId": "dnsw_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 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.dns.delete" ] }, { "OAuth2": [ "attestor.dns.delete" ] }, { "WorkspaceApiKey": [ "attestor.dns.delete" ] } ], "x-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.watch.tls.add": { "post": { "operationId": "attestor_watch_tls_add", "summary": "Register a TLS certificate watch (detects cert changes; signs every check).", "x-agined-description-key": "actions.attestor.watch.tls.add.description", "tags": [ "attestor" ], "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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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": "^tlsw_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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": "tlsw_demo00000000000000000000", "workspaceId": "ws_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.tls.create" ] }, { "OAuth2": [ "attestor.tls.create" ] }, { "WorkspaceApiKey": [ "attestor.tls.create" ] } ], "x-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.watch.tls.list": { "post": { "operationId": "attestor_watch_tls_list", "summary": "List TLS watches in a workspace.", "x-agined-description-key": "actions.attestor.watch.tls.list.description", "tags": [ "attestor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List TLS watches.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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": "^tlsw_[0-9A-Z]{20,}$" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.tls.view" ] }, { "OAuth2": [ "attestor.tls.view" ] }, { "WorkspaceApiKey": [ "attestor.tls.view" ] } ], "x-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.watch.tls.remove": { "post": { "operationId": "attestor_watch_tls_remove", "summary": "Delete a TLS watch.", "x-agined-description-key": "actions.attestor.watch.tls.remove.description", "tags": [ "attestor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "tlsWatchId": { "type": "string", "pattern": "^tlsw_[0-9A-Z]{20,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "tlsWatchId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Delete TLS watch.", "value": { "workspaceId": "ws_demo_default", "tlsWatchId": "tlsw_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 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.tls.delete" ] }, { "OAuth2": [ "attestor.tls.delete" ] }, { "WorkspaceApiKey": [ "attestor.tls.delete" ] } ], "x-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.receipt.list": { "post": { "operationId": "attestor_receipt_list", "summary": "List Attestor receipts for a workspace.", "x-agined-description-key": "actions.attestor.receipt.list.description", "tags": [ "attestor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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-Za-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.receipts.view" ] }, { "OAuth2": [ "attestor.receipts.view" ] }, { "WorkspaceApiKey": [ "attestor.receipts.view" ] } ], "x-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.receipt.get": { "post": { "operationId": "attestor_receipt_get", "summary": "Get a single receipt with full body.", "x-agined-description-key": "actions.attestor.receipt.get.description", "tags": [ "attestor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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-Za-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_demo_default", "kind": "agent.call", "issuedAt": "2026-05-22T12:00:00.000Z", "signature": "...", "signatureKeyId": "attestor-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.receipts.view" ] }, { "OAuth2": [ "attestor.receipts.view" ] }, { "WorkspaceApiKey": [ "attestor.receipts.view" ] } ], "x-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.receipt.verify": { "post": { "operationId": "attestor_receipt_verify", "summary": "Verify a receipt's Ed25519 signature against the published public key. Cannot be disabled.", "x-agined-description-key": "actions.attestor.receipt.verify.description", "tags": [ "attestor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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-Za-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_demo_default", "kind": "agent.call", "issuedAt": "2026-05-22T12:00:00.000Z", "signature": "...", "signatureKeyId": "attestor-2026-q2-enam", "body": {} } } } } } } }, "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" }, "publishedKeyUrl": { "type": "string", "format": "uri" }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "valid", "signatureValid", "publishedKeyUrl", "errors" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify a receipt.", "value": { "valid": true, "signatureValid": true, "publishedKeyUrl": "https://agined.com/.well-known/attestor-keys.json", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.usage.current": { "post": { "operationId": "attestor_usage_current", "summary": "Get current-period Attestor usage for a workspace (calls per primitive + budget consumed).", "x-agined-description-key": "actions.attestor.usage.current.description", "tags": [ "attestor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read current usage.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.usage.view" ] }, { "OAuth2": [ "attestor.usage.view" ] }, { "WorkspaceApiKey": [ "attestor.usage.view" ] } ], "x-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.usage.historical": { "post": { "operationId": "attestor_usage_historical", "summary": "Get historical Attestor usage (per-day breakdown for a date range).", "x-agined-description-key": "actions.attestor.usage.historical.description", "tags": [ "attestor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.usage.view" ] }, { "OAuth2": [ "attestor.usage.view" ] }, { "WorkspaceApiKey": [ "attestor.usage.view" ] } ], "x-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "expensive", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.subscription.get": { "post": { "operationId": "attestor_subscription_get", "summary": "Get workspace Attestor subscription state.", "x-agined-description-key": "actions.attestor.subscription.get.description", "tags": [ "attestor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read subscription state.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.subscription.view" ] }, { "OAuth2": [ "attestor.subscription.view" ] }, { "WorkspaceApiKey": [ "attestor.subscription.view" ] } ], "x-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.subscription.cancel": { "post": { "operationId": "attestor_subscription_cancel", "summary": "Cancel the Attestor subscription at the next billing period. Workspace's existing receipts remain accessible.", "x-agined-description-key": "actions.attestor.subscription.cancel.description", "tags": [ "attestor" ], "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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "reason" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Cancel Attestor subscription.", "value": { "workspaceId": "ws_demo_default", "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 Attestor 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "plan.changed", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.abuse-status.get": { "post": { "operationId": "attestor_abuse-status_get", "summary": "Get the current Attestor abuse status for a workspace.", "x-agined-description-key": "actions.attestor.abuse-status.get.description", "tags": [ "attestor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read abuse status.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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" ] } }, "required": [ "workspaceId", "status", "flaggedAt", "suspendedAt", "reason" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read abuse status.", "value": { "workspaceId": "ws_demo_default", "status": "clean", "flaggedAt": null, "suspendedAt": null, "reason": 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.abuse.view" ] }, { "OAuth2": [ "attestor.abuse.view" ] }, { "WorkspaceApiKey": [ "attestor.abuse.view" ] } ], "x-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.abuse-status.appeal": { "post": { "operationId": "attestor_abuse-status_appeal", "summary": "Submit an appeal against an abuse-status flag or suspension.", "x-agined-description-key": "actions.attestor.abuse-status.appeal.description", "tags": [ "attestor" ], "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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "appealText": { "type": "string", "minLength": 50, "maxLength": 5000 } }, "required": [ "workspaceId", "appealText" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Submit abuse appeal.", "value": { "workspaceId": "ws_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.abuse.appeal" ] }, { "OAuth2": [ "attestor.abuse.appeal" ] }, { "WorkspaceApiKey": [ "attestor.abuse.appeal" ] } ], "x-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.signing-key.get": { "post": { "operationId": "attestor_signing-key_get", "summary": "Get the current active Attestor signing key id for the workspace's jurisdiction.", "x-agined-description-key": "actions.attestor.signing-key.get.description", "tags": [ "attestor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read signing key id.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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-Za-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": "attestor-2026-q2-enam", "jurisdiction": "ENAM", "issuedAt": "2026-04-01T00:00:00.000Z", "expiresAt": "2027-04-01T00:00:00.000Z", "publishedAtUrl": "https://agined.com/.well-known/attestor-keys.json" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.subscription.view" ] }, { "OAuth2": [ "attestor.subscription.view" ] }, { "WorkspaceApiKey": [ "attestor.subscription.view" ] } ], "x-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.signing-key.list": { "post": { "operationId": "attestor_signing-key_list", "summary": "List all signing keys (active + historical) usable to verify the workspace's receipts.", "x-agined-description-key": "actions.attestor.signing-key.list.description", "tags": [ "attestor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List signing keys.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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-Za-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": "attestor-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.subscription.view" ] }, { "OAuth2": [ "attestor.subscription.view" ] }, { "WorkspaceApiKey": [ "attestor.subscription.view" ] } ], "x-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.signing-key.rotate-request": { "post": { "operationId": "attestor_signing-key_rotate-request", "summary": "Request signing-key rotation (Enterprise tier dedicated keys only). Agined ops fulfils via key ceremony.", "x-agined-description-key": "actions.attestor.signing-key.rotate-request.description", "tags": [ "attestor" ], "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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 } }, "required": [ "workspaceId", "reason" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Request key rotation.", "value": { "workspaceId": "ws_demo_default", "reason": "Q4 scheduled rotation per our internal policy" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestId": { "type": "string" }, "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))$" } }, "required": [ "requestId", "estimatedRotationAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Request key rotation.", "value": { "requestId": "rot_abc", "estimatedRotationAt": "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.subscription.view" ] }, { "OAuth2": [ "attestor.subscription.view" ] }, { "WorkspaceApiKey": [ "attestor.subscription.view" ] } ], "x-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "admin.action", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.signing-key.public.get": { "post": { "operationId": "attestor_signing-key_public_get", "summary": "Get the public-key JWK for a specific signing key id (for offline verification).", "x-agined-description-key": "actions.attestor.signing-key.public.get.description", "tags": [ "attestor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Za-z0-9_-]{4,64}$" } }, "required": [ "signingKeyId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read public key JWK.", "value": { "signingKeyId": "attestor-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.status.get": { "post": { "operationId": "attestor_status_get", "summary": "Get the Attestor subsystem health (per-jurisdiction Worker uptime, per-primitive error rate, last self-attestation receipt).", "x-agined-description-key": "actions.attestor.status.get.description", "tags": [ "attestor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Read Attestor health.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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 Attestor 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "attestor.subscription.view" ] }, { "OAuth2": [ "attestor.subscription.view" ] }, { "WorkspaceApiKey": [ "attestor.subscription.view" ] } ], "x-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/attestor.attestation-feed.get": { "post": { "operationId": "attestor_attestation-feed_get", "summary": "Get the daily Attestor self-attestation receipt feed (Agined attesting to its own platform integrity).", "x-agined-description-key": "actions.attestor.attestation-feed.get.description", "tags": [ "attestor" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/starfleet.run": { "post": { "operationId": "starfleet_run", "summary": "Post a run to a Starfleet spot actor (witness/council/historian/custodian/conscience/…) — observe + decide + anchor it in the workspace hash-chain.", "x-agined-description-key": "actions.starfleet.run.description", "tags": [ "starfleet" ], "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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_invocation", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/starfleet.runs.list": { "post": { "operationId": "starfleet_runs_list", "summary": "List the workspace's Starfleet runs (actor IS the surface: witness | historian | custodian | conscience | …).", "x-agined-description-key": "actions.starfleet.runs.list.description", "tags": [ "starfleet" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/starfleet.actors.list": { "post": { "operationId": "starfleet_actors_list", "summary": "List the Starfleet roster (optionally for one version) with each actor's min tier.", "x-agined-description-key": "actions.starfleet.actors.list.description", "tags": [ "starfleet" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/starfleet.agents.list": { "post": { "operationId": "starfleet_agents_list", "summary": "List the workspace's posting agents (distinct agent DIDs across runs, with counts + last-seen).", "x-agined-description-key": "actions.starfleet.agents.list.description", "tags": [ "starfleet" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/starfleet.runs.verify-chain": { "post": { "operationId": "starfleet_runs_verify-chain", "summary": "Verify the integrity of the workspace's run hash-chain from a starting sequence.", "x-agined-description-key": "actions.starfleet.runs.verify-chain.description", "tags": [ "starfleet" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "expensive", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/starfleet.runs.diff": { "post": { "operationId": "starfleet_runs_diff", "summary": "Compare two Starfleet runs (classification + payload diff).", "x-agined-description-key": "actions.starfleet.runs.diff.description", "tags": [ "starfleet" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/starfleet.runs.replay": { "post": { "operationId": "starfleet_runs_replay", "summary": "Reconstruct + re-verify a single run from its chain entry.", "x-agined-description-key": "actions.starfleet.runs.replay.description", "tags": [ "starfleet" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/ledger-bundles.snapshot.create": { "post": { "operationId": "ledger-bundles_snapshot_create", "summary": "Create a signed LedgerBundles snapshot of the workspace's audit state (a paid action).", "x-agined-description-key": "actions.ledger-bundles.snapshot.create.description", "tags": [ "ledger-bundles" ], "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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": {} } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "agent_invocation", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/ledger-bundles.verify-chain": { "post": { "operationId": "ledger-bundles_verify-chain", "summary": "Verify the LedgerBundles transparency chain (free — a transparency guarantee).", "x-agined-description-key": "actions.ledger-bundles.verify-chain.description", "tags": [ "ledger-bundles" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": {} } } } } }, "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": {} } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/ledger-bundles.anchors.list": { "post": { "operationId": "ledger-bundles_anchors_list", "summary": "List the LedgerBundles anchors (the published chain checkpoints).", "x-agined-description-key": "actions.ledger-bundles.anchors.list.description", "tags": [ "ledger-bundles" ], "parameters": [ { "name": "X-Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 120 }, "description": "Required for mutating non-idempotent actions; recommended otherwise. Echo to retry a request without double-effect." }, { "name": "X-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": {} } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/privacy.dsr.submit": { "post": { "operationId": "privacy_dsr_submit", "summary": "Submit a data-subject request (GDPR / CCPA). Cannot be disabled — statutory right.", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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", "automated_decision_review", "withdraw_consent" ] }, "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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", "automated_decision_review", "withdraw_consent" ] }, "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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" } ] } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "admin.action", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/privacy.dsr.status": { "post": { "operationId": "privacy_dsr_status", "summary": "Check status of a submitted DSR. Cannot be disabled — statutory right.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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", "automated_decision_review", "withdraw_consent" ] }, "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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" } ] } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/privacy.dsr.list": { "post": { "operationId": "privacy_dsr_list", "summary": "List all DSRs filed for this account / workspace.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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", "automated_decision_review", "withdraw_consent" ] }, "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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" } ] } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "format": { "default": "portable-archive", "type": "string", "enum": [ "json", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "expensive", "x-agined-audit-kind": "export.requested", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/privacy.export.download": { "post": { "operationId": "privacy_export_download", "summary": "Get a signed download URL for a completed personal-data export.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": { "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" } }, "required": [ "url", "expiresAt", "sha256" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Download your export.", "value": { "url": "https://r2.agined.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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "export.completed", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/privacy.subject-rights.list": { "post": { "operationId": "privacy_subject-rights_list", "summary": "List the data-subject rights Agined honours (GDPR, CCPA, LGPD) + the legal references.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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", "automated_decision_review", "withdraw_consent" ] }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/support.tickets.list": { "post": { "operationId": "support_tickets_list", "summary": "List your support tickets.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": [ "critical", "high", "medium", "low" ] }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/support.tickets.create": { "post": { "operationId": "support_tickets_create", "summary": "Open a new support ticket.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "medium", "type": "string", "enum": [ "critical", "high", "medium", "low" ] } }, "required": [ "subject", "body" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Open a new ticket.", "value": { "subject": "Issue with Tools receipt verification", "body": "Hi — I'm seeing a signature_invalid error when verifying receipts from workspace ws_X. Could you take a look?", "priority": "medium" } } } } } }, "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": [ "critical", "high", "medium", "low" ] }, "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 Tools receipt verification", "status": "open", "priority": "medium", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/support.tickets.get": { "post": { "operationId": "support_tickets_get", "summary": "Get a ticket's details + reply thread.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": [ "critical", "high", "medium", "low" ] }, "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", "agined-support", "agined-ai", "system" ] }, "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": "medium", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/support.tickets.reply": { "post": { "operationId": "support_tickets_reply", "summary": "Post a reply to a ticket.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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 …" } } } } } }, "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", "agined-support", "agined-ai", "system" ] }, "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 …", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/support.tickets.close": { "post": { "operationId": "support_tickets_close", "summary": "Close a ticket (optionally with a reason).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": [ "critical", "high", "medium", "low" ] }, "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": "medium", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/support.satisfaction.rate": { "post": { "operationId": "support_satisfaction_rate", "summary": "Rate the support experience after a ticket closes — five dimensions, 1–5 each (ADR-034). A 2-or-below on any dimension triggers the feedback loop.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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 support 5/5 across the board.", "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" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Rate support 5/5 across the board.", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/discovery.capabilities.get": { "post": { "operationId": "discovery_capabilities_get", "summary": "Get the full action registry catalogue (machine-readable). Same content as `/api/v1/actions.json`.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/discovery.version.get": { "post": { "operationId": "discovery_version_get", "summary": "Get the platform version + contracts package version + supported MCP / OpenAPI spec versions.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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": "agined/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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/discovery.schema.get": { "post": { "operationId": "discovery_schema_get", "summary": "Get the JSON Schema for a specific action's input or output.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/discovery.locales.list": { "post": { "operationId": "discovery_locales_list", "summary": "List supported user-facing locales.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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", "pt", "it" ] }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/discovery.plans.list": { "post": { "operationId": "discovery_plans_list", "summary": "List the available Agined + Tools subscription plans.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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": [ "agined", "tools", "attestor", "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": [ "agined", "tools", "attestor" ] }, "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": "agined", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/discovery.regions.list": { "post": { "operationId": "discovery_regions_list", "summary": "List the 32 data-residency regions a workspace can be bound to.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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 32 regions (6 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 32 regions (6 Cloudflare + 26 AWS Aurora).", "value": { "regions": [ { "id": "cloudflare-d1:weur", "provider": "cloudflare-d1", "label": "Western Europe", "countryCode": "DE", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/agents.identity.enroll": { "post": { "operationId": "agents_identity_enroll", "summary": "Enroll a new W3C DID Web agent identity under your principal.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": [ "workspace", "organization", "agent" ] }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "organizationId": { "type": "string", "pattern": "^org_[A-Za-z0-9_-]{11,}$" }, "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. One-time secrets are minted by rotate, not enroll.", "value": { "displayName": "GitHub Actions release attestor", "scopeKind": "workspace", "workspaceId": "ws_demo_default" } } } } } }, "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", "null" ] }, "privateKeyRecoveryEnvelope": { "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))$" } }, "required": [ "did", "documentUrl", "enrollmentCredential", "privateKeyRecoveryEnvelope", "createdAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Enroll a workspace-scoped agent DID for CI signing. One-time secrets are minted by rotate, not enroll.", "value": { "did": "did:web:agined.com:agents:ws_demo_default:abc", "documentUrl": "https://agined.com/.well-known/agents/ws_demo_default/abc/did.json", "enrollmentCredential": null, "privateKeyRecoveryEnvelope": null, "createdAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "agents.create" ] }, { "OAuth2": [ "agents.create" ] }, { "WorkspaceApiKey": [ "agents.create" ] } ], "x-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent.identity.enrolled", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/agents.identity.list": { "post": { "operationId": "agents_identity_list", "summary": "List enrolled agent DIDs visible to the principal.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "organizationId": { "type": "string", "pattern": "^org_[A-Za-z0-9_-]{11,}$" }, "includeDeactivated": { "default": false, "type": "boolean" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "List workspace-scoped agents.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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": [ "workspace", "organization", "agent" ] }, "workspaceId": { "anyOf": [ { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, { "type": "null" } ] }, "organizationId": { "anyOf": [ { "type": "string", "pattern": "^org_[A-Za-z0-9_-]{11,}$" }, { "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "agents.view" ] }, { "OAuth2": [ "agents.view" ] }, { "WorkspaceApiKey": [ "agents.view" ] } ], "x-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/agents.identity.get": { "post": { "operationId": "agents_identity_get", "summary": "Get one enrolled agent DID with full document + rotation history.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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:agined.com:agents:ws_demo_default: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": [ "workspace", "organization", "agent" ] }, "workspaceId": { "anyOf": [ { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, { "type": "null" } ] }, "organizationId": { "anyOf": [ { "type": "string", "pattern": "^org_[A-Za-z0-9_-]{11,}$" }, { "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:agined.com:agents:ws_demo_default:abc", "displayName": "GitHub Actions release attestor", "description": null, "scopeKind": "workspace", "workspaceId": "ws_demo_default", "organizationId": null, "alg": "EdDSA", "activeMethodId": "did:web:agined.com:agents:ws_demo_default:abc#key-1", "enrolledAt": "2026-05-22T12:00:00.000Z", "deactivatedAt": null, "lastSeenAt": null, "rotationsCount": 0, "lastTrustBundleSignedAt": null }, "document": {}, "rotationHistory": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "agents.view" ] }, { "OAuth2": [ "agents.view" ] }, { "WorkspaceApiKey": [ "agents.view" ] } ], "x-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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:agined.com:agents:ws_demo_default: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:agined.com:agents:ws_demo_default:abc", "newMethodId": "did:web:agined.com:agents:ws_demo_default:abc#key-2", "oldMethodRetiresAt": "2026-05-22T13:00:00.000Z", "privateKeyRecoveryEnvelope": "v1:AES-256-GCM:…" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "agents.create" ] }, { "OAuth2": [ "agents.create" ] }, { "WorkspaceApiKey": [ "agents.create" ] } ], "x-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent.identity.rotated", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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:agined.com:agents:ws_demo_default: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))$" } }, "required": [ "did", "deactivatedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Compromise-recovery revoke.", "value": { "did": "did:web:agined.com:agents:ws_demo_default:abc", "deactivatedAt": "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "agents.delete" ] }, { "OAuth2": [ "agents.delete" ] }, { "WorkspaceApiKey": [ "agents.delete" ] } ], "x-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent.identity.revoked", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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:agined.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:agined.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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "fromAgentDid": "did:web:agined.com:agents:ws_demo_default:abc", "toRemoteDid": "did:web:partner.example.com:agents:bot", "scopes": [ "read:audit" ], "validForDays": 7, "purposeReason": "Partner integration handoff" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "agents.create" ] }, { "OAuth2": [ "agents.create" ] }, { "WorkspaceApiKey": [ "agents.create" ] } ], "x-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent.delegation.issued", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/agents.identity.delegate.revoke": { "post": { "operationId": "agents_identity_delegate_revoke", "summary": "Revoke an A2A delegation. Flips its bit in the published BitstringStatusList.", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "Revoke an A2A delegation.", "value": { "delegationHandle": "delg_demo00000000000000000000", "reason": "Partner integration 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": "Revoke an A2A 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "agents.delete" ] }, { "OAuth2": [ "agents.delete" ] }, { "WorkspaceApiKey": [ "agents.delete" ] } ], "x-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent.delegation.revoked", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/agents.identity.delegate.verify": { "post": { "operationId": "agents_identity_delegate_verify", "summary": "Verify a presented A2A delegation credential. Returns ok, or a structured reason.", "x-agined-description-key": "actions.agents.identity.delegate.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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", "minLength": 1 }, "requestedScope": { "type": "string" } }, "required": [ "presentationSerialized" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Verify a presented A2A delegation.", "value": { "presentationSerialized": "eyJhbGciOiJFZERTQSJ9…", "requestedScope": "read:audit" } } } } } }, "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 }, "delegationHandle": { "type": "string" }, "vcId": { "type": "string" }, "fromAgentDid": { "type": "string" }, "toRemoteDid": { "type": "string" }, "scopes": { "type": "array", "items": { "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))$" }, "revocationChecked": { "type": "boolean" } }, "required": [ "ok", "delegationHandle", "vcId", "fromAgentDid", "toRemoteDid", "scopes", "expiresAt", "revocationChecked" ], "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 presented A2A delegation.", "value": { "ok": true, "delegationHandle": "delg_demo00000000000000000000", "vcId": "urn:uuid:0000", "fromAgentDid": "did:web:agined.com:agents:ws_demo_default:abc", "toRemoteDid": "did:web:partner.example.com:agents:bot", "scopes": [ "read:audit" ], "expiresAt": "2026-05-29T12:00:00.000Z", "revocationChecked": true } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/agents.identity.authority.get": { "post": { "operationId": "agents_identity_authority_get", "summary": "Resolve who an agent acts on behalf of, from verified identity rather than operator configuration.", "x-agined-description-key": "actions.agents.identity.authority.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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.\\-_:%]+$" }, "selfAsserted": { "type": "string" } }, "required": [ "agentDid" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Resolve the on-whose-behalf value.", "value": { "agentDid": "did:web:agined.com:agents:ws_demo_default:abc" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentDid": { "type": "string" }, "confidence": { "type": "string", "enum": [ "verified", "unverified", "conflicted" ] }, "grade": { "type": "string", "enum": [ "self-asserted", "domain-control", "workload-identity", "tenant-attested", "business-verified", "wallet-attested" ] }, "principal": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "basis": { "type": "string" }, "reliedOn": { "type": "array", "items": { "type": "string" } }, "competingPrincipals": { "type": "array", "items": { "type": "string" } }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "principal": { "type": "string" }, "verified": { "type": "boolean" }, "failureReason": { "type": "string" } }, "required": [ "source", "principal", "verified" ], "additionalProperties": false } } }, "required": [ "agentDid", "confidence", "grade", "principal", "source", "basis", "reliedOn", "competingPrincipals", "evidence" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Resolve the on-whose-behalf value.", "value": { "agentDid": "did:web:agined.com:agents:ws_demo_default:abc", "confidence": "verified", "grade": "tenant-attested", "principal": "did:web:agined.com:workspaces:ws_demo_default", "source": "ap2-mandate", "basis": "A mandate signed by the workspace principal names this agent.", "reliedOn": [ "Art. 50(1)", "Art. 50(1) — on-whose-behalf element" ], "competingPrincipals": [], "evidence": [ { "source": "ap2-mandate", "principal": "did:web:agined.com:workspaces:ws_demo_default", "verified": true } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "agents.view" ] }, { "OAuth2": [ "agents.view" ] }, { "WorkspaceApiKey": [ "agents.view" ] } ], "x-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "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:agined.com:agents:ws_demo_default:refund-bot", "allowedActionIds": [ "billing.subscription.upgrade", "tools.attest.agent-call" ], "maxSafetyLevel": "billing_impacting", "workspaceIds": [ "ws_demo_default" ], "maxSpendUsdFractional": 50000, "maxInvocations": 100, "validForDays": 30 } } } } } }, "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:agined.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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "agents.create" ] }, { "OAuth2": [ "agents.create" ] }, { "WorkspaceApiKey": [ "agents.create" ] } ], "x-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent.mandate.issued", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/agents.mandate.list": { "post": { "operationId": "agents_mandate_list", "summary": "List mandates issued under the principal.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "activeOnly": { "default": false, "type": "boolean" } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "List mandates.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "agents.view" ] }, { "OAuth2": [ "agents.view" ] }, { "WorkspaceApiKey": [ "agents.view" ] } ], "x-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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…", "requestedActionId": "billing.subscription.upgrade", "audience": "https://api.agined.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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/agents.mandate.revoke": { "post": { "operationId": "agents_mandate_revoke", "summary": "Revoke a mandate, and every A2A delegation the agent issued under it (the kill chain). Goes into the BitstringStatusList revocation register immediately.", "x-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "Revoking the mandate also withdrew one delegation the agent had issued — and named the two API keys it minted, which are STILL LIVE and must be revoked directly.", "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))$" }, "cascade": { "type": "object", "properties": { "delegationsRevoked": { "type": "array", "items": { "type": "string" }, "description": "Delegation handles withdrawn by this revoke." }, "notWalked": { "type": "array", "items": { "type": "string" }, "description": "Delegate DIDs whose OWN delegations were not reached because the walk hit its depth cap. Their delegations are still active and must be revoked directly." }, "depth": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many hops the walk went." }, "complete": { "type": "boolean", "description": "False when anything was left un-walked or a write failed." }, "keysStillLive": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Live API keys that were minted under this mandate and are STILL ACTIVE. Revoking a mandate does not revoke what it minted (BLOCKED-ON-JAKE §27) — these must be revoked directly. Zero means none were minted under it, not that none were checked." } }, "required": [ "delegationsRevoked", "notWalked", "depth", "complete", "keysStillLive" ], "additionalProperties": false } }, "required": [ "revokedAt", "cascade" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Revoking the mandate also withdrew one delegation the agent had issued — and named the two API keys it minted, which are STILL LIVE and must be revoked directly.", "value": { "revokedAt": "2026-05-22T12:00:00.000Z", "cascade": { "delegationsRevoked": [ "delg_abc" ], "notWalked": [], "depth": 1, "complete": true, "keysStillLive": 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "agents.delete" ] }, { "OAuth2": [ "agents.delete" ] }, { "WorkspaceApiKey": [ "agents.delete" ] } ], "x-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent.mandate.revoked", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/agents.spiffe.bind": { "post": { "operationId": "agents_spiffe_bind", "summary": "Bind a SPIFFE ID to an agent DID so its JWT-SVIDs can attest as that agent.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": [ "jwt" ] } }, "required": [ "agentDid", "spiffeId", "svidType" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Bind SPIFFE workload to agent.", "value": { "agentDid": "did:web:agined.com:agents:ws_demo_default: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:agined.com:agents:ws_demo_default: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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "agents.create" ] }, { "OAuth2": [ "agents.create" ] }, { "WorkspaceApiKey": [ "agents.create" ] } ], "x-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent.spiffe.bound", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/agents.spiffe.unbind": { "post": { "operationId": "agents_spiffe_unbind", "summary": "Unbind a SPIFFE ID from its agent DID so its SVIDs stop attesting as that agent.", "x-agined-description-key": "actions.agents.spiffe.unbind.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "spiffeId": { "type": "string", "pattern": "^spiffe:\\/\\/[A-Za-z0-9.\\-]+(\\/[A-Za-z0-9._\\-/]*)?$" } }, "required": [ "spiffeId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Stop a decommissioned workload attesting as this agent.", "value": { "spiffeId": "spiffe://corp.example.com/svc/billing" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "spiffeId": { "type": "string", "pattern": "^spiffe:\\/\\/[A-Za-z0-9.\\-]+(\\/[A-Za-z0-9._\\-/]*)?$" }, "unboundAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?: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": [ "spiffeId", "unboundAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Stop a decommissioned workload attesting as this agent.", "value": { "spiffeId": "spiffe://corp.example.com/svc/billing", "unboundAt": "2026-08-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "agents.create" ] }, { "OAuth2": [ "agents.create" ] }, { "WorkspaceApiKey": [ "agents.create" ] } ], "x-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent.spiffe.unbound", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/agents.spiffe.workload.attest": { "post": { "operationId": "agents_spiffe_workload_attest", "summary": "Exchange a SPIFFE SVID for a short-lived DPoP-bound Agined session.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": { "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…" }, "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": "av_sess_demo…", "expiresAt": "2026-05-22T12:05:00.000Z", "agentDid": "did:web:agined.com:agents:ws_demo_default: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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent.spiffe.workload_attested", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List trusted A2A roots.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "agents.view" ] }, { "OAuth2": [ "agents.view" ] }, { "WorkspaceApiKey": [ "agents.view" ] } ], "x-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "agents.create" ] }, { "OAuth2": [ "agents.create" ] }, { "WorkspaceApiKey": [ "agents.create" ] } ], "x-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent.trusted_root.added", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/agents.trusted-roots.remove": { "post": { "operationId": "agents_trusted-roots_remove", "summary": "Remove a partner organization DID from the trusted-roots list for this workspace.", "x-agined-description-key": "actions.agents.trusted-roots.remove.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "did": { "type": "string", "pattern": "^did:web:[A-Za-z0-9.\\-_:%]+$" } }, "required": [ "workspaceId", "did" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Stop trusting a federated root.", "value": { "workspaceId": "ws_demo_default", "did": "did:web:partner.example.com" } } } } } }, "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.\\-_:%]+$" }, "removedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?: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", "removedAt" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Stop trusting a federated root.", "value": { "did": "did:web:partner.example.com", "removedAt": "2026-08-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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "agents.create" ] }, { "OAuth2": [ "agents.create" ] }, { "WorkspaceApiKey": [ "agents.create" ] } ], "x-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent.trusted_root.removed", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/fabric.retrieve.signed": { "post": { "operationId": "fabric_retrieve_signed", "summary": "Query the fabric and seal the result as a signed-retrieval receipt — the query hash plus every returned record's content hash, so a grounded claim can be proved after the fact.", "x-agined-description-key": "actions.fabric.retrieve.signed.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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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}$" }, "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": { "type": "integer", "minimum": 1, "maximum": 200 }, "embeddingModel": { "description": "The model that produced the grounding, when one did. Absent records `none/structured-query` — the fabric does not embed, and asserting a model would be a claim nobody made.", "type": "string" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Ground a claim on policy clauses, provably.", "value": { "workspaceId": "ws_demo_default", "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "sourceId": { "type": "string" }, "connectionId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "connectionLabel": { "type": "string" }, "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", "connectionLabel", "kind", "payload", "observedAt", "extractedAt", "contentHash", "anchorUrl" ], "additionalProperties": {} } }, "nextCursor": { "type": [ "string", "null" ] }, "retrieval": { "type": "object", "properties": { "retrievalRef": { "type": "string" }, "queryHash": { "type": "string", "description": "SHA-256 over the canonicalised FILTERS — not a rendered query string, which would differ over whitespace." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "sourceRef": { "type": "string" }, "contentSha256": { "type": "string", "description": "SHA-256 over the record's canonicalised payload, computed at retrieval time. Hashing the id instead would verify perfectly and prove nothing." }, "score": { "type": "number" } }, "required": [ "sourceRef", "contentSha256", "score" ], "additionalProperties": false } }, "retrievedAt": { "type": "string" }, "sealed": { "type": "boolean" }, "artifactId": { "type": [ "string", "null" ] }, "unsealedReason": { "description": "Why it could not be sealed, when it could not. Never a fabricated artifact id.", "type": [ "string", "null" ] } }, "required": [ "retrievalRef", "queryHash", "sources", "retrievedAt", "sealed", "artifactId", "unsealedReason" ], "additionalProperties": {} } }, "required": [ "records", "nextCursor", "retrieval" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Ground a claim on policy clauses, provably.", "value": { "records": [], "nextCursor": null, "retrieval": { "retrievalRef": "ret_…", "queryHash": "…", "sources": [], "retrievedAt": "2026-09-03T00:00:00.000Z", "sealed": true, "artifactId": "art_01J…", "unsealedReason": 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "records.view" ] }, { "OAuth2": [ "records.view" ] }, { "WorkspaceApiKey": [ "records.view" ] } ], "x-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "agent_invocation", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/fabric.memory.snapshot": { "post": { "operationId": "fabric_memory_snapshot", "summary": "Snapshot the fabric's records as a signed memory-attestation receipt — entry count, Merkle root over every entry's content hash, and the provenance window — so an export can be verified without trusting the exporter.", "x-agined-description-key": "actions.fabric.memory.snapshot.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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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}$" }, "since": { "description": "Only entries extracted at or after this instant. Narrows a memory too large to snapshot whole.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?: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": "Make an agent's memory portable and independently checkable.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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", "description": "The acting agent's DID, as verified by the gateway — never a caller-supplied value." }, "snapshotRef": { "type": "string" }, "entryCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "merkleRoot": { "type": "string", "description": "Domain-separated binary Merkle root over every entry's content hash, leaves in record-id order. An empty memory has the well-defined root SHA-256(\"\")." }, "earliestEntryAt": { "description": "Null when the memory is empty — no window, which is not the same as a zero-length one.", "type": [ "string", "null" ] }, "latestEntryAt": { "type": [ "string", "null" ] }, "snapshotAt": { "type": "string" }, "sealed": { "type": "boolean" }, "artifactId": { "type": [ "string", "null" ] }, "unsealedReason": { "description": "Why it could not be sealed, when it could not. The root is still returned — it is re-derivable from the export — but never a fabricated artifact id.", "type": [ "string", "null" ] } }, "required": [ "agentRef", "snapshotRef", "entryCount", "merkleRoot", "earliestEntryAt", "latestEntryAt", "snapshotAt", "sealed", "artifactId", "unsealedReason" ], "additionalProperties": {} } }, "required": [ "snapshot" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Make an agent's memory portable and independently checkable.", "value": { "snapshot": { "agentRef": "did:key:z6Mk…", "snapshotRef": "mem_…", "entryCount": 42, "merkleRoot": "…", "earliestEntryAt": "2026-08-01T00:00:00.000Z", "latestEntryAt": "2026-09-04T00:00:00.000Z", "snapshotAt": "2026-09-04T00:00:00.000Z", "sealed": true, "artifactId": "art_01J…", "unsealedReason": null } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "records.view" ] }, { "OAuth2": [ "records.view" ] }, { "WorkspaceApiKey": [ "records.view" ] } ], "x-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "mandate", "x-agined-rate-class": "billing", "x-agined-audit-kind": "agent_invocation", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/fabric.sources.catalog": { "post": { "operationId": "fabric_sources_catalog", "summary": "List the connectable source catalog — each source's category, purpose, auth method, and the engine classes it contributes.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": { "type": "string", "enum": [ "identity", "crm", "hris", "finance", "collab", "devtools", "endpoint" ] }, "purpose": { "type": "string", "enum": [ "catalogue", "inventory", "endpoint" ] }, "query": { "type": "string", "maxLength": 200 } }, "additionalProperties": false }, "examples": { "example_0": { "summary": "Browse developer-tool sources.", "value": { "category": "devtools" } } } } } }, "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" }, "category": { "type": "string", "enum": [ "identity", "crm", "hris", "finance", "collab", "devtools", "endpoint" ] }, "purpose": { "type": "array", "items": { "type": "string", "enum": [ "catalogue", "inventory", "endpoint" ] } }, "authMethod": { "type": "string", "enum": [ "oauth2", "api_key", "service_account" ] }, "contributes": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "available", "planned" ] }, "docsUrl": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "vendor", "category", "purpose", "authMethod", "contributes", "status", "docsUrl", "description" ], "additionalProperties": {} } } }, "required": [ "sources" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Browse developer-tool 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "integrations.view" ] }, { "OAuth2": [ "integrations.view" ] }, { "WorkspaceApiKey": [ "integrations.view" ] } ], "x-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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 }, "credential": { "type": "string", "maxLength": 8192 } }, "required": [ "workspaceId", "sourceId", "label" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Connect Jira — an OAuth source stays pending until its oauth/start → callback completes.", "value": { "workspaceId": "ws_demo_default", "sourceId": "jira", "label": "Acme Jira", "scope": [ "ACME" ], "syncSchedule": "daily" } } } } } }, "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "sourceId": { "type": "string" }, "category": { "type": "string", "enum": [ "identity", "crm", "hris", "finance", "collab", "devtools", "endpoint" ] }, "authMethod": { "type": "string", "enum": [ "oauth2", "api_key", "service_account" ] }, "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" } ] }, "connectionRef": { "type": [ "string", "null" ] }, "credentialRef": { "type": [ "string", "null" ] }, "syncSchedule": { "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": [ "connectionId", "workspaceId", "sourceId", "category", "authMethod", "label", "scope", "state", "syncState", "emits", "lastSyncAt", "connectionRef", "credentialRef", "syncSchedule", "createdAt" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Connect Jira — an OAuth source stays pending until its oauth/start → callback completes.", "value": { "connectionId": "01J9X4P9R7Z2C1A1F2A8VBJYS1", "workspaceId": "ws_demo_default", "sourceId": "jira", "category": "devtools", "authMethod": "oauth2", "label": "Acme Jira", "scope": [ "ACME" ], "state": "pending", "syncState": "never", "emits": [ "ticket" ], "lastSyncAt": null, "connectionRef": null, "credentialRef": null, "syncSchedule": "daily", "createdAt": "2026-05-22T12:00:00.000Z" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "integrations.connect" ] }, { "OAuth2": [ "integrations.connect" ] }, { "WorkspaceApiKey": [ "integrations.connect" ] } ], "x-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/fabric.connections.list": { "post": { "operationId": "fabric_connections_list", "summary": "List the workspace's fabric connections with their sync health.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "sourceId": { "type": "string" }, "category": { "type": "string", "enum": [ "identity", "crm", "hris", "finance", "collab", "devtools", "endpoint" ] } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "List connections.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "sourceId": { "type": "string" }, "category": { "type": "string", "enum": [ "identity", "crm", "hris", "finance", "collab", "devtools", "endpoint" ] }, "authMethod": { "type": "string", "enum": [ "oauth2", "api_key", "service_account" ] }, "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" } ] }, "connectionRef": { "type": [ "string", "null" ] }, "credentialRef": { "type": [ "string", "null" ] }, "syncSchedule": { "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": [ "connectionId", "workspaceId", "sourceId", "category", "authMethod", "label", "scope", "state", "syncState", "emits", "lastSyncAt", "connectionRef", "credentialRef", "syncSchedule", "createdAt" ], "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "integrations.view" ] }, { "OAuth2": [ "integrations.view" ] }, { "WorkspaceApiKey": [ "integrations.view" ] } ], "x-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/fabric.connections.sync": { "post": { "operationId": "fabric_connections_sync", "summary": "Enqueue an on-demand sync + re-extraction of a fabric connection.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "connectionId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "required": [ "workspaceId", "connectionId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Sync now.", "value": { "workspaceId": "ws_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "integrations.connect" ] }, { "OAuth2": [ "integrations.connect" ] }, { "WorkspaceApiKey": [ "integrations.connect" ] } ], "x-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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_demo_default", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "integrations.disconnect" ] }, { "OAuth2": [ "integrations.disconnect" ] }, { "WorkspaceApiKey": [ "integrations.disconnect" ] } ], "x-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/fabric.webhooks.list": { "post": { "operationId": "fabric_webhooks_list", "summary": "List the workspace's inbound webhook endpoints, with which sources can push and whether each scheme binds the body.", "x-agined-description-key": "actions.fabric.webhooks.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" } }, "required": [ "workspaceId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "What can push, and what has.", "value": { "workspaceId": "ws_demo_default" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "endpoints": { "type": "array", "items": { "type": "object", "properties": { "endpointId": { "type": "string" }, "workspaceId": { "type": "string", "pattern": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "connectionId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "sourceId": { "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))$" }, "lastEventAt": { "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" } ] }, "lastErrorAt": { "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" } ] }, "lastError": { "type": [ "string", "null" ] } }, "required": [ "endpointId", "workspaceId", "connectionId", "sourceId", "createdAt", "lastEventAt", "lastErrorAt", "lastError" ], "additionalProperties": false } }, "supportedSources": { "type": "array", "items": { "type": "object", "properties": { "sourceId": { "type": "string" }, "label": { "type": "string" }, "signatureHeader": { "type": "string" }, "bindsBody": { "type": "boolean" } }, "required": [ "sourceId", "label", "signatureHeader", "bindsBody" ], "additionalProperties": false } } }, "required": [ "endpoints", "supportedSources" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "What can push, and what has.", "value": { "endpoints": [], "supportedSources": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "integrations.view" ] }, { "OAuth2": [ "integrations.view" ] }, { "WorkspaceApiKey": [ "integrations.view" ] } ], "x-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/fabric.webhooks.open": { "post": { "operationId": "fabric_webhooks_open", "summary": "Open an inbound webhook endpoint for a connection — returns the signing secret ONCE.", "x-agined-description-key": "actions.fabric.webhooks.open.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "connectionId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" } }, "required": [ "workspaceId", "connectionId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Open an endpoint for a GitHub connection.", "value": { "workspaceId": "ws_demo_default", "connectionId": "01J9X4P9R7Z2C1A1F2A8VBJYS1" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "endpointId": { "type": "string" }, "sourceId": { "type": "string" }, "deliveryPath": { "type": "string" }, "signatureHeader": { "type": "string" }, "secret": { "type": "string" } }, "required": [ "endpointId", "sourceId", "deliveryPath", "signatureHeader", "secret" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Open an endpoint for a GitHub connection.", "value": { "endpointId": "01J9X4P9R7Z2C1A1F2A8VBJYS2", "sourceId": "github", "deliveryPath": "/api/v1/fabric/deliveries/01J9X4P9R7Z2C1A1F2A8VBJYS2", "signatureHeader": "x-hub-signature-256", "secret": "shown-once" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "integrations.connect" ] }, { "OAuth2": [ "integrations.connect" ] }, { "WorkspaceApiKey": [ "integrations.connect" ] } ], "x-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/fabric.webhooks.revoke": { "post": { "operationId": "fabric_webhooks_revoke", "summary": "Revoke an inbound webhook endpoint — deliveries to it stop immediately.", "x-agined-description-key": "actions.fabric.webhooks.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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "endpointId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "workspaceId", "endpointId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Stop accepting pushes.", "value": { "workspaceId": "ws_demo_default", "endpointId": "01J9X4P9R7Z2C1A1F2A8VBJYS2" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "revoked": { "type": "boolean" }, "endpointId": { "type": "string" } }, "required": [ "revoked", "endpointId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Stop accepting pushes.", "value": { "revoked": true, "endpointId": "01J9X4P9R7Z2C1A1F2A8VBJYS2" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "integrations.disconnect" ] }, { "OAuth2": [ "integrations.disconnect" ] }, { "WorkspaceApiKey": [ "integrations.disconnect" ] } ], "x-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "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": [ "tools", "actionflow", "norman", "magazine" ] }, "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_demo_default", "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": "^(?:agn-ws|ws)_[A-Za-z0-9_-]{11,}$" }, "sourceId": { "type": "string" }, "connectionId": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "connectionLabel": { "type": "string" }, "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", "connectionLabel", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "records.view" ] }, { "OAuth2": [ "records.view" ] }, { "WorkspaceApiKey": [ "records.view" ] } ], "x-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": [ "tools", "actionflow", "norman", "magazine" ] } }, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "Rate-limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "BearerPat": [ "integrations.view" ] }, { "OAuth2": [ "integrations.view" ] }, { "WorkspaceApiKey": [ "integrations.view" ] } ], "x-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/actionflow.flows.list": { "post": { "operationId": "actionflow_flows_list", "summary": "List the workspace's ActionFlow flows.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": { "flows": { "type": "array", "items": { "type": "object", "properties": { "schemaVersion": { "type": "string" }, "id": { "type": "string" }, "workspaceId": { "type": "string" }, "tenantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "source": { "type": "object", "properties": {}, "additionalProperties": {} }, "triggers": { "type": "array", "items": {} }, "steps": { "type": "array", "items": {} }, "version": { "type": "object", "properties": { "semver": { "type": "string" }, "status": { "type": "string" }, "publishedAt": { "type": "string" } }, "required": [ "semver", "status" ], "additionalProperties": {} }, "authoredBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "schemaVersion", "id", "workspaceId", "name", "tags", "source", "triggers", "steps", "version", "createdAt", "updatedAt" ], "additionalProperties": {} } } }, "required": [ "flows" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "List flows.", "value": { "flows": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/actionflow.flows.run": { "post": { "operationId": "actionflow_flows_run", "summary": "Run a flow — trigger an execution through the bounded graph engine.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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." }, "mode": { "description": "Sandbox runs execute the graph without real side effects (default real).", "type": "string", "enum": [ "real", "sandbox" ] }, "async": { "description": "true → queue-backed run: returns a 'queued' execution immediately; poll executions.list for state. Default runs inline.", "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Run the incident flow.", "value": { "id": "flow_incident", "input": { "severity": "high" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "execution": { "type": "object", "properties": { "executionId": { "type": "string" }, "flowId": { "type": "string" }, "flowVersion": { "type": [ "string", "null" ] }, "workspaceId": { "type": "string" }, "initiatedBy": { "type": "object", "properties": {}, "additionalProperties": {} }, "triggeredBy": { "type": "object", "properties": {}, "additionalProperties": {} }, "status": { "type": "string" }, "stepStates": { "type": "object", "properties": {}, "additionalProperties": {} }, "result": {}, "error": {}, "mode": { "type": "string" }, "startedAt": { "type": "string" }, "completedAt": { "type": "string" }, "waiting": { "type": "boolean" } }, "required": [ "executionId", "flowId", "workspaceId", "initiatedBy", "triggeredBy", "status", "stepStates", "mode", "startedAt", "waiting" ], "additionalProperties": {} } }, "required": [ "execution" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Run the incident flow.", "value": { "execution": { "executionId": "exec_…", "flowId": "flow_incident", "workspaceId": "ws_…", "initiatedBy": {}, "triggeredBy": {}, "status": "succeeded", "stepStates": {}, "mode": "real", "startedAt": "2026-08-10T00:00:00Z", "waiting": 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_invocation", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/actionflow.flows.publish": { "post": { "operationId": "actionflow_flows_publish", "summary": "Publish a flow (make the current draft the live version).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": { "flow": { "type": "object", "properties": { "schemaVersion": { "type": "string" }, "id": { "type": "string" }, "workspaceId": { "type": "string" }, "tenantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "source": { "type": "object", "properties": {}, "additionalProperties": {} }, "triggers": { "type": "array", "items": {} }, "steps": { "type": "array", "items": {} }, "version": { "type": "object", "properties": { "semver": { "type": "string" }, "status": { "type": "string" }, "publishedAt": { "type": "string" } }, "required": [ "semver", "status" ], "additionalProperties": {} }, "authoredBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "schemaVersion", "id", "workspaceId", "name", "tags", "source", "triggers", "steps", "version", "createdAt", "updatedAt" ], "additionalProperties": {} } }, "required": [ "flow" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Publish a flow.", "value": { "flow": { "schemaVersion": "1.0", "id": "flow_incident", "workspaceId": "ws_…", "name": "Incident flow", "tags": [], "source": {}, "triggers": [], "steps": [], "version": { "semver": "0.1.0", "status": "published" }, "createdAt": "2026-08-10T00:00:00Z", "updatedAt": "2026-08-10T00:00:00Z" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_invocation", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/actionflow.flows.deprecate": { "post": { "operationId": "actionflow_flows_deprecate", "summary": "Retire a published flow. It stops running on its triggers; its execution history is kept.", "x-agined-description-key": "actions.actionflow.flows.deprecate.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "Retire a published 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": { "flow": { "type": "object", "properties": { "schemaVersion": { "type": "string" }, "id": { "type": "string" }, "workspaceId": { "type": "string" }, "tenantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "source": { "type": "object", "properties": {}, "additionalProperties": {} }, "triggers": { "type": "array", "items": {} }, "steps": { "type": "array", "items": {} }, "version": { "type": "object", "properties": { "semver": { "type": "string" }, "status": { "type": "string" }, "publishedAt": { "type": "string" } }, "required": [ "semver", "status" ], "additionalProperties": {} }, "authoredBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "schemaVersion", "id", "workspaceId", "name", "tags", "source", "triggers", "steps", "version", "createdAt", "updatedAt" ], "additionalProperties": {} } }, "required": [ "flow" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Retire a published flow.", "value": { "flow": { "schemaVersion": "1.0", "id": "flow_incident", "workspaceId": "ws_…", "name": "Incident flow", "tags": [], "source": {}, "triggers": [], "steps": [], "version": { "semver": "1.0.0", "status": "deprecated", "deprecatedAt": "2026-08-24T12:00:00Z" }, "createdAt": "2026-08-10T00:00:00Z", "updatedAt": "2026-08-24T12:00:00Z" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_invocation", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/actionflow.templates.list": { "post": { "operationId": "actionflow_templates_list", "summary": "List the ActionFlow starter templates.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": { "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "description", "tags" ], "additionalProperties": {} } } }, "required": [ "templates" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Browse templates.", "value": { "templates": [ { "id": "tmpl_incident_alert", "name": "Sentinel incident → alert", "description": "When Sentinel opens a high-severity incident, emit an alert webhook.", "tags": [ "security", "alerting" ] } ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/actionflow.templates.instantiate": { "post": { "operationId": "actionflow_templates_instantiate", "summary": "Instantiate a template into a new draft flow in the workspace.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": { "flow": { "type": "object", "properties": { "schemaVersion": { "type": "string" }, "id": { "type": "string" }, "workspaceId": { "type": "string" }, "tenantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "source": { "type": "object", "properties": {}, "additionalProperties": {} }, "triggers": { "type": "array", "items": {} }, "steps": { "type": "array", "items": {} }, "version": { "type": "object", "properties": { "semver": { "type": "string" }, "status": { "type": "string" }, "publishedAt": { "type": "string" } }, "required": [ "semver", "status" ], "additionalProperties": {} }, "authoredBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "schemaVersion", "id", "workspaceId", "name", "tags", "source", "triggers", "steps", "version", "createdAt", "updatedAt" ], "additionalProperties": {} } }, "required": [ "flow" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Create a flow from a template.", "value": { "flow": { "schemaVersion": "1.0", "id": "flow_…", "workspaceId": "ws_…", "name": "My incident flow", "tags": [ "security", "alerting" ], "source": {}, "triggers": [], "steps": [], "version": { "semver": "0.1.0", "status": "draft" }, "createdAt": "2026-08-10T00:00:00Z", "updatedAt": "2026-08-10T00:00:00Z" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_invocation", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/actionflow.executions.list": { "post": { "operationId": "actionflow_executions_list", "summary": "List recent ActionFlow executions.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": { "executions": { "type": "array", "items": { "type": "object", "properties": { "executionId": { "type": "string" }, "flowId": { "type": "string" }, "flowVersion": { "type": [ "string", "null" ] }, "workspaceId": { "type": "string" }, "initiatedBy": { "type": "object", "properties": {}, "additionalProperties": {} }, "triggeredBy": { "type": "object", "properties": {}, "additionalProperties": {} }, "status": { "type": "string" }, "stepStates": { "type": "object", "properties": {}, "additionalProperties": {} }, "result": {}, "error": {}, "mode": { "type": "string" }, "startedAt": { "type": "string" }, "completedAt": { "type": "string" }, "waiting": { "type": "boolean" } }, "required": [ "executionId", "flowId", "workspaceId", "initiatedBy", "triggeredBy", "status", "stepStates", "mode", "startedAt", "waiting" ], "additionalProperties": {} } } }, "required": [ "executions" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "List executions.", "value": { "executions": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/lens.list": { "post": { "operationId": "lens_list", "summary": "List the available compliance-evidence lenses.", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": { "lenses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "framework": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "custom": { "type": "boolean" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "kind": { "type": "string" } }, "required": [ "id", "title", "kind" ], "additionalProperties": {} } } }, "required": [ "id", "name", "version", "description", "category", "source", "custom" ], "additionalProperties": {} } } }, "required": [ "lenses" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Browse lenses.", "value": { "lenses": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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 GDPR lens.", "value": { "id": "lens_gdpr_art30", "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": { "ok": { "type": "boolean" }, "resultId": { "type": "string" }, "signed": { "type": "boolean" }, "bundle": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "ok" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Run a GDPR lens.", "value": { "ok": true, "resultId": "lres_…", "signed": true, "bundle": {} } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "agent_invocation", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/lens.validate": { "post": { "operationId": "lens_validate", "summary": "Validate a lens definition (dry-run; no evidence bundle, no charge).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "gdpr" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ok": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "ok" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Validate a lens.", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/lens.results.list": { "post": { "operationId": "lens_results_list", "summary": "List prior lens-execution results (the evidence-bundle history).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "lensId": { "type": "string" }, "lensVersion": { "type": "string" }, "contentHash": { "type": "string" }, "executedAt": { "type": "string" }, "rangeStart": { "type": [ "string", "null" ] }, "rangeEnd": { "type": [ "string", "null" ] }, "signed": { "type": "boolean" }, "jurisdiction": { "type": [ "string", "null" ] }, "signingKeyId": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "otsProofId": { "type": [ "string", "null" ] }, "btcBlockHeight": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "lensId", "lensVersion", "contentHash", "executedAt", "signed", "status" ], "additionalProperties": {} } } }, "required": [ "results" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "List evidence bundles.", "value": { "results": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/lens.custom.list": { "post": { "operationId": "lens_custom_list", "summary": "List the custom lenses this workspace has authored.", "x-agined-description-key": "actions.lens.custom.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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 the workspace's own lenses.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "lenses": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "updatedAt": { "type": "string" }, "definition": {} }, "required": [ "id", "updatedAt", "definition" ], "additionalProperties": {} } } }, "required": [ "lenses" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Browse the workspace's own lenses.", "value": { "lenses": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/lens.custom.get": { "post": { "operationId": "lens_custom_get", "summary": "Read one custom lens definition.", "x-agined-description-key": "actions.lens.custom.get.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "Read one.", "value": { "id": "lensc_…" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "updatedAt": { "type": "string" }, "definition": {} }, "required": [ "id", "updatedAt", "definition" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Read one.", "value": { "id": "lensc_…", "updatedAt": "2026-08-24T12:00:00.000Z", "definition": {} } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/lens.custom.create": { "post": { "operationId": "lens_custom_create", "summary": "Author a custom lens. The runtime sanitises the definition and refuses an invalid one with the specific errors.", "x-agined-description-key": "actions.lens.custom.create.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": {} }, "required": [ "definition" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Author a lens.", "value": { "definition": {} } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ok": { "type": "boolean" }, "id": { "type": "string" }, "definition": {} }, "required": [ "ok", "id", "definition" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Author a lens.", "value": { "ok": true, "id": "lensc_…", "definition": {} } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_invocation", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/lens.custom.update": { "post": { "operationId": "lens_custom_update", "summary": "Replace a custom lens definition.", "x-agined-description-key": "actions.lens.custom.update.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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 }, "definition": {} }, "required": [ "id", "definition" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Revise a lens.", "value": { "id": "lensc_…", "definition": {} } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ok": { "type": "boolean" }, "id": { "type": "string" }, "definition": {} }, "required": [ "ok", "id", "definition" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Revise a lens.", "value": { "ok": true, "id": "lensc_…", "definition": {} } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_invocation", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/lens.custom.delete": { "post": { "operationId": "lens_custom_delete", "summary": "Delete a custom lens. Its past results keep the definition hash they were produced under.", "x-agined-description-key": "actions.lens.custom.delete.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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "Remove a lens the workspace authored.", "value": { "id": "lensc_…" } } } } } }, "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": "Remove a lens the workspace authored.", "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_invocation", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/lens.marketplace.list": { "post": { "operationId": "lens_marketplace_list", "summary": "Browse the lens marketplace, with what this workspace has published and installed.", "x-agined-description-key": "actions.lens.marketplace.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": "What is available, and what I have.", "value": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "listings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "publisherWorkspaceId": { "type": "string" }, "sourceLensId": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "version": { "type": "string" }, "publishedAt": { "type": "string" }, "unpublishedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "publisherWorkspaceId", "sourceLensId", "name", "summary", "version", "publishedAt", "unpublishedAt" ], "additionalProperties": false } }, "published": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "publisherWorkspaceId": { "type": "string" }, "sourceLensId": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "version": { "type": "string" }, "publishedAt": { "type": "string" }, "unpublishedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "publisherWorkspaceId", "sourceLensId", "name", "summary", "version", "publishedAt", "unpublishedAt" ], "additionalProperties": false } }, "installs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "listingId": { "type": "string" }, "version": { "type": "string" }, "installedLensId": { "type": "string" }, "installedAt": { "type": "string" } }, "required": [ "id", "listingId", "version", "installedLensId", "installedAt" ], "additionalProperties": false } } }, "required": [ "listings", "published", "installs" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "What is available, and what I have.", "value": { "listings": [], "published": [], "installs": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/lens.marketplace.publish": { "post": { "operationId": "lens_marketplace_publish", "summary": "Publish one of the workspace's own custom lenses at its pinned version. Enterprise only.", "x-agined-description-key": "actions.lens.marketplace.publish.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "lensId": { "type": "string", "minLength": 1 }, "summary": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "lensId", "summary" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Share a lens.", "value": { "lensId": "clens_…", "summary": "Counts sign-ins on the audit chain." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "listing": { "type": "object", "properties": { "id": { "type": "string" }, "publisherWorkspaceId": { "type": "string" }, "sourceLensId": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string" }, "version": { "type": "string" }, "publishedAt": { "type": "string" }, "unpublishedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "publisherWorkspaceId", "sourceLensId", "name", "summary", "version", "publishedAt", "unpublishedAt" ], "additionalProperties": false } }, "required": [ "listing" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Share a lens.", "value": { "listing": { "id": "llist_…", "publisherWorkspaceId": "ws_1", "sourceLensId": "clens_…", "name": "Sign-in review", "summary": "Counts sign-ins on the audit chain.", "version": "1.0.0", "publishedAt": "2026-09-02T00:00:00.000Z", "unpublishedAt": null } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_invocation", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/lens.marketplace.unpublish": { "post": { "operationId": "lens_marketplace_unpublish", "summary": "Withdraw a listing. It leaves the catalogue; workspaces that already installed it keep the lens.", "x-agined-description-key": "actions.lens.marketplace.unpublish.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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "listingId": { "type": "string", "minLength": 1 } }, "required": [ "listingId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Stop offering it.", "value": { "listingId": "llist_…" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "unpublished": { "type": "boolean" }, "listingId": { "type": "string" } }, "required": [ "unpublished", "listingId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Stop offering it.", "value": { "unpublished": true, "listingId": "llist_…" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_invocation", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/lens.marketplace.install": { "post": { "operationId": "lens_marketplace_install", "summary": "Install a listing into this workspace as a custom lens, pinned to the published version.", "x-agined-description-key": "actions.lens.marketplace.install.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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "listingId": { "type": "string", "minLength": 1 } }, "required": [ "listingId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Take a shared lens.", "value": { "listingId": "llist_…" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "install": { "type": "object", "properties": { "id": { "type": "string" }, "listingId": { "type": "string" }, "version": { "type": "string" }, "installedLensId": { "type": "string" }, "installedAt": { "type": "string" } }, "required": [ "id", "listingId", "version", "installedLensId", "installedAt" ], "additionalProperties": false }, "alreadyInstalled": { "type": "boolean" } }, "required": [ "install", "alreadyInstalled" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Take a shared lens.", "value": { "install": { "id": "linst_…", "listingId": "llist_…", "version": "1.0.0", "installedLensId": "clens_…", "installedAt": "2026-09-02T00:00:00.000Z" }, "alreadyInstalled": 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_invocation", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/lens.marketplace.uninstall": { "post": { "operationId": "lens_marketplace_uninstall", "summary": "Remove an installed lens and its install receipt together — the inverse of install.", "x-agined-description-key": "actions.lens.marketplace.uninstall.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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. The gateway rejects mismatched proofs." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "listingId": { "type": "string", "minLength": 1 } }, "required": [ "listingId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Give a shared lens back.", "value": { "listingId": "llist_…" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "uninstalled": { "type": "boolean" }, "listingId": { "type": "string" } }, "required": [ "uninstalled", "listingId" ], "additionalProperties": false }, "examples": { "example_0": { "summary": "Give a shared lens back.", "value": { "uninstalled": true, "listingId": "llist_…" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "destructive", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_invocation", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-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": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": { "ok": { "type": "boolean" }, "bundle": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "ok" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Seal a signed snapshot.", "value": { "ok": true, "bundle": {} } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "billing_impacting", "x-agined-confirmation-policy": "always", "x-agined-rate-class": "billing", "x-agined-audit-kind": "agent_invocation", "x-agined-idempotent": false, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/notarian.verify-chain": { "post": { "operationId": "notarian_verify-chain", "summary": "Verify the Notarian transparency chain (free — a transparency guarantee).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": {} } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ok": { "type": "boolean" }, "verification": { "type": "object", "properties": { "ok": { "type": "boolean" }, "workspaceId": { "type": "string" }, "checkedCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "tipHash": { "type": [ "string", "null" ] } }, "required": [ "ok" ], "additionalProperties": {} } }, "required": [ "ok", "verification" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Prove the chain is intact.", "value": { "ok": true, "verification": { "ok": true, "checkedCount": 0, "tipHash": 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/v1/actions/notarian.anchors.list": { "post": { "operationId": "notarian_anchors_list", "summary": "List the Notarian anchors (the published chain checkpoints).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": { "anchors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": "string" }, "ledgerSha256": { "type": "string" }, "snapshottedAt": { "type": "string" }, "otsProofId": { "type": [ "string", "null" ] }, "btcBlockHeight": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "type": "string" }, "source": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "recordCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rangeStart": { "type": [ "string", "null" ] }, "rangeEnd": { "type": [ "string", "null" ] }, "jurisdiction": { "type": [ "string", "null" ] }, "bundleId": { "type": "string" } }, "required": [ "id", "workspaceId", "ledgerSha256", "snapshottedAt", "status", "source" ], "additionalProperties": {} } } }, "required": [ "anchors" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "List anchors.", "value": { "anchors": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": { "frameworks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "tagline": { "type": "string" }, "category": { "type": "string" }, "runtime": { "type": "string" }, "status": { "type": "string" }, "integrationPattern": { "type": "string" }, "sdkPackage": { "type": [ "string", "null" ] }, "sdkVersion": { "type": [ "string", "null" ] }, "integrationDocHref": { "type": [ "string", "null" ] }, "upstreamHref": { "type": [ "string", "null" ] }, "coverage": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "category", "status" ], "additionalProperties": {} } }, "counts": { "type": "object", "properties": { "stable": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "beta": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "comingSoon": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "stable", "beta", "comingSoon", "total" ], "additionalProperties": {} } }, "required": [ "frameworks" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "All stable frameworks.", "value": { "frameworks": [], "counts": { "stable": 0, "beta": 0, "comingSoon": 0, "total": 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": { "framework": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "tagline": { "type": "string" }, "category": { "type": "string" }, "runtime": { "type": "string" }, "status": { "type": "string" }, "integrationPattern": { "type": "string" }, "sdkPackage": { "type": [ "string", "null" ] }, "sdkVersion": { "type": [ "string", "null" ] }, "integrationDocHref": { "type": [ "string", "null" ] }, "upstreamHref": { "type": [ "string", "null" ] }, "coverage": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "category", "status" ], "additionalProperties": {} } }, "required": [ "framework" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "LangChain's catalog entry.", "value": { "framework": { "id": "langchain", "name": "LangChain", "category": "orchestration", "status": "beta" } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": { "patterns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "setup": { "type": "string" } }, "required": [ "id", "label", "setup" ], "additionalProperties": {} } } }, "required": [ "patterns" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "The pattern catalog.", "value": { "patterns": [] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": { "subscriptions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "subscriptions" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "The WITNESS_SUBSCRIPTIONS routing matrix.", "value": { "subscriptions": {} } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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 enrollment required).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": { "records": { "type": "array", "items": { "type": "object", "properties": { "recordId": { "type": "string" }, "workspaceId": { "type": "string" }, "agentId": { "type": "string" }, "event": { "type": "string" }, "frameworkId": { "type": "string" }, "pattern": { "type": "string" }, "actorRunId": { "type": "string" }, "contentHash": { "type": "string" }, "record": { "type": "object", "properties": {}, "additionalProperties": {} }, "occurredAt": { "type": "string" }, "broadcastAt": { "type": "string" }, "storedAt": { "type": "string" } }, "required": [ "recordId", "workspaceId", "agentId", "event", "frameworkId", "pattern", "actorRunId", "contentHash", "record", "occurredAt", "broadcastAt", "storedAt" ], "additionalProperties": {} } }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "nextCursor": { "anyOf": [ { "type": "object", "properties": { "before": { "type": "string" }, "beforeId": { "type": "string" } }, "required": [ "before", "beforeId" ], "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "records" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Latest CrewAI records.", "value": { "records": [], "count": 0, "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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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 Agined's Tops chain — use the ingest lane for evidentiary anchoring).", "x-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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" } } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "recordId": { "type": "string" }, "deduplicated": { "type": "boolean" }, "chainAnchored": { "type": "boolean" }, "delivery": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "recordId", "deduplicated", "chainAnchored" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Neutral-plane record post.", "value": { "recordId": "wr_demo00000000000000000000", "deduplicated": false, "chainAnchored": 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-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "mutation", "x-agined-confirmation-policy": "ask", "x-agined-rate-class": "default", "x-agined-audit-kind": null, "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } }, "/api/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-agined-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-Agined-Confirmation", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^conf_[0-9A-Z]{20,}$" }, "description": "Step-up confirmation token, obtained from a prior 412 challenge or from the dashboard's elevation flow." }, { "name": "Agined-Workspace-Id", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^ws_[0-9A-Z]{20,}$" }, "description": "Active workspace id. Required for any workspace-scoped action." }, { "name": "DPoP", "in": "header", "required": false, "schema": { "type": "string" }, "description": "RFC 9449 DPoP proof JWS — required when calling with a DPoP-bound token. 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": { "stats": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "byFramework": { "type": "array", "items": { "type": "object", "properties": { "frameworkId": { "type": "string" }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "frameworkId", "count" ], "additionalProperties": {} } }, "byPattern": { "type": "array", "items": { "type": "object", "properties": { "pattern": { "type": "string" }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "pattern", "count" ], "additionalProperties": {} } }, "byEvent": { "type": "array", "items": { "type": "object", "properties": { "event": { "type": "string" }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "event", "count" ], "additionalProperties": {} } } }, "required": [ "total", "byFramework", "byPattern", "byEvent" ], "additionalProperties": {} } }, "required": [ "stats" ], "additionalProperties": {} }, "examples": { "example_0": { "summary": "Stream aggregates for dashboards.", "value": { "stats": { "total": 0, "byFramework": [], "byPattern": [], "byEvent": [] } } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — missing permission or kill-switch active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Confirmation required. Obtain `X-Agined-Confirmation` and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmationRequired" } } } }, "429": { "description": "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-agined-safety-level": "read", "x-agined-confirmation-policy": "none", "x-agined-rate-class": "default", "x-agined-audit-kind": "agent_read", "x-agined-idempotent": true, "x-agined-surfaces": [ "rest", "mcp", "chatgpt_app", "gemini", "perplexity", "claude_cowork", "claude_skill", "a2a", "nlweb" ] } } }, "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": "Agined PAT (av_pat_*)", "description": "Personal access token. Scopes are derived from the actor's org + workspace roles." }, "OAuth2": { "type": "oauth2", "description": "OAuth 2.1 + PKCE — for agentic apps acting on behalf of an Agined user.", "flows": { "authorizationCode": { "authorizationUrl": "https://agined.com/auth/authorize", "tokenUrl": "https://api.agined.com/api/v1/oauth/token", "scopes": { "organization.rename": "Grants the `organization.rename` permission.", "billing.view": "Grants the `billing.view` permission.", "members.view": "Grants the `members.view` permission.", "members.invite": "Grants the `members.invite` permission.", "members.remove": "Grants the `members.remove` permission.", "members.change_role": "Grants the `members.change_role` permission.", "organization.transfer_ownership": "Grants the `organization.transfer_ownership` permission.", "organization.delete": "Grants the `organization.delete` permission.", "settings.view_audit_log": "Grants the `settings.view_audit_log` permission.", "settings.configure_sso": "Grants the `settings.configure_sso` permission.", "workspaces.view": "Grants the `workspaces.view` permission.", "workspaces.create": "Grants the `workspaces.create` permission.", "settings.view": "Grants the `settings.view` permission.", "workspace.rename": "Grants the `workspace.rename` permission.", "workspaces.delete": "Grants the `workspaces.delete` permission.", "workspace.schedule_deletion": "Grants the `workspace.schedule_deletion` permission.", "workspaces.transfer": "Grants the `workspaces.transfer` permission.", "billing.change_plan": "Grants the `billing.change_plan` permission.", "billing.buy_pack": "Grants the `billing.buy_pack` permission.", "billing.configure_autotopup": "Grants the `billing.configure_autotopup` permission.", "billing.subscribe_addons": "Grants the `billing.subscribe_addons` permission.", "keys.view": "Grants the `keys.view` permission.", "keys.create": "Grants the `keys.create` permission.", "keys.revoke": "Grants the `keys.revoke` permission.", "webhooks.view": "Grants the `webhooks.view` permission.", "webhooks.create": "Grants the `webhooks.create` permission.", "webhooks.delete": "Grants the `webhooks.delete` permission.", "exports.view": "Grants the `exports.view` permission.", "exports.create": "Grants the `exports.create` permission.", "exports.download": "Grants the `exports.download` permission.", "settings.edit_retention": "Grants the `settings.edit_retention` permission.", "settings.edit_integrations": "Grants the `settings.edit_integrations` permission.", "settings.edit_capabilities": "Grants the `settings.edit_capabilities` permission.", "attestor.attest.agent-call": "Grants the `attestor.attest.agent-call` permission.", "attestor.attest.content": "Grants the `attestor.attest.content` permission.", "attestor.attest.llm": "Grants the `attestor.attest.llm` permission.", "attestor.attest.commit": "Grants the `attestor.attest.commit` permission.", "attestor.deliver.webhook": "Grants the `attestor.deliver.webhook` permission.", "attestor.monitors.create": "Grants the `attestor.monitors.create` permission.", "attestor.monitors.view": "Grants the `attestor.monitors.view` permission.", "attestor.monitors.delete": "Grants the `attestor.monitors.delete` permission.", "attestor.dns.create": "Grants the `attestor.dns.create` permission.", "attestor.dns.view": "Grants the `attestor.dns.view` permission.", "attestor.dns.delete": "Grants the `attestor.dns.delete` permission.", "attestor.tls.create": "Grants the `attestor.tls.create` permission.", "attestor.tls.view": "Grants the `attestor.tls.view` permission.", "attestor.tls.delete": "Grants the `attestor.tls.delete` permission.", "attestor.receipts.view": "Grants the `attestor.receipts.view` permission.", "attestor.usage.view": "Grants the `attestor.usage.view` permission.", "attestor.subscription.view": "Grants the `attestor.subscription.view` permission.", "attestor.abuse.view": "Grants the `attestor.abuse.view` permission.", "attestor.abuse.appeal": "Grants the `attestor.abuse.appeal` permission.", "agents.create": "Grants the `agents.create` permission.", "agents.view": "Grants the `agents.view` permission.", "agents.delete": "Grants the `agents.delete` permission.", "records.view": "Grants the `records.view` permission.", "integrations.view": "Grants the `integrations.view` permission.", "integrations.connect": "Grants the `integrations.connect` permission.", "integrations.disconnect": "Grants the `integrations.disconnect` permission." } } } }, "WorkspaceApiKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Workspace-scoped API key. Prefixed `av_*` (control plane) or `atst_*` (Attestor data plane)." } } } }