{ "openapi": "3.1.0", "info": { "title": "1Claw API", "version": "0.58.0", "description": "Secure secret management for AI agents. Provides vaults, secrets,\npolicy-based access control, agent identity, Intents API,\nsharing, billing, and audit logging. Automations (workflow_spec,\nwebhook tokens, event triggers, Assist), cloud runtimes with\ninteractive shell sessions, agent memory, and discovery.\n\nAll endpoints require JWT Bearer authentication unless marked with\n`security: []`.\n", "contact": { "email": "ops@1claw.xyz" } }, "servers": [ { "url": "http://localhost:8443", "description": "Development" }, { "url": "https://api.1claw.xyz", "description": "Production" }, { "url": "https://shroud.1claw.xyz", "description": "Shroud TEE Proxy (Intents API + LLM proxy)" } ], "x-agentcash-guidance": { "llmsTxtUrl": "https://1claw.xyz/llms.txt" }, "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Authentication", "description": "Credential exchange, MFA, device auth, token management" }, { "name": "API Keys", "description": "Personal API key management" }, { "name": "Vaults", "description": "Vault lifecycle operations" }, { "name": "Secrets", "description": "Secret CRUD within vaults" }, { "name": "Policies", "description": "Access policy management" }, { "name": "Agents", "description": "Agent identity and key management" }, { "name": "Transactions", "description": "Intents API (signing, simulation)" }, { "name": "Chains", "description": "Blockchain chain registry" }, { "name": "Sharing", "description": "Secret sharing links" }, { "name": "Organization", "description": "Org membership and roles" }, { "name": "Billing", "description": "Subscriptions, credits, and usage" }, { "name": "Audit", "description": "Immutable audit event log" }, { "name": "Security", "description": "IP rules and security configuration" }, { "name": "Treasury", "description": "Multi-sig treasury wallets (Safe) and agent access requests" }, { "name": "Treasury Wallets", "description": "Multi-chain wallet generation for human users (replaces CDP embedded wallets)" }, { "name": "Admin", "description": "Platform administration" }, { "name": "Health", "description": "Service health checks" }, { "name": "Approvals", "description": "Human-in-the-loop approval workflow for agent actions" }, { "name": "Signing Keys", "description": "Per-agent multi-chain signing key management" }, { "name": "Webhooks", "description": "Event webhook registration and management" }, { "name": "Platform", "description": "Platform API for developers building on 1Claw (plt_ keys, user provisioning, bootstrap templates)" }, { "name": "OAuth", "description": "OAuth 2.0 authorization server (PKCE, consent, token exchange, OIDC UserInfo)" }, { "name": "Risk Engine", "description": "Risk events, verdicts, and honeytoken management" }, { "name": "Tokens", "description": "Known token registry for guardrail enforcement" }, { "name": "Execution Intents", "description": "Execute HTTP calls, queries, and more through pre-configured bindings" }, { "name": "Payment Cards", "description": "Order prepaid/gift cards via x402, then reveal, refresh, and void them" }, { "name": "Automations", "description": "Scheduled, webhook-triggered, and on-demand automation workflows" }, { "name": "Runtimes", "description": "Cloud runtime containers for hosting AI agents" }, { "name": "Agent Memory", "description": "Agent memory storage (scratch, durable, semantic)" }, { "name": "Discovery", "description": "Agent directory and platform marketplace" }, { "name": "Agent Chat", "description": "Chat with agents via Shroud LLM proxy" }, { "name": "Agent Channels", "description": "External messaging channels (Telegram, WhatsApp, Discord)" }, { "name": "OAuth Connect", "description": "OAuth connected accounts for agents (provider registry, connect flows, app credentials)" }, { "name": "Delegations", "description": "Agent-to-agent delegation management (human-controlled authorization)" }, { "name": "Cedar Policies", "description": "Cedar policy engine (Team+ tier)" }, { "name": "OPA Policies", "description": "OPA policy engine (Business+ tier)" }, { "name": "Contract ABIs", "description": "Org-scoped contract ABI registry for transaction decoding" }, { "name": "Pending Approvals", "description": "Consensus-based multi-party approval workflow for signing" }, { "name": "Sub-Organizations", "description": "Sub-organization management" }, { "name": "Portfolio", "description": "Unified balance aggregator" }, { "name": "Environment Variables", "description": "Per-vault and org-shared environment variable management" }, { "name": "Wallet Access", "description": "Role-based wallet access policies for agents and users" }, { "name": "Credential Recovery", "description": "MFA/passkey/password recovery escape hatch with admin approval" }, { "name": "Shamir KEK", "description": "Shamir secret-sharing for org-level Key Encryption Keys" } ], "paths": { "/v1/auth/token": { "post": { "tags": [ "Authentication" ], "summary": "Login with email and password", "operationId": "login", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "responses": { "200": { "description": "Authenticated (or MFA required)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "delete": { "tags": [ "Authentication" ], "summary": "Revoke current token", "operationId": "revokeToken", "responses": { "204": { "description": "Token revoked" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/auth/agent-token": { "post": { "tags": [ "Authentication" ], "summary": "Exchange agent credentials for JWT", "description": "Returns a short-lived EdDSA-signed JWT (`access_token`). Standard claims include `sub`\n(`agent:`), `org`, `scopes`, `vault_ids`, optional `intents_api_enabled`, optional\n`shroud_enabled`, optional `llm_token_billing` / `stripe_customer_id` when org LLM billing is on.\n\nWhen **`shroud_enabled`** is true, the JWT payload may include **`shroud_config`**: a JSON object\nmirroring the agent row in Vault (same shape as `ShroudConfig` on `GET /v1/agents/{id}`).\n**Shroud** (TEE proxy) decodes this on each LLM request and runs **PolicyEngine** after the\nglobal inspection pipeline so per-agent limits and threat **block** actions apply without a\nseparate policy fetch. Re-exchange the agent token after changing `shroud_config` so the JWT\nis fresh.\n\nUser JWTs from password, API key, or device flow do **not** include `shroud_config`.\n", "operationId": "agentToken", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTokenRequest" } } } }, "responses": { "200": { "description": "Agent JWT issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/auth/api-key-token": { "post": { "tags": [ "Authentication" ], "summary": "Exchange user API key for JWT", "operationId": "apiKeyToken", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserApiKeyTokenRequest" } } } }, "responses": { "200": { "description": "JWT issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/auth/refresh": { "post": { "tags": [ "Authentication" ], "summary": "Refresh an expiring JWT", "operationId": "refreshToken", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "refresh_token" ], "properties": { "refresh_token": { "type": "string" } } } } } }, "responses": { "200": { "description": "Token refreshed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/auth/jwt-public-key": { "get": { "tags": [ "Authentication" ], "summary": "Get JWT verification public key", "description": "Returns the Ed25519 public key used to sign JWTs.\nUse this to verify tokens independently (e.g. in a TEE proxy or\ngateway). No authentication required.\n\nFor OIDC-compliant relying parties (Anthropic Workload Identity\nFederation, etc.) prefer the JWKS endpoint at\n`/.well-known/jwks.json` together with the discovery document\nat `/.well-known/openid-configuration` — those advertise both\nEd25519 and RS256 keys keyed by `kid` and survive key rotation.\n", "operationId": "getJwtPublicKey", "security": [], "responses": { "200": { "description": "JWT public key", "content": { "application/json": { "schema": { "type": "object", "required": [ "alg", "public_key_base64" ], "properties": { "alg": { "type": "string", "example": "EdDSA" }, "public_key_base64": { "type": "string", "description": "Base64-encoded Ed25519 public key" } } } } } } } } }, "/v1/auth/federated-token": { "post": { "tags": [ "Authentication" ], "summary": "Exchange a 1claw token for an OIDC federation token (RFC 8693)", "description": "Mints a short-lived RS256-signed JWT targeted at an external\nrelying party (e.g. Anthropic Workload Identity Federation).\nThe relying party validates the token via this issuer's JWKS\nURL (`/.well-known/jwks.json`) and exchanges it for its own\nshort-lived service credentials.\n\nRequirements:\n- The agent that owns the `subject_token` must have\n `federation_enabled = true` and the requested `audience`\n must appear in `federation_audiences`.\n- The `subject_token` must be a valid 1claw agent JWT or\n `ocv_` API key.\n- Optional `scope` narrows the agent's existing scopes — it\n cannot escalate.\n\nReturns 503 when `ONECLAW_JWT_RS256_SIGNING_KEY_ID` is not\nconfigured on the server.\n", "operationId": "exchangeFederatedToken", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenExchangeRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TokenExchangeRequest" } } } }, "responses": { "200": { "description": "Federation token issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenExchangeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "503": { "description": "RS256 signing key not configured" } } } }, "/.well-known/openid-configuration": { "get": { "tags": [ "Authentication" ], "summary": "OIDC discovery document", "description": "Standard OpenID Connect discovery document advertising the\nissuer URL, JWKS URL, supported algorithms (`EdDSA`, `RS256`),\nand the RFC 8693 token-exchange endpoint. External IdPs\n(Anthropic WIF, Okta, Auth0, etc.) read this URL to learn\nwhere 1claw publishes its JWKS.\n", "operationId": "openidConfiguration", "security": [], "responses": { "200": { "description": "Discovery document", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/jwks.json": { "get": { "tags": [ "Authentication" ], "summary": "JSON Web Key Set", "description": "Public keys for every active version of every JWT signing\nkey (Ed25519 + RSA-2048). Each entry includes a `kid` so\nconsumers can validate tokens issued before the most recent\nkey rotation. Cached for 5 minutes via `Cache-Control` and\nCORS-permissive for browser-based IdP consoles.\n", "operationId": "jwks", "security": [], "responses": { "200": { "description": "JWK Set", "content": { "application/jwk-set+json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/v1/auth/signup": { "post": { "tags": [ "Authentication" ], "summary": "Create a new account", "operationId": "signup", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupRequest" } } } }, "responses": { "200": { "description": "Account created (pending verification or auto-login)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/auth/verify-email": { "post": { "tags": [ "Authentication" ], "summary": "Verify email address", "operationId": "verifyEmail", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } } } } } }, "responses": { "200": { "description": "Email verified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/auth/forgot-password": { "post": { "tags": [ "Authentication" ], "summary": "Request password reset email", "description": "Always returns the same message whether or not the email exists (no account enumeration).\nOnly password-based accounts receive mail.\n", "operationId": "forgotPassword", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgotPasswordRequest" } } } }, "responses": { "200": { "description": "Acknowledgement (check email if account exists)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgotPasswordResponse" } } } } } } }, "/v1/auth/reset-password": { "post": { "tags": [ "Authentication" ], "summary": "Set a new password using reset token from email", "operationId": "resetPassword", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordRequest" } } } }, "responses": { "200": { "description": "Password updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/auth/google": { "post": { "tags": [ "Authentication" ], "summary": "Authenticate with Google OAuth", "operationId": "googleAuth", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoogleAuthRequest" } } } }, "responses": { "200": { "description": "Authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/auth/change-password": { "post": { "tags": [ "Authentication" ], "summary": "Change current user's password", "operationId": "changePassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePasswordRequest" } } } }, "responses": { "204": { "description": "Password changed" }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/auth/set-password": { "post": { "tags": [ "Authentication" ], "summary": "Set initial password for platform users", "description": "Only allowed when the user has no password set (platform_oidc users after claiming).", "operationId": "setPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "password", "password_confirm" ], "properties": { "password": { "type": "string", "minLength": 12 }, "password_confirm": { "type": "string" } } } } } }, "responses": { "200": { "description": "Password set successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/auth/change-email": { "post": { "tags": [ "Authentication" ], "summary": "Request email change", "description": "Sends a 6-digit verification code to the new email address. Code expires in 10 minutes.", "operationId": "changeEmail", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "new_email" ], "properties": { "new_email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "Verification code sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "new_email": { "type": "string" }, "expires_in_seconds": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "description": "Email already in use" } } } }, "/v1/auth/verify-email-change": { "post": { "tags": [ "Authentication" ], "summary": "Verify email change with code", "operationId": "verifyEmailChange", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } } } } }, "responses": { "200": { "description": "Email updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "email": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/auth/passkeys/register/begin": { "post": { "tags": [ "Authentication" ], "summary": "Begin passkey registration", "description": "Returns a WebAuthn challenge for creating a new passkey credential.", "operationId": "passkeyRegisterBegin", "responses": { "200": { "description": "Registration options", "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge": { "type": "string" }, "rp_id": { "type": "string" }, "rp_name": { "type": "string" }, "user_id": { "type": "string" }, "user_name": { "type": "string" }, "user_display_name": { "type": "string" }, "attestation": { "type": "string" }, "authenticator_selection": { "type": "object" } } } } } } } } }, "/v1/auth/passkeys/register/complete": { "post": { "tags": [ "Authentication" ], "summary": "Complete passkey registration", "description": "When the account already has a password, passkey, or TOTP,\n`X-Auth-Confirm` is required (purpose `security.passkey.register`).\n", "operationId": "passkeyRegisterComplete", "parameters": [ { "name": "X-Auth-Confirm", "in": "header", "required": false, "description": "Re-auth token (`rat_`) or account password", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "credential_id", "attestation_object", "client_data_json" ], "properties": { "credential_id": { "type": "string" }, "attestation_object": { "type": "string" }, "client_data_json": { "type": "string" }, "transports": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string" } } } } } }, "responses": { "201": { "description": "Passkey registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "passkey_id": { "type": "string", "format": "uuid" }, "credential_id": { "type": "string" } } } } } } } } }, "/v1/auth/passkeys/assert/begin": { "post": { "tags": [ "Authentication" ], "summary": "Begin passkey authentication", "operationId": "passkeyAssertBegin", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "Assertion options", "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge": { "type": "string" }, "rp_id": { "type": "string" }, "timeout": { "type": "integer" }, "user_verification": { "type": "string" }, "allow_credentials": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/v1/auth/passkeys/assert/complete": { "post": { "tags": [ "Authentication" ], "summary": "Complete passkey authentication", "operationId": "passkeyAssertComplete", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "credential_id", "authenticator_data", "client_data_json", "signature" ], "properties": { "credential_id": { "type": "string" }, "authenticator_data": { "type": "string" }, "client_data_json": { "type": "string" }, "signature": { "type": "string" } } } } } }, "responses": { "200": { "description": "Authentication successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "refresh_token": { "type": "string" }, "user": { "type": "object" } } } } } } } } }, "/v1/auth/passkeys": { "get": { "tags": [ "Authentication" ], "summary": "List registered passkeys", "operationId": "listPasskeys", "responses": { "200": { "description": "List of passkeys", "content": { "application/json": { "schema": { "type": "object", "properties": { "passkeys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "credential_id": { "type": "string" }, "name": { "type": "string" }, "last_used_at": { "type": "string" }, "created_at": { "type": "string" } } } } } } } } } } } }, "/v1/auth/passkeys/{passkey_id}": { "delete": { "tags": [ "Authentication" ], "summary": "Delete a passkey", "description": "Removes a registered passkey. Requires recent re-authentication\n(`X-Auth-Confirm` with a `rat_` token from `POST /v1/auth/reauth`\nusing purpose `security.passkey.delete`). Passkey or TOTP is\nrequired when either is enrolled. Deleting the last passkey is\nrefused while vault passkey unlock is enabled.\n", "operationId": "deletePasskey", "parameters": [ { "name": "passkey_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Auth-Confirm", "in": "header", "required": true, "description": "Re-auth token (`rat_`) or account password", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Passkey deleted" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/approvals/request": { "post": { "tags": [ "Approvals" ], "summary": "Request human approval (agent-only)", "description": "Agents can request policy changes or other sensitive actions that require human approval.", "operationId": "requestApproval", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action", "target_type", "target_id", "summary" ], "properties": { "action": { "type": "string", "description": "Type of action (e.g. policy_change)" }, "target_type": { "type": "string" }, "target_id": { "type": "string" }, "summary": { "type": "object", "description": "JSON payload describing the request" }, "reason": { "type": "string" }, "risk_tier": { "type": "integer", "minimum": 1, "maximum": 5 } } } } } }, "responses": { "202": { "description": "Approval request created", "headers": { "Location": { "description": "URL to poll for approval status", "schema": { "type": "string", "example": "/v1/approvals/{id}" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/auth/me": { "get": { "tags": [ "Authentication" ], "summary": "Get current user profile", "operationId": "getMe", "responses": { "200": { "description": "User profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileResponse" } } } } } }, "patch": { "tags": [ "Authentication" ], "summary": "Update user profile", "operationId": "updateMe", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProfileRequest" } } } }, "responses": { "200": { "description": "Profile updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "delete": { "tags": [ "Authentication" ], "summary": "Delete current user account", "operationId": "deleteMe", "parameters": [ { "name": "X-Auth-Confirm", "in": "header", "required": true, "description": "Re-auth token (`rat_`, purpose `account.delete`) or password", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "confirmation" ], "properties": { "confirmation": { "type": "string", "description": "Must be \"DELETE MY ACCOUNT\"" } } } } } }, "responses": { "204": { "description": "Account deleted" }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/auth/settings": { "get": { "tags": [ "Authentication" ], "summary": "Get user security settings", "operationId": "getSecuritySettings", "responses": { "200": { "description": "Security settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "require_passkey_for_vaults": { "type": "boolean" }, "require_passkey_for_mfa": { "type": "boolean" }, "passkey_count": { "type": "integer" } } } } } } } }, "patch": { "tags": [ "Authentication" ], "summary": "Update user security settings", "description": "Disabling `require_passkey_for_vaults` requires `X-Auth-Confirm`\n(purpose `security.vault_passkey.disable`) with a passkey or TOTP\nwhen either is enrolled.\n\nDisabling `require_passkey_for_mfa` requires `X-Auth-Confirm`\n(purpose `security.mfa_passkey.disable`) with a passkey or TOTP\nwhen either is enrolled.\n", "operationId": "updateSecuritySettings", "parameters": [ { "name": "X-Auth-Confirm", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "require_passkey_for_vaults": { "type": "boolean" }, "require_passkey_for_mfa": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated settings" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/auth/human-factor-auth": { "get": { "tags": [ "Authentication" ], "summary": "Get effective human factor auth policy", "description": "Returns the resolved HFA policy for treasury wallet send, swap, and export.\nPrecedence: user override → spend policy → platform defaults.\n", "operationId": "getHumanFactorAuth", "responses": { "200": { "description": "Effective HFA policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HumanFactorAuthResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "put": { "tags": [ "Authentication" ], "summary": "Set user human factor auth policy", "operationId": "upsertHumanFactorAuth", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertHumanFactorAuthRequest" } } } }, "responses": { "200": { "description": "Updated policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HumanFactorAuthResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/auth/mfa/status": { "get": { "tags": [ "Authentication" ], "summary": "Check MFA enrollment status", "operationId": "mfaStatus", "responses": { "200": { "description": "MFA status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaStatusResponse" } } } } } } }, "/v1/auth/mfa/setup": { "post": { "tags": [ "Authentication" ], "summary": "Begin MFA enrollment", "operationId": "mfaSetup", "responses": { "200": { "description": "TOTP setup details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaSetupResponse" } } } } } } }, "/v1/auth/mfa/verify-setup": { "post": { "tags": [ "Authentication" ], "summary": "Confirm MFA enrollment with a TOTP code", "operationId": "mfaVerifySetup", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaVerifySetupRequest" } } } }, "responses": { "200": { "description": "MFA enabled, recovery codes returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaVerifySetupResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/auth/mfa/verify": { "post": { "tags": [ "Authentication" ], "summary": "Verify MFA code during login", "operationId": "mfaVerify", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaVerifyRequest" } } } }, "responses": { "200": { "description": "MFA verified, JWT issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/auth/mfa/passkey/begin": { "post": { "tags": [ "Authentication" ], "summary": "Begin passkey MFA verification during login", "operationId": "mfaPasskeyBegin", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mfa_token" ], "properties": { "mfa_token": { "type": "string" } } } } } }, "responses": { "200": { "description": "WebAuthn challenge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyAssertBeginResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/auth/mfa/passkey/complete": { "post": { "tags": [ "Authentication" ], "summary": "Complete passkey MFA verification during login", "operationId": "mfaPasskeyComplete", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaPasskeyCompleteRequest" } } } }, "responses": { "200": { "description": "MFA verified, JWT issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/auth/mfa": { "delete": { "tags": [ "Authentication" ], "summary": "Disable MFA", "description": "Requires a valid TOTP or recovery code in the body, or a passkey\nre-auth token in `X-Auth-Confirm` (purpose `security.mfa.disable`).\nAccount password alone is not accepted while TOTP is enabled.\n", "operationId": "mfaDisable", "parameters": [ { "name": "X-Auth-Confirm", "in": "header", "required": false, "description": "Passkey or TOTP re-auth token (`rat_`)", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaDisableRequest" } } } }, "responses": { "204": { "description": "MFA disabled" }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/auth/device/code": { "post": { "tags": [ "Authentication" ], "summary": "Request a device authorization code", "operationId": "deviceCode", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceCodeRequest" } } } }, "responses": { "200": { "description": "Device code issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceCodeResponse" } } } } } } }, "/v1/auth/device/token": { "post": { "tags": [ "Authentication" ], "summary": "Poll for device authorization token", "operationId": "deviceToken", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceTokenRequest" } } } }, "responses": { "200": { "description": "Token issued or authorization pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceTokenResponse" } } } } } } }, "/v1/auth/device/code/{user_code}": { "get": { "tags": [ "Authentication" ], "summary": "Check device code status", "operationId": "deviceCodeStatus", "security": [], "parameters": [ { "name": "user_code", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Device code details" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/auth/device/approve": { "post": { "tags": [ "Authentication" ], "summary": "Approve a CLI device login", "operationId": "deviceApprove", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceApproveRequest" } } } }, "responses": { "200": { "description": "Device approved" } } } }, "/v1/auth/device/deny": { "post": { "tags": [ "Authentication" ], "summary": "Deny a CLI device login", "operationId": "deviceDeny", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceApproveRequest" } } } }, "responses": { "200": { "description": "Device denied" } } } }, "/v1/auth/api-keys": { "post": { "tags": [ "API Keys" ], "summary": "Create a personal API key", "operationId": "createApiKey", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "responses": { "201": { "description": "API key created (full key shown once)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "get": { "tags": [ "API Keys" ], "summary": "List personal API keys", "operationId": "listApiKeys", "responses": { "200": { "description": "List of API keys (masked)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyListResponse" } } } } } } }, "/v1/auth/api-keys/{key_id}": { "delete": { "tags": [ "API Keys" ], "summary": "Revoke an API key", "operationId": "revokeApiKey", "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Key revoked" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/auth/export-data": { "post": { "tags": [ "Authentication" ], "summary": "Export user data (GDPR)", "description": "Returns a full export of the authenticated user's data including\nprofile, vaults, agents, secrets metadata, and policies. Intended\nfor GDPR data-portability requests. Only available to human users\n(not agents). Requires `X-Auth-Confirm` (purpose `account.export`);\npasskey or TOTP when either is enrolled.\n", "operationId": "exportUserData", "parameters": [ { "name": "X-Auth-Confirm", "in": "header", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User data export", "content": { "application/json": { "schema": { "type": "object", "required": [ "export_version", "exported_at", "user", "vaults", "agents", "secrets_metadata", "policies" ], "properties": { "export_version": { "type": "string", "example": "1.0" }, "exported_at": { "type": "string", "format": "date-time" }, "user": { "type": "object", "required": [ "id", "email", "display_name", "auth_method", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "display_name": { "type": "string" }, "auth_method": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "vaults": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "agents": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "secrets_metadata": { "type": "array", "items": { "type": "object", "required": [ "vault_id", "path", "type", "version", "created_at" ], "properties": { "vault_id": { "type": "string", "format": "uuid" }, "path": { "type": "string" }, "type": { "type": "string" }, "version": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } } }, "policies": { "type": "array", "items": { "type": "object", "required": [ "id", "vault_id", "principal_type", "principal_id", "secret_path_pattern", "permissions", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "vault_id": { "type": "string", "format": "uuid" }, "principal_type": { "type": "string" }, "principal_id": { "type": "string", "format": "uuid" }, "secret_path_pattern": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/auth/devices": { "post": { "tags": [ "Authentication" ], "summary": "Register a mobile device", "description": "Register a new mobile device for the authenticated user. Human-only.\nThe device public key is used for step-up authentication challenges.\n", "operationId": "registerDevice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterDeviceRequest" } } } }, "responses": { "201": { "description": "Device registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterDeviceResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "get": { "tags": [ "Authentication" ], "summary": "List devices for current user", "description": "Returns all registered mobile devices for the authenticated user.", "operationId": "listDevices", "responses": { "200": { "description": "Device list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceListResponse" } } } } } } }, "/v1/auth/devices/{device_id}": { "delete": { "tags": [ "Authentication" ], "summary": "Revoke a device", "description": "Removes a registered device, invalidating its keys and push tokens.", "operationId": "revokeDevice", "parameters": [ { "name": "device_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Device revoked" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/auth/devices/{device_id}/challenge": { "post": { "tags": [ "Authentication" ], "summary": "Create step-up auth challenge", "description": "Creates a cryptographic challenge bound to a specific action (e.g. approving\na high-risk transaction). The device signs the challenge nonce to prove\npossession of the private key.\n", "operationId": "createDeviceChallenge", "parameters": [ { "name": "device_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDeviceChallengeRequest" } } } }, "responses": { "200": { "description": "Challenge created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceChallengeResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/auth/devices/{device_id}/attest": { "post": { "tags": [ "Authentication" ], "summary": "Attest device challenge", "description": "Submit a signed challenge nonce to complete step-up authentication.\nReturns a short-lived step-up token that can be used for the bound action.\n", "operationId": "attestDeviceChallenge", "parameters": [ { "name": "device_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttestDeviceChallengeRequest" } } } }, "responses": { "200": { "description": "Attestation successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttestDeviceChallengeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/auth/devices/{device_id}/push-token": { "post": { "tags": [ "Authentication" ], "summary": "Register push notification token", "description": "Associates a push notification token (APNs or FCM) with a registered device\nso the server can send approval requests and alerts.\n", "operationId": "registerPushToken", "parameters": [ { "name": "device_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterPushTokenRequest" } } } }, "responses": { "204": { "description": "Push token registered" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/vaults": { "post": { "tags": [ "Vaults" ], "summary": "Create a vault", "operationId": "createVault", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVaultRequest" } } } }, "responses": { "201": { "description": "Vault created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "get": { "tags": [ "Vaults" ], "summary": "List vaults", "operationId": "listVaults", "responses": { "200": { "description": "List of vaults", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultListResponse" } } } } } } }, "/v1/vaults/{vault_id}": { "get": { "tags": [ "Vaults" ], "summary": "Get vault details", "operationId": "getVault", "parameters": [ { "$ref": "#/components/parameters/VaultId" } ], "responses": { "200": { "description": "Vault details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Vaults" ], "summary": "Delete a vault", "operationId": "deleteVault", "parameters": [ { "$ref": "#/components/parameters/VaultId" } ], "responses": { "204": { "description": "Vault deleted" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/vaults/{vault_id}/cmek": { "post": { "tags": [ "CMEK" ], "summary": "Enable CMEK on a vault", "operationId": "enableCmek", "description": "Enable client-side encryption on a vault. Requires Business or Enterprise plan.\nOnly the key's SHA-256 fingerprint is stored — the key never touches the server.\n", "parameters": [ { "$ref": "#/components/parameters/VaultId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableCmekRequest" } } } }, "responses": { "200": { "description": "CMEK enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "delete": { "tags": [ "CMEK" ], "summary": "Disable CMEK on a vault", "operationId": "disableCmek", "description": "Disable client-side encryption. Existing CMEK-encrypted secrets still require\nthe key to decrypt. New secrets will use HSM-only encryption.\n", "parameters": [ { "$ref": "#/components/parameters/VaultId" } ], "responses": { "200": { "description": "CMEK disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/vaults/{vault_id}/cmek-rotate": { "post": { "tags": [ "CMEK" ], "summary": "Start server-assisted CMEK key rotation", "operationId": "rotateCmek", "description": "Re-encrypts all secrets from the old CMEK key to the new one.\nKeys are passed in headers (TLS-only) and exist in server memory\nonly during the rotation. Batched in groups of 100 secrets.\n", "parameters": [ { "$ref": "#/components/parameters/VaultId" }, { "name": "x-cmek-old-key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64-encoded old CMEK key (32 bytes)" }, { "name": "x-cmek-new-key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Base64-encoded new CMEK key (32 bytes)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CmekRotateRequest" } } } }, "responses": { "202": { "description": "Rotation job started", "headers": { "Location": { "description": "URL to poll for rotation job status", "schema": { "type": "string", "example": "/v1/vaults/{vault_id}/cmek-rotate/{job_id}" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CmekRotationJobResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/vaults/{vault_id}/cmek-rotate/{job_id}": { "get": { "tags": [ "CMEK" ], "summary": "Get CMEK rotation job status", "operationId": "getCmekRotationJob", "parameters": [ { "$ref": "#/components/parameters/VaultId" }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Rotation job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CmekRotationJobResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/vaults/{vault_id}/mpc": { "post": { "tags": [ "Vaults" ], "summary": "Enable MPC custody on a vault", "operationId": "enableMpc", "description": "Enable MPC custody on an existing vault. Requires Business or Enterprise plan.\nSplits secret encryption keys across multiple providers using the specified\ncustody mode (e.g. 2-of-2, 2-of-3).\n", "parameters": [ { "$ref": "#/components/parameters/VaultId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnableMpcRequest" } } } }, "responses": { "200": { "description": "MPC custody enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/vaults/{vault_id}/secrets": { "get": { "tags": [ "Secrets" ], "summary": "List secrets in a vault", "operationId": "listSecrets", "parameters": [ { "$ref": "#/components/parameters/VaultId" }, { "name": "prefix", "in": "query", "schema": { "type": "string" }, "description": "Filter by path prefix" } ], "responses": { "200": { "description": "Secret metadata list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretListResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/vaults/{vault_id}/secrets/{path}": { "put": { "tags": [ "Secrets" ], "summary": "Store or update a secret", "operationId": "putSecret", "x-agentcash-auth": { "mode": "paid" }, "x-payment-info": { "protocols": [ "x402" ], "pricingMode": "fixed", "price": "0.0075" }, "parameters": [ { "$ref": "#/components/parameters/VaultId" }, { "$ref": "#/components/parameters/SecretPath" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutSecretRequest" } } } }, "responses": { "201": { "description": "Secret created or updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretCreatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } }, "get": { "tags": [ "Secrets" ], "summary": "Retrieve a decrypted secret", "operationId": "getSecret", "x-agentcash-auth": { "mode": "paid" }, "x-payment-info": { "protocols": [ "x402" ], "pricingMode": "fixed", "price": "0.0015" }, "parameters": [ { "$ref": "#/components/parameters/VaultId" }, { "$ref": "#/components/parameters/SecretPath" }, { "name": "x-client-share", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Base64-encoded client key share for MPC 2-of-2 vaults. Required when the vault uses 2-of-2 MPC custody." } ], "responses": { "200": { "description": "Decrypted secret value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretResponse" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Secrets" ], "summary": "Delete a secret", "operationId": "deleteSecret", "parameters": [ { "$ref": "#/components/parameters/VaultId" }, { "$ref": "#/components/parameters/SecretPath" } ], "responses": { "204": { "description": "Secret deleted" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/vaults/{vault_id}/secret-versions/{path}": { "get": { "tags": [ "Secrets" ], "summary": "List all versions of a secret", "operationId": "listSecretVersions", "parameters": [ { "$ref": "#/components/parameters/VaultId" }, { "$ref": "#/components/parameters/SecretPath" } ], "responses": { "200": { "description": "Version list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretVersionListResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/vaults/{vault_id}/secret-version/{path}/{version}": { "get": { "tags": [ "Secrets" ], "summary": "Retrieve a specific version of a secret", "operationId": "getSecretVersion", "parameters": [ { "$ref": "#/components/parameters/VaultId" }, { "$ref": "#/components/parameters/SecretPath" }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Decrypted secret value at the specified version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "410": { "description": "Version has been disabled or expired" } } } }, "/v1/vaults/{vault_id}/secret-version-disable/{path}/{version}": { "post": { "tags": [ "Secrets" ], "summary": "Disable a specific secret version", "operationId": "disableSecretVersion", "description": "Disables a version so it can no longer be read. The version is\nretained for audit purposes but returns 410 on read attempts.\n", "parameters": [ { "$ref": "#/components/parameters/VaultId" }, { "$ref": "#/components/parameters/SecretPath" }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Version disabled" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/vaults/{vault_id}/secret-rotate/{path}": { "post": { "tags": [ "Secrets" ], "summary": "Server-side secret rotation", "operationId": "rotateSecret", "description": "Generates a cryptographically random value and stores it as a new\nversion of the secret. The previous version is preserved in history.\nRequires rotate or write permission.\n", "parameters": [ { "$ref": "#/components/parameters/VaultId" }, { "$ref": "#/components/parameters/SecretPath" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateSecretRequest" } } } }, "responses": { "201": { "description": "New version created with server-generated value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecretCreatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/vaults/{vault_id}/policies": { "post": { "tags": [ "Policies" ], "summary": "Create an access policy", "operationId": "createPolicy", "parameters": [ { "$ref": "#/components/parameters/VaultId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePolicyRequest" } } } }, "responses": { "201": { "description": "Policy created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "get": { "tags": [ "Policies" ], "summary": "List policies on a vault", "operationId": "listPolicies", "parameters": [ { "$ref": "#/components/parameters/VaultId" } ], "responses": { "200": { "description": "Policy list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyListResponse" } } } } } } }, "/v1/vaults/{vault_id}/policies/{policy_id}": { "put": { "tags": [ "Policies" ], "summary": "Update a policy", "operationId": "updatePolicy", "parameters": [ { "$ref": "#/components/parameters/VaultId" }, { "$ref": "#/components/parameters/PolicyId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePolicyRequest" } } } }, "responses": { "200": { "description": "Policy updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Policies" ], "summary": "Revoke a policy", "operationId": "deletePolicy", "parameters": [ { "$ref": "#/components/parameters/VaultId" }, { "$ref": "#/components/parameters/PolicyId" } ], "responses": { "204": { "description": "Policy revoked" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/vaults/{vault_id}/env-vars": { "get": { "tags": [ "Environment Variables" ], "summary": "List environment variables", "description": "List all environment variables for a vault, optionally filtered by environment.", "operationId": "listEnvVars", "parameters": [ { "$ref": "#/components/parameters/VaultId" }, { "name": "environment", "in": "query", "schema": { "type": "string" }, "description": "Filter by environment (production, preview, development, or custom)" } ], "responses": { "200": { "description": "Environment variable list", "content": { "application/json": { "schema": { "type": "object", "properties": { "env_vars": { "type": "array", "items": { "$ref": "#/components/schemas/EnvVar" } } } } } } } } }, "post": { "tags": [ "Environment Variables" ], "summary": "Create environment variable", "operationId": "createEnvVar", "parameters": [ { "$ref": "#/components/parameters/VaultId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEnvVarRequest" } } } }, "responses": { "201": { "description": "Environment variable created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvVar" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/vaults/{vault_id}/env-vars/resolve": { "get": { "tags": [ "Environment Variables" ], "summary": "Resolve environment variables", "description": "Resolve the final KEY=VALUE set for an environment with full precedence (shared < vault < branch override).\nWhen the caller is an agent with `env_auto_resolve: true`, the `environment` query parameter may be omitted —\nthe server uses the agent's tagged environment from the JWT. Org setting `env.enforce_agent_environment_scope`\nblocks agents from resolving vars outside their tagged environment.\n", "operationId": "resolveEnvVars", "parameters": [ { "$ref": "#/components/parameters/VaultId" }, { "name": "environment", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Target environment (production, preview, development, or custom). Required for human callers; optional for agents with env_auto_resolve when the agent has an environment tag." }, { "name": "git_branch", "in": "query", "schema": { "type": "string" }, "description": "Optional git branch for preview branch overrides" } ], "responses": { "200": { "description": "Resolved environment variables", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveEnvVarsResponse" } } } } } } }, "/v1/vaults/{vault_id}/env-vars/{key}": { "get": { "tags": [ "Environment Variables" ], "summary": "Get environment variable", "operationId": "getEnvVar", "parameters": [ { "$ref": "#/components/parameters/VaultId" }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "environment", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Environment variable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvVar" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Environment Variables" ], "summary": "Update environment variable", "operationId": "updateEnvVar", "parameters": [ { "$ref": "#/components/parameters/VaultId" }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "environment", "in": "query", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEnvVarRequest" } } } }, "responses": { "200": { "description": "Environment variable updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvVar" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Environment Variables" ], "summary": "Delete environment variable", "operationId": "deleteEnvVar", "parameters": [ { "$ref": "#/components/parameters/VaultId" }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "environment", "in": "query", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/v1/vaults/{vault_id}/environments": { "get": { "tags": [ "Environment Variables" ], "summary": "List vault environments", "operationId": "listVaultEnvironments", "parameters": [ { "$ref": "#/components/parameters/VaultId" } ], "responses": { "200": { "description": "Vault environment list", "content": { "application/json": { "schema": { "type": "object", "properties": { "environments": { "type": "array", "items": { "$ref": "#/components/schemas/VaultEnvironment" } } } } } } } } }, "post": { "tags": [ "Environment Variables" ], "summary": "Create custom environment", "operationId": "createVaultEnvironment", "parameters": [ { "$ref": "#/components/parameters/VaultId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEnvironmentRequest" } } } }, "responses": { "201": { "description": "Environment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaultEnvironment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/vaults/{vault_id}/environments/{slug}": { "delete": { "tags": [ "Environment Variables" ], "summary": "Delete custom environment", "operationId": "deleteVaultEnvironment", "parameters": [ { "$ref": "#/components/parameters/VaultId" }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/v1/agents/enroll": { "post": { "tags": [ "Agents" ], "summary": "Self-enroll an agent", "operationId": "enrollAgent", "description": "Public endpoint (no auth required).\n\n**With `human_email`:** Creates a pending enrollment for that account's org,\nemails Allow/Deny links, and returns `approval_url` in the JSON body (use if email\nis delayed). The API key is NOT returned until the human approves.\n\n**Name only (omit `human_email`):** Creates a link-only pending enrollment.\nThe response includes `approval_url`; the human opens it while signed in to\napprove the agent into their org.\n\nAnti-spam: IP rate limiting, per-email cooldown, caps on pending rows.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollAgentRequest" } } } }, "responses": { "201": { "description": "Enrollment processed (uniform response to prevent email enumeration)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollAgentResponse" } } } }, "429": { "description": "Rate limit exceeded" } } } }, "/v1/agents": { "post": { "tags": [ "Agents" ], "summary": "Register a new agent", "operationId": "createAgent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRequest" } } } }, "responses": { "201": { "description": "Agent created with one-time API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCreatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "get": { "tags": [ "Agents" ], "summary": "List agents", "operationId": "listAgents", "responses": { "200": { "description": "Agent list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentListResponse" } } } } } } }, "/v1/agents/me": { "get": { "tags": [ "Agents" ], "summary": "Get the calling agent's own profile", "operationId": "getAgentSelf", "responses": { "200": { "description": "Agent self profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSelfResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/agents/{agent_id}": { "get": { "tags": [ "Agents" ], "summary": "Get agent details", "operationId": "getAgent", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "responses": { "200": { "description": "Agent details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Agents" ], "summary": "Update an agent", "operationId": "updateAgent", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgentRequest" } } } }, "responses": { "200": { "description": "Agent updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "202": { "description": "Guardrail widening queued for human approval. The change is not\napplied until approved via POST /v1/approvals/{approval_id}/decide.\nResubmit this PATCH with `approval_id` set to the returned value\nafter approval to apply the widening.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardrailWideningQueuedResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Agents" ], "summary": "Delete an agent", "operationId": "deleteAgent", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "responses": { "204": { "description": "Agent deleted" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/rotate-key": { "post": { "tags": [ "Agents" ], "summary": "Rotate agent API key", "operationId": "rotateAgentKey", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "responses": { "200": { "description": "New API key returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentKeyRotatedResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/rotate-identity-keys": { "post": { "tags": [ "Agents" ], "summary": "Rotate agent identity keys (SSH + ECDH)", "description": "Rotates the agent's Ed25519 SSH keypair and P-256 ECDH keypair.\nNew private keys are stored in the __agent-keys vault; old keys are overwritten.\nUser-only endpoint — agents cannot rotate their own identity keys.\n", "operationId": "rotateAgentIdentityKeys", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "responses": { "200": { "description": "Agent with updated public keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/smart-accounts": { "post": { "tags": [ "Agents" ], "summary": "Add a smart account (Safe) for this agent on a chain", "description": "Use after deploying a Safe on a new chain. Multi-chain; one Safe per chain.\nReplaces any existing entry for the same chain_id.\n", "operationId": "addAgentSmartAccount", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddSmartAccountRequest" } } } }, "responses": { "200": { "description": "Agent with updated smart_accounts list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/transactions": { "post": { "tags": [ "Transactions" ], "summary": "Submit a transaction for signing", "x-agentcash-auth": { "mode": "paid" }, "x-payment-info": { "protocols": [ "x402" ], "pricingMode": "quote" }, "description": "Replay protection: send an optional **Idempotency-Key** header (e.g. UUID or opaque string).\nDuplicate requests with the same key within 24 hours return the cached transaction response\n(no second sign/broadcast). Omit the header for non-idempotent submissions.\n", "operationId": "submitTransaction", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional key for replay protection; duplicate requests return cached response.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitTransactionRequest" } } } }, "responses": { "200": { "description": "Transaction previously created with same Idempotency-Key (replay-safe response)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" } } } }, "201": { "description": "Transaction signed (and optionally broadcast)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" } } } }, "202": { "description": "Transaction held for human approval (graduated tx_approval_policy)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TxAwaitingApproval" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Idempotency-Key in use by another in-flight request; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "422": { "description": "Simulation reverted (when simulate_first is true)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" } } } } } }, "get": { "tags": [ "Transactions" ], "summary": "List agent transactions", "operationId": "listTransactions", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "$ref": "#/components/parameters/IncludeSignedTx" } ], "responses": { "200": { "description": "Transaction list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionListResponse" } } } } } } }, "/v1/agents/{agent_id}/transactions/{tx_id}": { "get": { "tags": [ "Transactions" ], "summary": "Get a transaction by ID", "operationId": "getTransaction", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "tx_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IncludeSignedTx" } ], "responses": { "200": { "description": "Transaction details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/transactions/sign": { "post": { "tags": [ "Transactions" ], "summary": "Sign a transaction without broadcasting", "description": "Signs a transaction inside the server (or TEE when using Shroud) but does\n**not** broadcast it. The caller receives the raw `signed_tx` hex and\n`tx_hash` so it can submit to any RPC of its choosing.\n\nAll agent guardrails (allowlists, value caps, daily limits) are enforced\nexactly as for the submit endpoint. The signed transaction is recorded for\naudit and daily-limit tracking with `status: \"sign_only\"`.\n", "operationId": "signTransaction", "x-agentcash-auth": { "mode": "paid" }, "x-payment-info": { "protocols": [ "x402" ], "pricingMode": "quote" }, "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignTransactionRequest" } } } }, "responses": { "200": { "description": "Transaction signed successfully (not broadcast)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignTransactionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/agents/{agent_id}/transactions/simulate": { "post": { "tags": [ "Transactions" ], "summary": "Simulate a transaction via Tenderly", "operationId": "simulateTransaction", "x-agentcash-auth": { "mode": "paid" }, "x-payment-info": { "protocols": [ "x402" ], "pricingMode": "fixed", "price": "0.075" }, "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateTransactionRequest" } } } }, "responses": { "200": { "description": "Simulation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/agents/{agent_id}/transactions/simulate-bundle": { "post": { "tags": [ "Transactions" ], "summary": "Simulate a bundle of transactions", "operationId": "simulateBundle", "x-agentcash-auth": { "mode": "paid" }, "x-payment-info": { "protocols": [ "x402" ], "pricingMode": "fixed", "price": "0.075" }, "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateBundleRequest" } } } }, "responses": { "200": { "description": "Bundle simulation results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleSimulationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/agents/{agent_id}/signing-keys": { "post": { "tags": [ "Signing Keys" ], "summary": "Provision a signing key for a chain", "operationId": "createSigningKey", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSigningKeyRequest" } } } }, "responses": { "201": { "description": "Signing key created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningKeyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "get": { "tags": [ "Signing Keys" ], "summary": "List signing keys for an agent", "operationId": "listSigningKeys", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "responses": { "200": { "description": "Signing keys list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningKeyListResponse" } } } } } } }, "/v1/agents/{agent_id}/signing-keys/{chain}/rotate": { "post": { "tags": [ "Signing Keys" ], "summary": "Rotate a signing key for a chain", "operationId": "rotateSigningKey", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "chain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rotated signing key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningKeyResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/signing-keys/{chain}": { "delete": { "tags": [ "Signing Keys" ], "summary": "Deactivate a signing key for a chain", "operationId": "deactivateSigningKey", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "chain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Key deactivated" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/signing-keys/{chain}/export": { "post": { "tags": [ "Signing Keys" ], "summary": "Export a signing key (private key included)", "description": "Export the private key for an agent's signing key. Requires re-authentication\nvia the X-Auth-Confirm header containing the user's account password.\nHuman users only — agents cannot export keys.\n", "operationId": "exportSigningKey", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "chain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Auth-Confirm", "in": "header", "required": true, "description": "Account password for re-authentication", "schema": { "type": "string", "format": "password" } } ], "responses": { "200": { "description": "Signing key exported successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "chain", "curve", "public_key", "private_key", "key_version", "agent_id" ], "properties": { "chain": { "type": "string" }, "curve": { "type": "string" }, "public_key": { "type": "string" }, "address": { "type": "string" }, "private_key": { "type": "string" }, "key_version": { "type": "integer" }, "agent_id": { "type": "string", "format": "uuid" } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/signing-keys/{chain}/balance": { "get": { "tags": [ "Signing Keys" ], "summary": "Get signing key balance", "description": "Returns the native token balance for the agent's signing key address\non the specified chain.\n", "operationId": "getSigningKeyBalance", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "chain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signing key balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningKeyBalanceResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/signing-keys/{chain}/import": { "post": { "tags": [ "Signing Keys" ], "summary": "Import a signing key for a chain", "description": "Import an existing private key for a specific chain. Human-only,\nrequires password re-authentication.\n", "operationId": "importSigningKey", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "chain", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportKeyRequest" } } } }, "responses": { "201": { "description": "Signing key imported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningKeyResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/agents/{agent_id}/bankr-keys/lease": { "post": { "tags": [ "Bankr Keys" ], "summary": "Lease a short-lived Bankr wallet API key", "description": "Provision a scoped, time-limited Bankr wallet API key for an agent.\n**Privileged, deny-by-default:** agent callers need an explicit access policy\non `agents/{agent_id}/bankr/*` in the `__agent-keys` vault (JWT scope\n`agents/{agent_id}/bankr/lease`). Agents may only lease for their own ID.\nThe `bk_usr_` key is **omitted** from the JSON response for agent JWTs —\nstored server-side for Shroud resolution. Human callers receive `api_key` once.\nRequires `BANKR_PARTNER_KEY` on Vault. Agent default TTL 15 min when omitted;\nhuman/org default 1 hour (`BANKR_DEFAULT_LEASE_TTL_SECS`). Recommend 5–15 min\nfor autonomous agents. Max TTL 24 hours. Max 5 concurrent leases per agent.\n", "operationId": "leaseBankrKey", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseBankrKeyRequest" } } } }, "responses": { "201": { "description": "Bankr key leased", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseBankrKeyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/agents/{agent_id}/bankr-keys": { "get": { "tags": [ "Bankr Keys" ], "summary": "List active Bankr key leases for an agent", "operationId": "listBankrKeys", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "responses": { "200": { "description": "Active leases (no secret values)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankrKeyLeaseListResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/bankr-keys/{lease_id}": { "delete": { "tags": [ "Bankr Keys" ], "summary": "Revoke an active Bankr key lease", "operationId": "revokeBankrKey", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "lease_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Lease revoked" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/accounts": { "get": { "tags": [ "Agents" ], "summary": "List agent on-chain accounts", "operationId": "listAgentAccounts", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "responses": { "200": { "description": "Agent accounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAccountListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Agents" ], "summary": "Provision an agent account record", "description": "Human-only. Creates a DB record for an EOA or Safe account (Safe onchain sync is stubbed).", "operationId": "provisionAgentAccount", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionAgentAccountRequest" } } } }, "responses": { "201": { "description": "Account provisioned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAccountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/accounts/migrate": { "post": { "tags": [ "Agents" ], "summary": "EOA to Safe migration wizard", "description": "Human-only. Provisions counterfactual Safe and returns sweep plan. Onchain module broadcast stubbed pre-audit.", "operationId": "migrateAgentToSafe", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "chain" ], "properties": { "chain": { "type": "string" }, "deprecate_eoa": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Migration plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MigrationPlanResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/accounts/{chain}/deprecate-eoa": { "post": { "tags": [ "Agents" ], "summary": "Mark agent EOA account deprecated", "operationId": "deprecateAgentEoa", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "chain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAccountResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/accounts/{chain}/deploy": { "post": { "tags": [ "Agents" ], "summary": "Lazy-deploy counterfactual Safe (stub)", "description": "Human-only. Broadcasts Safe deployment when Guard audit completes. Returns 501 pre-audit.", "operationId": "deployAgentSafeAccount", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "chain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "501": { "description": "Not implemented (Phase 5.1)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotImplementedResponse" } } } } } } }, "/v1/org/safe/sync-allowances": { "post": { "tags": [ "Organization" ], "summary": "Reconcile Safe allowance targets (org admin)", "description": "Compiles tx_daily_limit targets for Safe agents. Onchain read/write stubbed pre-audit.", "operationId": "syncOrgSafeAllowances", "responses": { "200": { "description": "Reconciliation report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowanceReconcileReport" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/treasury/{treasury_id}/safe/roles-sync": { "post": { "tags": [ "Treasury" ], "summary": "Sync treasury Safe Roles module (stub)", "description": "Human-only. Reconciles on-chain Roles config with agent guardrails. Returns 501 pre-audit.", "operationId": "treasurySafeRolesSync", "parameters": [ { "name": "treasury_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "501": { "description": "Not implemented (Phase 5.9)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotImplementedResponse" } } } } } } }, "/v1/agents/{agent_id}/safe/cosign": { "post": { "tags": [ "Agents" ], "summary": "Enable Vault co-signer (stub)", "operationId": "enableSafeCosign", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "responses": { "501": { "description": "Not implemented (Phase 5.2)" } } } }, "/v1/agents/{agent_id}/safe/passkey-enroll": { "post": { "tags": [ "Agents" ], "summary": "Enroll passkey Safe owner (stub)", "operationId": "enrollSafePasskeyOwner", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "responses": { "501": { "description": "Not implemented (Phase 5.5)" } } } }, "/v1/agents/{agent_id}/safe/timelock": { "post": { "tags": [ "Agents" ], "summary": "Configure Zodiac timelock (stub)", "operationId": "configureSafeTimelock", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "responses": { "501": { "description": "Not implemented (Phase 5.6)" } } } }, "/v1/agents/{agent_id}/safe/erc4337": { "post": { "tags": [ "Agents" ], "summary": "Enable ERC-4337 Safe lane (stub)", "operationId": "enableSafeErc4337", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "responses": { "501": { "description": "Not implemented (Phase 5.8)" } } } }, "/v1/agents/{agent_id}/guardrails/replay": { "post": { "tags": [ "Agents" ], "summary": "Dry-run guardrail changes against recent transactions", "description": "Human-only. Compares draft guardrails against recent agent transactions.", "operationId": "replayAgentGuardrails", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardrailReplayRequest" } } } }, "responses": { "200": { "description": "Replay report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardrailReplayResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/safe/module-registry/{chain}": { "get": { "tags": [ "Agents" ], "summary": "List Safe module registry entries for a chain", "operationId": "getSafeModuleRegistry", "security": [], "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Module registry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SafeModuleRegistryResponse" } } } } } } }, "/v1/agents/{agent_id}/delegations": { "post": { "tags": [ "Delegations" ], "summary": "Create a delegation", "description": "Grant an agent (delegator) permission to delegate tasks to another agent (delegate).\nHuman-only — agents cannot create their own delegations.\n", "operationId": "createDelegation", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDelegationRequest" } } } }, "responses": { "201": { "description": "Delegation created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Delegation already exists for this delegator/delegate pair", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "get": { "tags": [ "Delegations" ], "summary": "List delegations for an agent", "description": "List all delegations where this agent is the delegator.\n", "operationId": "listDelegations", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "responses": { "200": { "description": "List of delegations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationListResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/delegations/effective": { "get": { "tags": [ "Delegations" ], "summary": "Get effective delegations", "description": "Get the effective delegations for an agent, including daily usage statistics.\nAgents can call this on their own ID to discover what they are authorized to delegate to.\n", "operationId": "getEffectiveDelegations", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "responses": { "200": { "description": "Effective delegations with usage stats", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationListResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/delegations/{delegation_id}": { "get": { "tags": [ "Delegations" ], "summary": "Get a specific delegation", "operationId": "getDelegation", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "delegation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Delegation details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Delegations" ], "summary": "Update a delegation", "description": "Update delegation tools, limits, mode, or active status. Human-only.\n", "operationId": "updateDelegation", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "delegation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDelegationRequest" } } } }, "responses": { "200": { "description": "Delegation updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Delegations" ], "summary": "Revoke a delegation", "operationId": "revokeDelegation", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "delegation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Delegation revoked" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/sign": { "post": { "tags": [ "Signing" ], "summary": "Unified signing intent (EIP-191, EIP-712, EIP-2718 types 0-4)", "operationId": "signIntent", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignIntentRequest" } } } }, "responses": { "200": { "description": "Signed result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignIntentResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/agents/{agent_id}/bindings": { "post": { "tags": [ "Execution Intents" ], "summary": "Create a binding", "operationId": "createBinding", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBindingRequest" } } } }, "responses": { "201": { "description": "Binding created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BindingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "get": { "tags": [ "Execution Intents" ], "summary": "List bindings", "operationId": "listBindings", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "responses": { "200": { "description": "Binding list", "content": { "application/json": { "schema": { "type": "object", "required": [ "bindings" ], "properties": { "bindings": { "type": "array", "items": { "$ref": "#/components/schemas/BindingResponse" } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/agents/{agent_id}/bindings/{binding_id}": { "get": { "tags": [ "Execution Intents" ], "summary": "Get binding", "operationId": "getBinding", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "binding_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Binding details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BindingResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Execution Intents" ], "summary": "Update binding", "operationId": "updateBinding", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "binding_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBindingRequest" } } } }, "responses": { "200": { "description": "Binding updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BindingResponse" } } } }, "202": { "description": "Binding guardrail widening queued for human approval. Resubmit\nPATCH with `approval_id` after approval via\nPOST /v1/approvals/{approval_id}/decide.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardrailWideningQueuedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Execution Intents" ], "summary": "Delete binding", "operationId": "deleteBinding", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "binding_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Binding deleted" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/bindings/{binding_id}/test": { "post": { "tags": [ "Execution Intents" ], "summary": "Test binding connectivity", "operationId": "testBinding", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "binding_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "timeout_ms": { "type": "integer", "description": "Connection test timeout in milliseconds" } } } } } }, "responses": { "200": { "description": "Test result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestBindingResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/bindings/{binding_id}/rotate-credential": { "post": { "tags": [ "Execution Intents" ], "summary": "Rotate a binding credential", "description": "Overwrite the stored credential for a binding without touching its config or guardrails. Human-only. The credential value is never returned.", "operationId": "rotateBindingCredential", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "binding_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "credential" ], "properties": { "credential": { "description": "New credential material (object or string). Stored server-side." } } } } } }, "responses": { "200": { "description": "Updated binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BindingResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/execute": { "post": { "tags": [ "Execution Intents" ], "summary": "Execute an intent", "operationId": "executeIntent", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteRequest" } } } }, "responses": { "200": { "description": "Execution result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteResponse" } } } }, "202": { "description": "Execution requires human approval before running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionApprovalRequired" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "Guardrail violation or permission denied", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/GuardrailViolation" }, { "$ref": "#/components/schemas/ProblemDetails" } ] } } } }, "413": { "description": "Request params exceed binding max_request_bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardrailViolation" } } } }, "429": { "description": "Binding or agent execution rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardrailViolation" } } } } } } }, "/v1/agents/{agent_id}/executions": { "get": { "tags": [ "Execution Intents" ], "summary": "List execution events", "operationId": "listExecutions", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Execution event list", "content": { "application/json": { "schema": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/ExecutionEventResponse" } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/chains": { "get": { "tags": [ "Chains" ], "summary": "List enabled chains", "operationId": "listChains", "security": [], "responses": { "200": { "description": "Chain list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChainListResponse" } } } } } } }, "/v1/chains/{identifier}": { "get": { "tags": [ "Chains" ], "summary": "Get chain by name or ID", "operationId": "getChain", "security": [], "parameters": [ { "name": "identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Chain name (e.g. \"ethereum\") or numeric chain ID" } ], "responses": { "200": { "description": "Chain details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChainResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/admin/chains": { "get": { "tags": [ "Chains" ], "summary": "List all chains including disabled (admin)", "operationId": "adminListChains", "responses": { "200": { "description": "Full chain list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChainListResponse" } } } } } }, "post": { "tags": [ "Chains" ], "summary": "Add a chain (admin)", "operationId": "createChain", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChainRequest" } } } }, "responses": { "201": { "description": "Chain added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChainResponse" } } } } } } }, "/v1/admin/chains/{chain_id}": { "put": { "tags": [ "Chains" ], "summary": "Update a chain (admin)", "operationId": "updateChain", "parameters": [ { "name": "chain_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChainRequest" } } } }, "responses": { "200": { "description": "Chain updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChainResponse" } } } } } }, "delete": { "tags": [ "Chains" ], "summary": "Remove a chain (admin)", "operationId": "deleteChain", "parameters": [ { "name": "chain_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Chain removed" } } } }, "/v1/secrets/{secret_id}/share": { "post": { "tags": [ "Sharing" ], "summary": "Create a share link for a secret", "operationId": "createShare", "x-agentcash-auth": { "mode": "paid" }, "x-payment-info": { "protocols": [ "x402" ], "pricingMode": "fixed", "price": "0.003" }, "parameters": [ { "name": "secret_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShareRequest" } } } }, "responses": { "201": { "description": "Share created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareResponse" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/share/{share_id}": { "get": { "tags": [ "Sharing" ], "summary": "Access a shared secret", "operationId": "accessShare", "security": [], "x-agentcash-auth": { "mode": "paid" }, "x-payment-info": { "protocols": [ "x402" ], "pricingMode": "fixed", "price": "0.0015" }, "parameters": [ { "name": "share_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Shared secret value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedSecretResponse" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Sharing" ], "summary": "Revoke a share link", "operationId": "revokeShare", "parameters": [ { "name": "share_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Share revoked" } } } }, "/v1/shares/outbound": { "get": { "tags": [ "Sharing" ], "summary": "List shares you have sent", "operationId": "listOutboundShares", "responses": { "200": { "description": "Outbound share list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareListResponse" } } } } } } }, "/v1/shares/inbound": { "get": { "tags": [ "Sharing" ], "summary": "List shares sent to you", "operationId": "listInboundShares", "responses": { "200": { "description": "Inbound share list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShareListResponse" } } } } } } }, "/v1/shares/{share_id}/accept": { "post": { "tags": [ "Sharing" ], "summary": "Accept an inbound share", "operationId": "acceptShare", "parameters": [ { "name": "share_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Share accepted" } } } }, "/v1/shares/{share_id}/decline": { "post": { "tags": [ "Sharing" ], "summary": "Decline an inbound share", "operationId": "declineShare", "parameters": [ { "name": "share_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Share declined" } } } }, "/v1/org/members": { "get": { "tags": [ "Organization" ], "summary": "List organization members", "operationId": "listOrgMembers", "responses": { "200": { "description": "Member list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgMemberListResponse" } } } } } } }, "/v1/org/agent-keys-vault": { "get": { "tags": [ "Organization" ], "summary": "Get the org's __agent-keys vault id", "description": "Returns the vault id for the caller's org agent-keys vault (used for revealing agent identity keys). Users only; 404 if the vault does not exist.", "operationId": "getAgentKeysVault", "responses": { "200": { "description": "Agent-keys vault id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentKeysVaultResponse" } } } }, "404": { "description": "Agent-keys vault not found" } } } }, "/v1/org/status": { "get": { "tags": [ "Organization" ], "summary": "Organization operational status", "description": "Returns whether the org is emergency-frozen (blocks agent tx/execution).", "operationId": "getOrgStatus", "responses": { "200": { "description": "Current org status", "content": { "application/json": { "schema": { "type": "object", "required": [ "org_id", "status" ], "properties": { "org_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "frozen" ] }, "frozen_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "403": { "description": "Forbidden" } } } }, "/v1/org/freeze": { "post": { "tags": [ "Organization" ], "summary": "Emergency org-wide freeze", "description": "Sets organizations.frozen_at — blocks agent tx/execution until unfreeze. Owner/admin only.", "operationId": "freezeOrg", "responses": { "200": { "description": "Organization frozen", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "frozen" ] }, "org_id": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Forbidden" } } } }, "/v1/org/unfreeze": { "post": { "tags": [ "Organization" ], "summary": "Clear org-wide freeze", "description": "Clears organizations.frozen_at. Owner/admin only.", "operationId": "unfreezeOrg", "responses": { "200": { "description": "Organization unfrozen", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "unfrozen" ] }, "org_id": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Forbidden" } } } }, "/v1/org/bankr-config": { "get": { "tags": [ "Organization" ], "summary": "Get org Bankr partner configuration", "description": "Returns whether the org has configured Bankr BYOK (partner key prefix and default wallet only — never the secret). Users only.", "operationId": "getOrgBankrConfig", "responses": { "200": { "description": "Bankr configuration status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgBankrConfigResponse" } } } } } }, "put": { "tags": [ "Organization" ], "summary": "Set org Bankr partner configuration", "description": "Store or replace the org's Bankr partner key (`bk_ptr_...`) and optional default wallet (`wlt_...`). Owner/admin only. Partner key encrypted at rest.", "operationId": "upsertOrgBankrConfig", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertOrgBankrConfigRequest" } } } }, "responses": { "200": { "description": "Configuration saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgBankrConfigResponse" } } } } } }, "delete": { "tags": [ "Organization" ], "summary": "Remove org Bankr partner configuration", "description": "Delete BYOK credentials for the org. Owner/admin only.", "operationId": "deleteOrgBankrConfig", "responses": { "204": { "description": "Configuration removed" }, "404": { "description": "Configuration not found" } } } }, "/v1/org/invite": { "post": { "tags": [ "Organization" ], "summary": "Invite a member by email", "operationId": "inviteMember", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteMemberRequest" } } } }, "responses": { "200": { "description": "Invitation sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteMemberResponse" } } } } } } }, "/v1/org/members/{user_id}": { "patch": { "tags": [ "Organization" ], "summary": "Update a member's role", "operationId": "updateMemberRole", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemberRoleRequest" } } } }, "responses": { "200": { "description": "Role updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgMemberResponse" } } } } } }, "delete": { "tags": [ "Organization" ], "summary": "Remove a member from the organization", "operationId": "removeMember", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Member removed" } } } }, "/v1/org/env-vars": { "get": { "tags": [ "Organization" ], "summary": "List org shared environment variables", "operationId": "listOrgEnvVars", "responses": { "200": { "description": "Org shared environment variable list", "content": { "application/json": { "schema": { "type": "object", "properties": { "env_vars": { "type": "array", "items": { "$ref": "#/components/schemas/OrgEnvVar" } } } } } } } } }, "post": { "tags": [ "Organization" ], "summary": "Create org shared environment variable", "operationId": "createOrgEnvVar", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgEnvVarRequest" } } } }, "responses": { "201": { "description": "Org shared env var created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgEnvVar" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/org/env-vars/{key}": { "patch": { "tags": [ "Organization" ], "summary": "Update org shared environment variable", "operationId": "updateOrgEnvVar", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrgEnvVarRequest" } } } }, "responses": { "200": { "description": "Org shared env var updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgEnvVar" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/org/env-vars/{id}": { "delete": { "tags": [ "Organization" ], "summary": "Delete org shared environment variable", "operationId": "deleteOrgEnvVar", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" } } } }, "/v1/org/env-vars/{id}/link": { "post": { "tags": [ "Organization" ], "summary": "Link org shared env var to a vault", "operationId": "linkOrgEnvVar", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "vault_id" ], "properties": { "vault_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "Linked" } } } }, "/v1/org/env-vars/{id}/links/{vault_id}": { "delete": { "tags": [ "Organization" ], "summary": "Unlink org shared env var from a vault", "operationId": "unlinkOrgEnvVar", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "vault_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Unlinked" } } } }, "/v1/billing/usage": { "get": { "tags": [ "Billing" ], "summary": "Get usage summary (legacy)", "operationId": "billingUsage", "responses": { "200": { "description": "Usage summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummaryResponse" } } } } } } }, "/v1/billing/history": { "get": { "tags": [ "Billing" ], "summary": "Get usage event history (legacy)", "operationId": "billingHistory", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "Usage event list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageHistoryResponse" } } } } } } }, "/v1/billing/subscribe": { "post": { "tags": [ "Billing" ], "summary": "Start a subscription via Stripe Checkout", "operationId": "billingSubscribe", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscribeRequest" } } } }, "responses": { "200": { "description": "Checkout URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutUrlResponse" } } } } } } }, "/v1/billing/portal": { "post": { "tags": [ "Billing" ], "summary": "Open Stripe Customer Portal", "operationId": "billingPortal", "responses": { "200": { "description": "Portal URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortalUrlResponse" } } } } } } }, "/v1/billing/subscription": { "get": { "tags": [ "Billing" ], "summary": "Get subscription, usage, and credit summary", "operationId": "billingSubscription", "responses": { "200": { "description": "Full billing summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResponse" } } } } } } }, "/v1/billing/credits/topup": { "post": { "tags": [ "Billing" ], "summary": "Top up prepaid credits via Stripe", "operationId": "billingCreditTopup", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupRequest" } } } }, "responses": { "200": { "description": "Checkout URL for top-up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutUrlResponse" } } } } } } }, "/v1/billing/credits/balance": { "get": { "tags": [ "Billing" ], "summary": "Get credit balance", "operationId": "billingCreditBalance", "responses": { "200": { "description": "Credit balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditBalanceResponse" } } } } } } }, "/v1/billing/credits/transactions": { "get": { "tags": [ "Billing" ], "summary": "Get credit transaction ledger", "operationId": "billingCreditTransactions", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "Credit ledger", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditTransactionsListResponse" } } } } } } }, "/v1/billing/llm-token-billing": { "get": { "tags": [ "Billing" ], "summary": "Get LLM token billing status", "operationId": "getLlmTokenBilling", "description": "Returns whether LLM token billing is enabled, optional Stripe billing credit balance (metered scope), and estimated cycle usage from the upcoming invoice—including per-line metered rows when Stripe returns them (amounts; quantities such as tokens when present).\n", "responses": { "200": { "description": "LLM token billing status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LlmTokenBillingStatus" } } } } } } }, "/v1/billing/llm-token-billing/subscribe": { "post": { "tags": [ "Billing" ], "summary": "Subscribe to LLM token billing", "operationId": "subscribeLlmTokenBilling", "description": "Creates a Stripe Checkout session for the LLM token billing pricing plan. Returns a checkout URL to redirect the user. After the user completes checkout, a webhook activates LLM billing for the org.\n", "responses": { "200": { "description": "Stripe Checkout URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LlmCheckoutResponse" } } } } } } }, "/v1/billing/llm-token-billing/disable": { "post": { "tags": [ "Billing" ], "summary": "Disable LLM token billing", "operationId": "disableLlmTokenBilling", "description": "Disables LLM token billing for the org and cancels all active Stripe subscriptions for the LLM pricing plan. Agents will fall back to direct provider routing. You can re-enable it at any time.\n", "responses": { "200": { "description": "LLM billing disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LlmDisableResponse" } } } } } } }, "/v1/billing/llm-token-billing/cancel-duplicates": { "post": { "tags": [ "Billing" ], "summary": "Cancel duplicate LLM billing subscriptions", "operationId": "cancelLlmDuplicateSubscriptions", "description": "Cancels extra Stripe LLM billing subscriptions for the org, keeping a single primary subscription (active preferred over trialing). Does not change the org LLM billing enabled setting.\n", "responses": { "200": { "description": "Duplicate subscriptions cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LlmCancelDuplicatesResponse" } } } } } } }, "/v1/billing/overage-method": { "patch": { "tags": [ "Billing" ], "summary": "Set overage payment method", "operationId": "billingOverageMethod", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverageMethodRequest" } } } }, "responses": { "200": { "description": "Overage method updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OverageMethodResponse" } } } } } } }, "/v1/billing/webhooks": { "post": { "tags": [ "Billing" ], "summary": "Stripe webhook receiver", "operationId": "billingWebhook", "security": [], "responses": { "200": { "description": "Webhook processed" } } } }, "/v1/audit/events": { "get": { "tags": [ "Audit" ], "summary": "Query audit events", "operationId": "queryAuditEvents", "x-agentcash-auth": { "mode": "paid" }, "x-payment-info": { "protocols": [ "x402" ], "pricingMode": "fixed", "price": "0.0008" }, "parameters": [ { "name": "resource_id", "in": "query", "schema": { "type": "string" } }, { "name": "actor_id", "in": "query", "schema": { "type": "string" } }, { "name": "action", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Audit events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEventsResponse" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/audit/verify": { "get": { "tags": [ "Audit" ], "summary": "Verify audit hash chain integrity", "operationId": "verifyAuditChain", "description": "Verifies the HMAC-SHA256 integrity hash chain for audit events in the\ncalling organization. Returns whether the chain is valid, how many\nevents were verified, and the point of first break (if any).\n", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 1000, "maximum": 10000 } } ], "responses": { "200": { "description": "Chain verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditVerifyResponse" } } } } } } }, "/v1/security/ip-rules": { "get": { "tags": [ "Security" ], "summary": "List IP rules", "operationId": "listIpRules", "responses": { "200": { "description": "IP rule list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpRulesListResponse" } } } } } }, "post": { "tags": [ "Security" ], "summary": "Create an IP rule", "operationId": "createIpRule", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIpRuleRequest" } } } }, "responses": { "201": { "description": "Rule created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpRuleResponse" } } } } } } }, "/v1/security/ip-rules/{rule_id}": { "delete": { "tags": [ "Security" ], "summary": "Delete an IP rule", "operationId": "deleteIpRule", "parameters": [ { "name": "rule_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Rule deleted" } } } }, "/v1/treasury": { "post": { "tags": [ "Treasury" ], "summary": "Create a treasury (Safe multisig)", "operationId": "createTreasury", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTreasuryRequest" } } } }, "responses": { "201": { "description": "Treasury created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "get": { "tags": [ "Treasury" ], "summary": "List treasuries", "operationId": "listTreasuries", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of treasuries", "content": { "application/json": { "schema": { "type": "object", "properties": { "treasuries": { "type": "array", "items": { "$ref": "#/components/schemas/TreasuryResponse" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/treasury/{treasury_id}": { "get": { "tags": [ "Treasury" ], "summary": "Get treasury details", "operationId": "getTreasury", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "treasury_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Treasury details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Treasury" ], "summary": "Update treasury name and/or threshold", "operationId": "updateTreasury", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "treasury_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTreasuryRequest" } } } }, "responses": { "200": { "description": "Treasury updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Treasury" ], "summary": "Delete a treasury and its signers", "operationId": "deleteTreasury", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "treasury_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Treasury deleted" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/treasury/{treasury_id}/signers": { "post": { "tags": [ "Treasury" ], "summary": "Add a signer to a treasury", "operationId": "addTreasurySigner", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "treasury_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddSignerRequest" } } } }, "responses": { "201": { "description": "Signer added" }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/v1/treasury/{treasury_id}/signers/{signer_id}": { "delete": { "tags": [ "Treasury" ], "summary": "Remove a signer from a treasury", "operationId": "removeTreasurySigner", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "treasury_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "signer_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Signer removed" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/treasury/{treasury_id}/access-requests": { "post": { "tags": [ "Treasury" ], "summary": "Request access to a treasury (agent-only)", "operationId": "requestTreasuryAccess", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "treasury_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Access request created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessRequestResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "get": { "tags": [ "Treasury" ], "summary": "List access requests for a treasury", "operationId": "listTreasuryAccessRequests", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "treasury_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of access requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "items": { "$ref": "#/components/schemas/AccessRequestResponse" } } } } } } } } } }, "/v1/treasury/{treasury_id}/access-requests/{request_id}/approve": { "post": { "tags": [ "Treasury" ], "summary": "Approve an access request", "operationId": "approveTreasuryAccess", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "treasury_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Access request approved" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/treasury/{treasury_id}/access-requests/{request_id}/deny": { "post": { "tags": [ "Treasury" ], "summary": "Deny an access request", "operationId": "denyTreasuryAccess", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "treasury_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Access request denied" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/treasury/{treasury_id}/proposals": { "post": { "tags": [ "Treasury Proposals" ], "summary": "Create a multisig proposal", "description": "Create a new Safe multisig transaction proposal. The proposer must be a\ntreasury signer or an agent with an active delegation for the treasury.\nIf auto-approve rules match, the agent's signature is auto-inserted and\nauto-execute fires if threshold is met.\n", "operationId": "createTreasuryProposal", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "treasury_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTreasuryProposalRequest" } } } }, "responses": { "201": { "description": "Proposal created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryProposalResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "get": { "tags": [ "Treasury Proposals" ], "summary": "List proposals for a treasury", "operationId": "listTreasuryProposals", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "treasury_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "approved", "executing", "executed", "rejected", "expired" ] } } ], "responses": { "200": { "description": "Proposal list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryProposalListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/treasury/{treasury_id}/proposals/{proposal_id}": { "get": { "tags": [ "Treasury Proposals" ], "summary": "Get a proposal with collected signatures", "operationId": "getTreasuryProposal", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "treasury_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "proposal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Proposal details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryProposalResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Treasury Proposals" ], "summary": "Cancel a pending proposal (proposer only)", "operationId": "cancelTreasuryProposal", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "treasury_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "proposal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Proposal cancelled" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/treasury/{treasury_id}/proposals/{proposal_id}/sign": { "post": { "tags": [ "Treasury Proposals" ], "summary": "Sign a proposal (approve or reject)", "description": "Submit an EIP-712 signature for a pending proposal. When approve signatures\nreach the Safe threshold, auto-execute fires: signatures are collected in\naddress-sorted order, `execTransaction` calldata is built, and the transaction\nis broadcast via RPC.\n", "operationId": "signTreasuryProposal", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "treasury_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "proposal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignTreasuryProposalRequest" } } } }, "responses": { "200": { "description": "Signature recorded (may include executed_tx_hash if auto-executed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryProposalResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/treasury/{treasury_id}/proposals/{proposal_id}/execute": { "post": { "tags": [ "Treasury Proposals" ], "summary": "Force-execute a proposal if threshold is met (user-only)", "operationId": "executeTreasuryProposal", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "treasury_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "proposal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Proposal executed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryProposalResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/treasury/wallets/generate": { "post": { "tags": [ "Treasury Wallets" ], "summary": "Generate multi-chain wallets for the authenticated user", "description": "Generates keypairs for the requested chains (or all supported chains if omitted).\nPrivate keys are stored in a per-org `__treasury-keys` vault with tier-appropriate\nMPC custody. Skips chains where the user already has an active wallet. Available\non all tiers (counts toward wallet quota). Human users only — agents get 403.\n", "operationId": "generateTreasuryWallets", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateTreasuryWalletsRequest" } } } }, "responses": { "201": { "description": "Wallets generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryWalletListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/treasury/wallets": { "get": { "tags": [ "Treasury Wallets" ], "summary": "List the authenticated user's treasury wallets", "operationId": "listTreasuryWallets", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Wallet list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryWalletListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/treasury/wallets/{chain}": { "get": { "tags": [ "Treasury Wallets" ], "summary": "Get the user's active wallet for a specific chain", "operationId": "getTreasuryWallet", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Chain name (e.g. ethereum, solana, bitcoin)" } ], "responses": { "200": { "description": "Wallet details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryWalletResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Treasury Wallets" ], "summary": "Deactivate the user's wallet for a specific chain", "operationId": "deactivateTreasuryWallet", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Wallet deactivated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/treasury/wallets/{chain}/export": { "post": { "tags": [ "Treasury Wallets" ], "summary": "Export the private key for a treasury wallet", "description": "Returns the raw private key hex for the user's active wallet on\nthe given chain. Requires re-authentication via the `X-Auth-Confirm`\nheader (account password). Audit-logged as `treasury_wallet.export`.\nHuman users only.\n", "operationId": "exportTreasuryWallet", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Auth-Confirm", "in": "header", "required": true, "description": "Account password for re-authentication", "schema": { "type": "string", "format": "password" } } ], "responses": { "200": { "description": "Private key exported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryWalletExportResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/treasury/wallets/{chain}/rotate": { "post": { "tags": [ "Treasury Wallets" ], "summary": "Rotate the user's wallet key for a chain", "description": "Generates a new keypair, deactivates the old wallet, and creates a\nnew active wallet. The old private key version is retained in the\nvault for audit. Counts toward wallet quota (does not require a paid plan).\n", "operationId": "rotateTreasuryWallet", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Wallet rotated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryWalletResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/treasury/wallets/{chain}/balance": { "get": { "tags": [ "Treasury Wallets" ], "summary": "Get wallet balance", "description": "Returns the native and token balances for the user's active wallet\non the specified chain.\n", "operationId": "getTreasuryWalletBalance", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tokens", "in": "query", "required": false, "description": "Optional list of ERC-20 contract addresses to query balances for", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Wallet balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryWalletBalanceResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/treasury/wallets/{chain}/send": { "post": { "tags": [ "Treasury Wallets" ], "summary": "Send from treasury wallet", "description": "Signs and broadcasts a transaction from the user's active wallet on\nthe specified chain. Requires re-authentication via `X-Auth-Confirm`\nheader (account password). Human users only.\n", "operationId": "sendFromTreasuryWallet", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Auth-Confirm", "in": "header", "required": true, "description": "Account password for re-authentication", "schema": { "type": "string", "format": "password" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryWalletSendRequest" } } } }, "responses": { "200": { "description": "Transaction sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryWalletSendResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/treasury/wallets/{chain}/swap": { "post": { "tags": [ "Treasury Wallets" ], "summary": "Swap tokens via DEX aggregator", "description": "Executes a token swap through a DEX aggregator from the user's active\nwallet on the specified chain. Requires re-authentication via\n`X-Auth-Confirm` header (account password). Human users only.\n", "operationId": "swapFromTreasuryWallet", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Auth-Confirm", "in": "header", "required": true, "description": "Account password for re-authentication", "schema": { "type": "string", "format": "password" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryWalletSwapRequest" } } } }, "responses": { "200": { "description": "Swap executed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryWalletSwapResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/treasury/wallets/{chain}/import": { "post": { "tags": [ "Treasury Wallets" ], "summary": "Import a treasury wallet", "description": "Import an existing private key as a treasury wallet. Human-only,\nrequires password re-authentication via X-Auth-Confirm header.\n", "operationId": "importTreasuryWallet", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "chain", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportKeyRequest" } } } }, "responses": { "201": { "description": "Treasury wallet imported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryWalletResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/treasury/wallets/auth-policy": { "get": { "tags": [ "Treasury Wallets" ], "summary": "Get effective human factor auth policy for embedded clients", "description": "Returns the resolved human factor auth (HFA) policy governing treasury\nwallet send, swap, and export, plus the number of passkeys registered\nfor the calling user. Intended for embedded wallet clients; equivalent\nto GET /v1/auth/human-factor-auth with an additional passkey count.\nPrecedence: user override → platform app → spend policy → defaults.\n", "operationId": "getTreasuryAuthPolicy", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Effective HFA policy with passkey registration count", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TreasuryAuthPolicyResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/treasury/wallets/spend-policy": { "get": { "tags": [ "Treasury Wallets" ], "summary": "Get effective spend policy for current user", "description": "Returns the effective spend policy governing the authenticated user's\nwallet transactions. Resolves from per-user override (if set) or the\napp-wide default. Returns null if no policy is configured.\n", "operationId": "getEffectiveSpendPolicy", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Effective spend policy", "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/SpendPolicyResponse" } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/treasury/wallets/inference-budget": { "get": { "tags": [ "Treasury Wallets" ], "summary": "Get inference budget for current user", "description": "Returns the user's remaining LLM inference allowance when connected via a platform app.\nIncludes allowance, spent, remaining USD, per-request cap, and billing period end.\n", "operationId": "getUserInferenceBudget", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Inference budget (or unconfigured message)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/InferenceBudgetResponse" }, { "$ref": "#/components/schemas/InferenceBudgetUnconfiguredResponse" } ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/webhooks": { "post": { "tags": [ "Webhooks" ], "summary": "Register a webhook", "operationId": "createWebhook", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } } }, "responses": { "201": { "description": "Webhook registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "operationId": "listWebhooks", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Webhook list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Get webhook", "operationId": "getWebhook", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Webhook details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Webhooks" ], "summary": "Update webhook", "operationId": "updateWebhook", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } } } }, "responses": { "200": { "description": "Webhook updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete webhook", "operationId": "deleteWebhook", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Webhook deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/admin/settings": { "get": { "tags": [ "Admin" ], "summary": "List platform settings", "operationId": "adminListSettings", "responses": { "200": { "description": "Settings list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsListResponse" } } } } } } }, "/v1/admin/settings/{key}": { "put": { "tags": [ "Admin" ], "summary": "Update a platform setting", "operationId": "adminUpdateSetting", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSettingRequest" } } } }, "responses": { "200": { "description": "Setting updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingResponse" } } } } } }, "delete": { "tags": [ "Admin" ], "summary": "Delete a platform setting", "operationId": "adminDeleteSetting", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Setting deleted" } } } }, "/v1/admin/x402": { "get": { "tags": [ "Admin" ], "summary": "Get x402 payment config", "operationId": "adminGetX402Config", "responses": { "200": { "description": "x402 config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402ConfigResponse" } } } } } }, "put": { "tags": [ "Admin" ], "summary": "Update x402 payment config", "operationId": "adminUpdateX402Config", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402ConfigResponse" } } } }, "responses": { "200": { "description": "Config updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402ConfigResponse" } } } } } } }, "/v1/admin/users": { "get": { "tags": [ "Admin" ], "summary": "List all platform users", "operationId": "adminListUsers", "responses": { "200": { "description": "User list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminUsersListResponse" } } } } } } }, "/v1/admin/users/{user_id}": { "delete": { "tags": [ "Admin" ], "summary": "Delete a user (cascade)", "operationId": "adminDeleteUser", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "User deleted" } } } }, "/v1/admin/orgs/{org_id}/limits": { "get": { "tags": [ "Admin" ], "summary": "Get org limits", "operationId": "adminGetOrgLimits", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Org limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgLimitsResponse" } } } } } }, "put": { "tags": [ "Admin" ], "summary": "Update org limits", "operationId": "adminUpdateOrgLimits", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrgLimitsRequest" } } } }, "responses": { "200": { "description": "Limits updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgLimitsResponse" } } } } } } }, "/v1/admin/orgs/{org_id}/billing-tier": { "put": { "tags": [ "Admin" ], "summary": "Set org billing tier (without Stripe)", "operationId": "adminSetBillingTier", "description": "Manually set an organization's billing tier to free, pro, business, or enterprise.\nFor testing, manual upgrades, and trial grants — does not create a Stripe subscription.\nSetting to \"pro\", \"business\", or \"enterprise\" sets period_end to now + duration_days (default 365).\nSetting to \"free\" clears subscription data. Use duration_days: 90 for a 3-month trial.\n", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetBillingTierRequest" } } } }, "responses": { "200": { "description": "Billing tier updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/admin/usage/reset": { "post": { "tags": [ "Admin" ], "summary": "Reset all API usage events (testing)", "operationId": "adminResetUsageEvents", "description": "Deletes every row in `usage_events` for all organizations. Resets monthly\nrequest counts used for free-tier / x402 quota. Does not change prepaid credit\nbalances or Stripe. **Platform admin only** (same guard as other `/v1/admin/*` routes).\n", "responses": { "200": { "description": "Usage table cleared; returns number of deleted rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetUsageEventsResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/admin/usage/reset-for-user": { "post": { "tags": [ "Admin" ], "summary": "Reset API usage for a user's organization", "operationId": "adminResetUsageForUserByEmail", "description": "Looks up a registered user by email and deletes all `usage_events` rows for that\nuser's `org_id`. Resets free-tier / monthly quota for the whole org (not other orgs).\n**Platform admin only.**\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetUsageForUserEmailRequest" } } } }, "responses": { "200": { "description": "Usage cleared for the user's org", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetUsageForUserEmailResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/health": { "get": { "tags": [ "Health" ], "summary": "Service health check", "operationId": "healthCheck", "security": [], "responses": { "200": { "description": "Healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/v1/health/hsm": { "get": { "tags": [ "Health" ], "summary": "HSM connectivity check", "operationId": "healthHsm", "security": [], "responses": { "200": { "description": "HSM status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded", "unavailable" ] } } } } } } } } }, "/v1/shroud/attestation": { "get": { "tags": [ "Shroud" ], "summary": "TEE attestation proof (public)", "operationId": "getShroudAttestation", "security": [], "description": "Public endpoint returning the TEE attestation proof for Shroud.\nReturns the GCE Confidential VM identity token and image hash so\ncustomers can verify Shroud is running inside a Confidential VM\nbefore signing contracts. Served from shroud.1claw.xyz.\n", "servers": [ { "url": "https://shroud.1claw.xyz" } ], "responses": { "200": { "description": "Attestation proof", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShroudAttestationResponse" } } } } } } }, "/v1/shroud/activity": { "get": { "tags": [ "Shroud" ], "summary": "List Shroud activity events", "description": "Returns recent Shroud proxy activity for the organization (LLM requests, inspections, policy actions).", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "agent_id", "schema": { "type": "string" }, "description": "Filter by agent ID" }, { "in": "query", "name": "action", "schema": { "type": "string" }, "description": "Filter by action (allowed, blocked, warned)" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 50 }, "description": "Maximum events to return" }, { "in": "query", "name": "offset", "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset" } ], "responses": { "200": { "description": "Activity events", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/ShroudActivityEvent" } }, "total": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized" } } }, "post": { "tags": [ "Shroud" ], "summary": "Ingest Shroud activity event (internal)", "description": "Called by the Shroud proxy to record activity events. Not intended for external use.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestShroudActivityRequest" } } } }, "responses": { "201": { "description": "Event recorded" }, "401": { "description": "Unauthorized" } } } }, "/v1/shroud/threat-summary": { "get": { "tags": [ "Shroud" ], "summary": "Shroud threat analytics summary", "description": "Aggregated threat metrics for the organization from `shroud_activity` (detectors, blocked counts, recent flagged requests). Query `period` selects the window; the previous window of equal length is used for request volume trend.\n", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "period", "schema": { "type": "string", "enum": [ "1h", "24h", "7d", "30d" ], "default": "24h" }, "description": "Rolling window ending now" } ], "responses": { "200": { "description": "Threat summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShroudThreatSummary" } } } }, "400": { "description": "Invalid period" }, "401": { "description": "Unauthorized" } } } }, "/v1/platform/apps": { "post": { "tags": [ "Platform" ], "summary": "Register a platform app", "description": "Register a new platform app for building on top of 1Claw. Returns an API key (plt_ prefix) that must be saved immediately.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlatformAppRequest" } } } }, "responses": { "201": { "description": "Platform app created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAppCreatedResponse" } } } }, "400": { "description": "Invalid request" }, "403": { "description": "Only human users can register platform apps" } } }, "get": { "tags": [ "Platform" ], "summary": "List platform apps", "description": "List all platform apps in the organization.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of platform apps", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformAppResponse" } } } } } } } }, "/v1/platform/apps/{appId}": { "get": { "tags": [ "Platform" ], "summary": "Get platform app details", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "appId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Platform app details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAppResponse" } } } }, "404": { "description": "Not found" } } }, "patch": { "tags": [ "Platform" ], "summary": "Update platform app", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "appId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePlatformAppRequest" } } } }, "responses": { "200": { "description": "Updated platform app", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAppResponse" } } } } } }, "delete": { "tags": [ "Platform" ], "summary": "Delete platform app", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "appId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Soft-deleted; slug released for reuse within the org", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAppDeleteResponse" } } } }, "403": { "description": "Only human users can delete platform apps" } } } }, "/v1/platform/apps/{appId}/transfer-ownership": { "post": { "tags": [ "Platform" ], "summary": "Transfer platform app to another organization", "description": "Moves the platform app record to another organization. Requires org\nowner/admin in the source org and step-up auth (`X-Auth-Confirm`,\npurpose `platform.app.transfer`). End-user connections and provisioned\nresources remain in their original organizations.\n", "operationId": "transferPlatformAppOwnership", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "appId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "X-Auth-Confirm", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferPlatformAppOwnershipRequest" } } } }, "responses": { "200": { "description": "Ownership transferred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferPlatformAppOwnershipResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/platform/apps/{appId}/rotate-key": { "post": { "tags": [ "Platform" ], "summary": "Rotate platform API key", "description": "Generate a new API key for the platform app. The old key is immediately invalidated. Returns the new key (one-time).", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Optional expiration for the new key." } } } } } }, "responses": { "200": { "description": "New key generated", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string", "description": "The new API key (shown once)" }, "api_key_prefix": { "type": "string" }, "api_key_expires_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "403": { "description": "Only human users can rotate platform keys" } } } }, "/v1/platform/apps/{appId}/stats": { "get": { "tags": [ "Platform" ], "summary": "Get platform app statistics", "description": "Returns aggregate statistics about a platform app's connected users, bootstraps, and grants.", "operationId": "getPlatformAppStats", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "App statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAppStatsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/platform/apps/{appId}/rotate-webhook-secret": { "post": { "tags": [ "Platform" ], "summary": "Rotate webhook secret", "description": "Generate a new webhook signing secret for the platform app. The old secret is immediately invalidated. Returns the new secret (one-time).", "operationId": "rotatePlatformWebhookSecret", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "New webhook secret generated", "content": { "application/json": { "schema": { "type": "object", "required": [ "webhook_secret" ], "properties": { "webhook_secret": { "type": "string", "description": "The new webhook signing secret (shown once)" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Only human users can rotate webhook secrets" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/platform/apps/{appId}/templates": { "post": { "tags": [ "Platform" ], "summary": "Create bootstrap template", "description": "Create a template that defines what vault, agents, and policies to bootstrap for each connected user.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "appId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateRequest" } } } }, "responses": { "201": { "description": "Template created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformTemplateResponse" } } } } } }, "get": { "tags": [ "Platform" ], "summary": "List templates", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "appId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of templates", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformTemplateResponse" } } } } } } } }, "/v1/platform/apps/{appId}/templates/{template_id}": { "patch": { "tags": [ "Platform" ], "summary": "Update a bootstrap template", "description": "Update an existing template's name, description, spec, or active status.", "operationId": "updatePlatformTemplate", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "appId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "template_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "spec": { "type": "object", "additionalProperties": true }, "is_active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Template updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformTemplateResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Platform" ], "summary": "Delete a bootstrap template", "operationId": "deletePlatformTemplate", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "appId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "template_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Template deleted" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/platform/apps/{appId}/templates/{template_id}/preview": { "post": { "tags": [ "Platform" ], "summary": "Preview resolved template spec", "description": "Resolves `{{params.*}}` and `{{subject.*}}` placeholders in a template spec\nwithout provisioning resources. Useful for validating parameterized bootstrap templates.\n", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "appId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "template_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePreviewRequest" } } } }, "responses": { "200": { "description": "Resolved template spec", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplatePreviewResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/platform/users/upsert": { "post": { "tags": [ "Platform" ], "summary": "Provision or look up a platform user", "description": "Upserts a user using either an OIDC subject_token (verified against the platform app's JWKS) or an email address. Returns the user handle and connection ID.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertPlatformUserRequest" } } } }, "responses": { "200": { "description": "Existing user found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformUserResponse" } } } }, "201": { "description": "New user created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformUserResponse" } } } }, "409": { "description": "User exists in a different organization. Contains a link_required payload with an OAuth authorize URL for cross-org consent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformUserLinkRequiredResponse" } } } } } } }, "/v1/platform/siwe/challenge": { "post": { "tags": [ "Platform" ], "summary": "Issue SIWE nonce", "description": "Creates a one-time nonce for Sign-In With Ethereum user provisioning.\nRequires platform (`plt_`) authentication. The nonce expires in 5 minutes.\n", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiweChallengeRequest" } } } }, "responses": { "200": { "description": "Nonce issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiweChallengeResponse" } } } }, "400": { "description": "SIWE domain not configured" } } } }, "/v1/platform/apps/{appId}/users": { "get": { "tags": [ "Platform" ], "summary": "List connected users", "description": "List all users connected to this platform app.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "appId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Connected users", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PlatformConnectedUserResponse" } } } } } } } }, "/v1/platform/connections/{connectionId}/bootstrap": { "post": { "tags": [ "Platform" ], "summary": "Bootstrap resources for a connected user", "description": "Executes a template to create vault, agent, and policies for the connected user. Returns a claim URL and token for the user to claim their resources.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "connectionId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BootstrapRequest" } } } }, "responses": { "201": { "description": "Resources bootstrapped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BootstrapResponse" } } } } } } }, "/v1/platform/connections/{connectionId}/reissue-claim": { "post": { "tags": [ "Platform" ], "summary": "Reissue a claim URL", "description": "Mints a fresh 10-minute claim token for an already-bootstrapped connection without re-provisioning resources. Use when the original claim URL has expired.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "connectionId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "return_to": { "type": "string", "description": "Optional redirect URL after claim" } } } } } }, "responses": { "200": { "description": "New claim URL issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "claim_url": { "type": "string" }, "claim_token": { "type": "string" }, "expires_in": { "type": "integer", "description": "Seconds until expiry (600 = 10 min)" }, "connection_id": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "Connection not yet bootstrapped" }, "404": { "description": "Connection not found" } } } }, "/v1/platform/connections/{connectionId}": { "get": { "tags": [ "Platform" ], "summary": "Get connection details", "description": "Returns connection status, claim state, wallet address, and provisioned resource IDs.\nUse for polling the claim loop after bootstrap.\n", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "connectionId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Connection details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionDetailResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/platform/connections/{connectionId}/usage": { "get": { "tags": [ "Platform" ], "summary": "Get per-connection usage", "description": "Returns inference spend for the current UTC month for this connection.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "connectionId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Usage summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionUsageResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/platform/connections/{connectionId}/entitlements": { "get": { "tags": [ "Platform" ], "summary": "List entitlement evaluations", "description": "Returns on-chain entitlement watch status for the connection.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "connectionId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Entitlement watches", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementsListResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/platform/connections/{connectionId}/entitlements/refresh": { "post": { "tags": [ "Platform" ], "summary": "Refresh entitlement evaluations", "description": "Triggers an immediate entitlement monitor cycle for this connection's org.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "connectionId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Refresh accepted" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/platform/apps/{appId}/audit": { "get": { "tags": [ "Platform" ], "summary": "Platform audit log", "description": "Returns audit events related to this platform app.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "appId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 50 } }, { "in": "query", "name": "offset", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Audit events", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/v1/platform/connected-apps": { "get": { "tags": [ "Platform" ], "summary": "List connected apps (user side)", "description": "Returns platform apps connected to the calling user's account.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Connected apps", "content": { "application/json": { "schema": { "type": "object", "properties": { "connected_apps": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectedAppResponse" } } } } } } } } } }, "/v1/platform/connected-apps/{connectionId}": { "patch": { "tags": [ "Platform" ], "summary": "Update connection delegation", "description": "Toggle delegation and update delegation scopes for a connected platform app. User-only.", "operationId": "updateConnectionDelegation", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "connectionId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "delegation_enabled": { "type": "boolean" }, "delegation_scopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes: vaults:read, vaults:write, agents:read, agents:write, secrets:read, secrets:write, automations:*, runtimes:*" } } } } } }, "responses": { "200": { "description": "Delegation settings updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid" }, "delegation_enabled": { "type": "boolean" }, "delegation_scopes": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Platform" ], "summary": "Disconnect a platform app", "description": "Disconnect the calling user from a platform app.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "connectionId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Disconnected" }, "404": { "description": "Connection not found" } } } }, "/v1/platform/connections/{connectionId}/delegation-log": { "get": { "tags": [ "Platform" ], "summary": "Delegation audit log", "description": "List delegated actions performed by a platform app on behalf of this user.", "operationId": "getDelegationLog", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "connectionId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Delegation log entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "scope": { "type": "string" }, "resource_type": { "type": "string" }, "resource_id": { "type": "string", "format": "uuid" }, "timestamp": { "type": "string", "format": "date-time" }, "details": { "type": "object", "additionalProperties": true, "nullable": true } } } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/platform/connections/{connectionId}/grant": { "post": { "tags": [ "Platform" ], "summary": "Grant platform app access to vaults/agents", "description": "User-authenticated. Grant the platform app access to selected vaults and agents.\nValidates user ownership of all requested resources. Creates platform_user_grants\nentries and merges resource IDs into the connection record.\n", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "connectionId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantResourcesRequest" } } } }, "responses": { "201": { "description": "Grants created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantResourcesResponse" } } } }, "400": { "description": "No vault_ids or agent_ids provided" }, "403": { "description": "Resource not owned by caller" }, "404": { "description": "Connection not found" } } } }, "/v1/platform/connections/{connectionId}/grants": { "get": { "tags": [ "Platform" ], "summary": "List active resource grants for a connection", "description": "User-authenticated. Returns active (non-revoked) grants for the connection.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "connectionId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Grant list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantListResponse" } } } }, "404": { "description": "Connection not found" } } } }, "/v1/platform/connections/{connectionId}/grants/{grantId}": { "delete": { "tags": [ "Platform" ], "summary": "Revoke a resource grant", "description": "User-authenticated. Revoke a specific resource grant by ID.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "connectionId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "grantId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Grant revoked" }, "404": { "description": "Grant not found or already revoked" } } } }, "/v1/platform/claim/{token}": { "get": { "tags": [ "Platform" ], "summary": "Preview a claim token", "description": "Verify a claim token and preview what was provisioned (app name, vaults, agents, policies).\nPublic endpoint — the token itself is the authentication.\n", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "type": "string" }, "description": "The `ct_` prefixed claim token from the bootstrap response" } ], "responses": { "200": { "description": "Claim preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimPreviewResponse" } } } }, "404": { "description": "Invalid or expired claim token" } } }, "post": { "tags": [ "Platform" ], "summary": "Redeem a claim token", "description": "Redeem a one-time claim token, marking the connection as claimed.\nPublic endpoint — the token itself is the authentication. Returns 409 if already claimed, 410 if expired.\n", "parameters": [ { "in": "path", "name": "token", "required": true, "schema": { "type": "string" }, "description": "The `ct_` prefixed claim token from the bootstrap response" } ], "responses": { "200": { "description": "Claim redeemed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimRedeemResponse" } } } }, "404": { "description": "Invalid claim token" }, "409": { "description": "Claim token already used" }, "410": { "description": "Claim token has expired" } } } }, "/v1/platform/apps/{appId}/spend-policies": { "post": { "tags": [ "Platform" ], "summary": "Create wallet spend policy", "description": "Create an app-wide spend policy that governs what embedded wallet users\ncan do with their wallets. Policies apply to all connected users by default\nand can be overridden per-user via connection-level policies.\n", "operationId": "createSpendPolicy", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "appId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSpendPolicyRequest" } } } }, "responses": { "201": { "description": "Spend policy created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendPolicyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "get": { "tags": [ "Platform" ], "summary": "List spend policies for app", "description": "Returns all spend policies configured for the platform app.", "operationId": "listSpendPolicies", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "appId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Spend policies", "content": { "application/json": { "schema": { "type": "object", "properties": { "policies": { "type": "array", "items": { "$ref": "#/components/schemas/SpendPolicyResponse" } } } } } } } } } }, "/v1/platform/apps/{appId}/spend-policies/{policyId}": { "get": { "tags": [ "Platform" ], "summary": "Get a spend policy by ID", "operationId": "getSpendPolicy", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "appId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "policyId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Spend policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendPolicyResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Platform" ], "summary": "Delete a spend policy", "operationId": "deleteSpendPolicy", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "appId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "policyId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/platform/connections/{connectionId}/spend-policy": { "get": { "tags": [ "Platform" ], "summary": "Get effective spend policy for a connection", "description": "Returns the effective spend policy for the connected user, resolving\nper-user overrides before app-level defaults. Requires plt_ platform auth.\n", "operationId": "getConnectionSpendPolicy", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "connectionId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Effective spend policy (or null)", "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "oneOf": [ { "$ref": "#/components/schemas/SpendPolicyResponse" }, { "type": "null" } ] } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Platform" ], "summary": "Set per-user spend policy override", "description": "Override the app-wide spend policy for a specific connected user. This\npolicy takes precedence over the app default. Remove by deleting the\nconnection-level policy.\n", "operationId": "setUserSpendPolicy", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "connectionId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "type": "string" }, "description": "Optional replay protection; same key + body returns cached response (409 on body mismatch)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSpendPolicyRequest" } } } }, "responses": { "200": { "description": "Spend policy set (or idempotent replay)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendPolicyResponse" } } } }, "201": { "description": "Spend policy created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendPolicyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Idempotency-Key reused with different body" } } } }, "/v1/platform/connections/{connectionId}/approvals": { "get": { "tags": [ "Platform" ], "summary": "List approvals for a platform connection", "description": "Returns approvals assigned to the connection's user, filtered to agents\nprovisioned on the connection. Requires plt_ platform auth.\n", "operationId": "listConnectionApprovals", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "connectionId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "risk_tier", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Connection-scoped approvals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalListResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/platform/connections/{connectionId}/approvals/{approvalId}": { "get": { "tags": [ "Platform" ], "summary": "Get a connection-scoped approval", "operationId": "getConnectionApproval", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "connectionId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "approvalId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Approval detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/platform/connections/{connectionId}/pending-approvals": { "get": { "tags": [ "Platform" ], "summary": "List pending consensus approvals for a connection", "description": "Returns pending approvals for agents provisioned on the connection,\nincluding `action_payload` and `payload_hash` for consensus UX.\nRequires plt_ platform auth.\n", "operationId": "listConnectionPendingApprovals", "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "connectionId", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "schema": { "type": "string", "default": "pending" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Pending approvals list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingApprovalListResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/approvals": { "get": { "tags": [ "Approvals" ], "summary": "List pending approvals", "description": "Returns approvals for the authenticated user's organization.\nHuman-only. Supports filtering by status and pagination.\n", "operationId": "listApprovals", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired" ] }, "description": "Filter by approval status" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Approval list", "content": { "application/json": { "schema": { "type": "object", "required": [ "approvals" ], "properties": { "approvals": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalResponse" } } } } } } } } } }, "/v1/approvals/{approval_id}": { "get": { "tags": [ "Approvals" ], "summary": "Get approval details", "description": "Returns details for a single approval by ID.", "operationId": "getApproval", "parameters": [ { "name": "approval_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Approval details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/approvals/{approval_id}/status": { "get": { "tags": [ "Approvals" ], "summary": "Poll approval status (agent-only)", "description": "Lightweight status poll for agents waiting on human approval.\nReturns `status` and `expires_at` only. Agents may only poll\napprovals they created (`agent_id` must match the caller).\n", "operationId": "getApprovalStatus", "parameters": [ { "name": "approval_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Approval status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalStatusResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/approvals/{approval_id}/decide": { "post": { "tags": [ "Approvals" ], "summary": "Approve or reject", "description": "Submit a decision (approve or reject) for a pending approval.\nHuman-only. The approval must be in `pending` status.\nFor `card_order` approvals, approving auto-executes the x402 payment;\nrejecting marks the card as `rejected`.\nRisk tier 2+ approvals require step-up authentication via\n`X-Auth-Confirm` (account password or `rat_` re-auth token from\n`POST /v1/auth/reauth/begin` + `complete`). Risk tier 3 requires\npasskey or TOTP re-auth token.\n", "operationId": "decideApproval", "parameters": [ { "name": "approval_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideApprovalRequest" } } } }, "responses": { "200": { "description": "Decision recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/approvals/quick-decide": { "get": { "tags": [ "Approvals" ], "summary": "One-click approve or deny (email link)", "description": "Public endpoint (no Bearer auth). The `token` query param is the\nauthenticator — SHA-256 hashed, single-use, 7-day TTL. On success\nredirects to `{public_url}/approvals/{id}?decided=true`.\nAuto-executes approved `card_order` and `policy_change` actions.\n", "operationId": "quickDecideApproval", "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "decision", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "approved", "rejected" ] } } ], "responses": { "302": { "description": "Redirect to dashboard confirmation page" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/deposit-destinations": { "post": { "tags": [ "Treasury" ], "summary": "Create deposit destination", "operationId": "createDepositDestination", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "chain" ], "properties": { "chain": { "type": "string" }, "label": { "type": "string" }, "treasury_wallet_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "Destination created" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "get": { "tags": [ "Treasury" ], "summary": "List deposit destinations", "operationId": "listDepositDestinations", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of destinations" } } } }, "/v1/deposit-destinations/{id}": { "get": { "tags": [ "Treasury" ], "summary": "Get deposit destination", "operationId": "getDepositDestination", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Destination detail with events" } } }, "patch": { "tags": [ "Treasury" ], "summary": "Update deposit destination status", "operationId": "updateDepositDestination", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "paused", "archived" ] } } } } } }, "responses": { "200": { "description": "Updated destination" } } } }, "/v1/internal-accounts": { "post": { "tags": [ "Treasury" ], "summary": "Create internal account", "operationId": "createInternalAccount", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } }, "responses": { "201": { "description": "Account created" } } }, "get": { "tags": [ "Treasury" ], "summary": "List internal accounts", "operationId": "listInternalAccounts", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Account list with balances" } } } }, "/v1/internal-accounts/{id}": { "get": { "tags": [ "Treasury" ], "summary": "Get internal account", "operationId": "getInternalAccount", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Account detail" } } } }, "/v1/internal-accounts/{id}/ledger": { "get": { "tags": [ "Treasury" ], "summary": "Get account ledger", "operationId": "getInternalAccountLedger", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Ledger entries" } } } }, "/v1/internal-transfers": { "post": { "tags": [ "Treasury" ], "summary": "Transfer between internal accounts", "operationId": "createInternalTransfer", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from_account_id", "to_account_id", "asset", "amount" ], "properties": { "from_account_id": { "type": "string", "format": "uuid" }, "to_account_id": { "type": "string", "format": "uuid" }, "asset": { "type": "string" }, "amount": { "type": "string" }, "memo": { "type": "string" } } } } } }, "responses": { "201": { "description": "Transfer completed" } } } }, "/v1/fiat/onramp/session": { "post": { "tags": [ "Billing" ], "summary": "Create fiat onramp session", "operationId": "createFiatOnrampSession", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Onramp widget URL" } } } }, "/v1/fiat/offramp/initiate": { "post": { "tags": [ "Billing" ], "summary": "Initiate fiat offramp", "operationId": "initiateFiatOfframp", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Offramp widget URL" } } } }, "/v1/auth/social-login": { "post": { "tags": [ "Authentication" ], "summary": "Social login (Google, Apple, Discord)", "operationId": "socialLogin", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "provider", "id_token" ], "properties": { "provider": { "type": "string", "enum": [ "google", "apple", "discord" ] }, "id_token": { "type": "string", "description": "Google/Apple ID token, or Discord OAuth authorization code" }, "oauth_redirect_uri": { "type": "string", "description": "Required for Discord — must match the redirect URI used in the OAuth flow" }, "auto_provision_chains": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Login successful" }, "201": { "description": "New user created" }, "401": { "description": "Invalid or unverified token" }, "409": { "description": "Email already registered (no auto-linking)" } } } }, "/v1/auth/passkeys/tx-assert/begin": { "post": { "tags": [ "Authentication" ], "summary": "Begin passkey transaction authorization", "description": "Requires `tx_digest` — SHA-256 hex of the canonical digest for the\ntreasury action being authorized (`send` or `swap`). The server\nrecomputes this digest on send/swap and rejects passkey tokens that\ndo not match.\n", "operationId": "passkeyTxAssertBegin", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyTxAssertBeginRequest" } } } }, "responses": { "200": { "description": "WebAuthn challenge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyAssertBeginResponse" } } } }, "400": { "description": "Missing or invalid tx_digest, or invalid action" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "No passkeys registered for the user" } } } }, "/v1/auth/passkeys/tx-assert/complete": { "post": { "tags": [ "Authentication" ], "summary": "Complete passkey transaction authorization", "operationId": "passkeyTxAssertComplete", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Passkey token for X-Passkey-Token header" } } } }, "/v1/auth/email-otp/send": { "post": { "tags": [ "Authentication" ], "summary": "Send email OTP code", "description": "Sends a 6-digit one-time code to the specified email address.\nNo authentication required. Rate-limited per IP and per email.\n", "operationId": "sendEmailOtp", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "platform_app_id": { "type": "string", "format": "uuid", "description": "Optional platform app context for embedded wallet flows" } } } } } }, "responses": { "200": { "description": "OTP sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "sent" ] } } } } } }, "429": { "description": "Rate limited" } } } }, "/v1/auth/email-otp/verify": { "post": { "tags": [ "Authentication" ], "summary": "Verify email OTP and get JWT", "description": "Verifies the 6-digit code sent to the user's email. If the user does not\nexist, a new account is created. Optionally auto-provisions treasury wallets\nfor the specified chains. Returns a JWT for subsequent API calls.\n", "operationId": "verifyEmailOtp", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "code" ], "properties": { "email": { "type": "string", "format": "email" }, "code": { "type": "string", "description": "6-digit OTP code" }, "platform_app_id": { "type": "string", "format": "uuid" }, "auto_provision_chains": { "type": "array", "items": { "type": "string" }, "description": "Chains to auto-generate wallets for (e.g. [\"ethereum\", \"base\"])" } } } } } }, "responses": { "200": { "description": "Existing user authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailOtpVerifyResponse" } } } }, "201": { "description": "New user created and authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailOtpVerifyResponse" } } } }, "400": { "description": "Invalid or expired code" }, "429": { "description": "Rate limited" } } } }, "/v1/oauth/authorize": { "get": { "tags": [ "OAuth" ], "summary": "Get OAuth consent info", "description": "Returns information about the platform app requesting authorization so the\nUI can display a consent screen. Used by the 1Claw-hosted consent page.\n", "operationId": "getOAuthConsent", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Platform app slug" }, { "name": "redirect_uri", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "response_type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "code" ] } }, { "name": "scope", "in": "query", "schema": { "type": "string" }, "description": "Space-delimited scopes (e.g. \"openid email wallet\")" }, { "name": "state", "in": "query", "schema": { "type": "string" } }, { "name": "code_challenge", "in": "query", "schema": { "type": "string" }, "description": "PKCE code challenge" }, { "name": "code_challenge_method", "in": "query", "schema": { "type": "string", "enum": [ "S256" ] }, "description": "Only S256 is supported (PKCE is mandatory for code grants)" }, { "name": "nonce", "in": "query", "schema": { "type": "string" }, "description": "OIDC nonce for ID token replay protection" }, { "name": "login_hint", "in": "query", "schema": { "type": "string" }, "description": "Pre-fill the email field on the consent page" } ], "responses": { "200": { "description": "Consent screen data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthConsentResponse" } } } }, "400": { "description": "Invalid client_id, redirect_uri, or response_type" } } }, "post": { "tags": [ "OAuth" ], "summary": "Submit OAuth consent decision", "description": "The user approves or denies the authorization request. On approval, returns\na redirect URL containing the authorization code. On denial, returns a\nredirect URL with an error parameter.\n", "operationId": "submitOAuthConsent", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "approve", "client_id", "redirect_uri" ], "properties": { "approve": { "type": "boolean" }, "client_id": { "type": "string" }, "redirect_uri": { "type": "string", "format": "uri" }, "scope": { "type": "string" }, "state": { "type": "string" }, "code_challenge": { "type": "string" }, "code_challenge_method": { "type": "string", "enum": [ "S256" ] }, "nonce": { "type": "string" } } } } } }, "responses": { "200": { "description": "Redirect URL with authorization code or error", "content": { "application/json": { "schema": { "type": "object", "required": [ "redirect_url" ], "properties": { "redirect_url": { "type": "string", "format": "uri" } } } } } }, "400": { "description": "Invalid request" } } } }, "/v1/oauth/token": { "post": { "tags": [ "OAuth" ], "summary": "Exchange authorization code for tokens", "description": "Standard OAuth 2.0 token endpoint. Exchanges an authorization code for an\naccess token and optional OIDC ID token. Supports PKCE via `code_verifier`.\n", "operationId": "exchangeOAuthToken", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "grant_type", "code", "client_id", "redirect_uri" ], "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code" ] }, "code": { "type": "string" }, "client_id": { "type": "string" }, "redirect_uri": { "type": "string", "format": "uri" }, "code_verifier": { "type": "string", "description": "PKCE code verifier (required — PKCE S256 is mandatory for all code grants)" } } } } } }, "responses": { "200": { "description": "Token response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenResponse" } } } }, "400": { "description": "Invalid grant, code, or verifier" }, "401": { "description": "Invalid client credentials" } } } }, "/v1/oauth/userinfo": { "get": { "tags": [ "OAuth" ], "summary": "Get authenticated user info (OIDC UserInfo)", "description": "Standard OIDC UserInfo endpoint. Returns claims about the authenticated user\nbased on the granted scopes.\n", "operationId": "getOAuthUserInfo", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "User info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthUserInfoResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/oauth/revoke": { "post": { "tags": [ "OAuth" ], "summary": "Revoke an OAuth token (RFC 7009)", "description": "Revokes an access token or refresh token. The authorization server\ninvalidates the token so it can no longer be used. Follows RFC 7009.\n", "operationId": "revokeOAuthToken", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string", "description": "The token to revoke (access_token or refresh_token)" }, "token_type_hint": { "type": "string", "enum": [ "access_token", "refresh_token" ], "description": "Hint about the type of token being revoked" } } } } } }, "responses": { "200": { "description": "Token revoked successfully (or was already invalid)", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean", "example": true } } } } } } } } }, "/v1/oauth/consents/{app_id}": { "delete": { "tags": [ "OAuth" ], "summary": "Revoke consent for a platform app", "description": "Revokes the user's previously granted OAuth consent for a specific platform app.\nAll active tokens issued to the app are invalidated and the consent record is deleted.\n", "operationId": "revokeOAuthConsent", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "app_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The platform app ID whose consent to revoke" } ], "responses": { "200": { "description": "Consent revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean", "example": true }, "app_id": { "type": "string", "format": "uuid" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/risk/events": { "get": { "tags": [ "Risk Engine" ], "summary": "List risk events", "description": "Returns risk events detected by the risk engine, ordered by most recent first.\nFilter by severity or principal type.\n", "operationId": "listRiskEvents", "parameters": [ { "name": "severity", "in": "query", "schema": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "description": "Filter events by severity level" }, { "name": "principal_type", "in": "query", "schema": { "type": "string", "enum": [ "user", "agent" ] }, "description": "Filter events by principal type" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Risk event list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiskEventListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/risk/verdicts": { "get": { "tags": [ "Risk Engine" ], "summary": "List risk verdicts", "description": "Returns all active risk verdicts for the caller's organization.", "operationId": "listRiskVerdicts", "responses": { "200": { "description": "Verdict list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RiskVerdictListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/risk/verdicts/{principal_type}/{principal_id}": { "get": { "tags": [ "Risk Engine" ], "summary": "Get risk verdict for a principal", "description": "Returns the current risk verdict for a specific user or agent.", "operationId": "getRiskVerdict", "parameters": [ { "name": "principal_type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "user", "agent" ] } }, { "name": "principal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Risk verdict (null if no verdict exists)", "content": { "application/json": { "schema": { "type": "object", "properties": { "verdict": { "$ref": "#/components/schemas/RiskVerdict", "nullable": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/risk/honeytokens": { "get": { "tags": [ "Risk Engine" ], "summary": "List honeytokens", "description": "Returns all honeytokens (canary secrets) configured for the caller's organization.", "operationId": "listHoneytokens", "responses": { "200": { "description": "Honeytoken list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HoneytokenListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Risk Engine" ], "summary": "Create a honeytoken", "description": "Register a secret path as a honeytoken (canary). Any access to this secret\ntriggers a risk event and increments the trigger counter.\n", "operationId": "createHoneytoken", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateHoneytokenRequest" } } } }, "responses": { "201": { "description": "Honeytoken created", "content": { "application/json": { "schema": { "type": "object", "properties": { "honeytoken": { "$ref": "#/components/schemas/Honeytoken" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/risk/honeytokens/{id}": { "delete": { "tags": [ "Risk Engine" ], "summary": "Delete a honeytoken", "description": "Remove a honeytoken registration. The underlying secret is not affected.", "operationId": "deleteHoneytoken", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Honeytoken deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/tokens": { "get": { "tags": [ "Tokens" ], "summary": "List known tokens", "operationId": "listKnownTokens", "parameters": [ { "name": "chain", "in": "query", "schema": { "type": "string" }, "description": "Filter by chain name" } ], "responses": { "200": { "description": "Token list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnownTokenListResponse" } } } } } } }, "/v1/chains/{chain_name}/tokens": { "get": { "tags": [ "Tokens" ], "summary": "List tokens for a specific chain", "operationId": "listTokensByChain", "parameters": [ { "name": "chain_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Token list for chain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnownTokenListResponse" } } } } } } }, "/v1/admin/tokens": { "post": { "tags": [ "Admin", "Tokens" ], "summary": "Create a known token (admin only)", "operationId": "createKnownToken", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKnownTokenRequest" } } } }, "responses": { "201": { "description": "Token created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnownToken" } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/admin/tokens/{token_id}": { "delete": { "tags": [ "Admin", "Tokens" ], "summary": "Delete a known token (admin only)", "operationId": "deleteKnownToken", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "token_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Token deleted" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/agents/{agent_id}/cards/order": { "post": { "tags": [ "Payment Cards" ], "summary": "Order a payment card (x402)", "description": "Order a prepaid or gift card for an agent. Drives the x402 payment flow server-side using the agent's Ethereum signing key (funded with USDC on Base). Requires `cards_enabled` on the agent and a Pro or higher plan. An `Idempotency-Key` header is required. When `card_require_approval` is true (default), the order is held in `awaiting_approval` until a human approves via the dashboard, mobile app, or email one-click link; payment runs only after approval.\n", "operationId": "orderCard", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCardRequest" } } } }, "responses": { "200": { "description": "Idempotent replay of a prior order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardResponse" } } } }, "201": { "description": "Card order accepted and payment submitted (status pending)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardResponse" } } } }, "202": { "description": "Card order queued for human approval (status awaiting_approval)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/cards": { "get": { "tags": [ "Payment Cards" ], "summary": "List payment cards", "description": "List cards for the caller (agents see only their own). Always masked (last4 only).", "operationId": "listCards", "responses": { "200": { "description": "Card list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardListResponse" } } } } } } }, "/v1/cards/import": { "post": { "tags": [ "Payment Cards" ], "summary": "Import a card (human-only)", "description": "Manually import an existing card. Full storage mode — PAN stored encrypted, CVV as a one-time-read secret. Human-only.", "operationId": "importCard", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportCardRequest" } } } }, "responses": { "201": { "description": "Card imported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/cards/gift-cards/search": { "post": { "tags": [ "Payment Cards" ], "summary": "Search gift-card brands", "description": "Search available Laso gift-card brands/servers for the org's Laso account.", "operationId": "searchGiftCards", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchGiftCardsRequest" } } } }, "responses": { "200": { "description": "Available gift-card brands (provider-shaped payload)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/v1/cards/{card_id}": { "get": { "tags": [ "Payment Cards" ], "summary": "Get a payment card", "description": "Get a single card (masked — last4 only).", "operationId": "getCard", "parameters": [ { "$ref": "#/components/parameters/CardId" } ], "responses": { "200": { "description": "Card details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Payment Cards" ], "summary": "Update a card's reveal policy (human-only)", "operationId": "updateCard", "parameters": [ { "$ref": "#/components/parameters/CardId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCardRequest" } } } }, "responses": { "200": { "description": "Card updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/cards/{card_id}/reveal": { "post": { "tags": [ "Payment Cards" ], "summary": "Reveal card details", "description": "Reveal full card details (PAN/CVV or gift-card redemption). Humans must re-authenticate with their account password via the `X-Auth-Confirm` header. Agents may reveal only when a human has enabled a per-card reveal policy. Once revealed, the card can be used anywhere up to its balance — 1Claw has no further control.\n", "operationId": "revealCard", "parameters": [ { "$ref": "#/components/parameters/CardId" }, { "name": "X-Auth-Confirm", "in": "header", "required": false, "description": "Account password (humans) for re-authentication.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revealed card details (sensitive)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardRevealResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/cards/{card_id}/void": { "post": { "tags": [ "Payment Cards" ], "summary": "Void a card", "description": "1Claw-level lock that blocks all further reveals/refreshes. Forward-looking only — a card revealed before void remains live.", "operationId": "voidCard", "parameters": [ { "$ref": "#/components/parameters/CardId" } ], "responses": { "200": { "description": "Card voided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/cards/{card_id}/refresh": { "post": { "tags": [ "Payment Cards" ], "summary": "Refresh a card's balance", "description": "Proxy Laso refresh to update balance/status. Rate-limited to once per 5 minutes per card (429 on exceed).", "operationId": "refreshCard", "parameters": [ { "$ref": "#/components/parameters/CardId" } ], "responses": { "200": { "description": "Card refreshed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "Refreshed too recently" } } } }, "/v1/automations": { "post": { "tags": [ "Automations" ], "summary": "Create automation", "operationId": "createAutomation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAutomationRequest" } } } }, "responses": { "201": { "description": "Automation created (includes one-time webhook credentials when trigger_type is webhook)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationCreatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "get": { "tags": [ "Automations" ], "summary": "List automations", "operationId": "listAutomations", "responses": { "200": { "description": "Automation list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/automations/{automationId}": { "get": { "tags": [ "Automations" ], "summary": "Get automation", "operationId": "getAutomation", "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Automation details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Automations" ], "summary": "Update automation", "operationId": "updateAutomation", "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAutomationRequest" } } } }, "responses": { "200": { "description": "Automation updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Automations" ], "summary": "Delete automation", "operationId": "deleteAutomation", "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Automation deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/automations/{automationId}/trigger": { "post": { "tags": [ "Automations" ], "summary": "Trigger automation", "operationId": "triggerAutomation", "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Automation triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRunResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/automations/{automationId}/runs": { "get": { "tags": [ "Automations" ], "summary": "List automation runs", "operationId": "listAutomationRuns", "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Automation run list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRunListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/automations/{automationId}/runs/{runId}": { "get": { "tags": [ "Automations" ], "summary": "Get automation run", "operationId": "getAutomationRun", "description": "Get details of a single automation run including step results and context.", "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Automation run detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRunResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/automations/assist/draft": { "post": { "tags": [ "Automations" ], "summary": "Draft automation from natural language", "operationId": "assistDraftAutomation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "agent_id": { "type": "string", "format": "uuid" }, "timezone": { "type": "string" } } } } } }, "responses": { "200": { "description": "Reviewable automation draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistDraftResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/automations/assist/session": { "post": { "tags": [ "Automations" ], "summary": "Mint short-lived Assist session token", "operationId": "assistAutomationSession", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "runtime_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Assist session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssistSessionResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/automations/webhook/{automationId}/{token}": { "post": { "tags": [ "Automations" ], "summary": "Public webhook trigger", "operationId": "webhookTriggerAutomation", "security": [], "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "description": "whk_ prefixed webhook token (SHA-256 verified server-side)" } } ], "responses": { "201": { "description": "Automation run queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRunResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/automations/{automationId}/rotate-webhook-token": { "post": { "tags": [ "Automations" ], "summary": "Rotate webhook token", "operationId": "rotateAutomationWebhookToken", "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "New one-time webhook URL and token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTokenRotatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/automations/{automationId}/runs/{runId}/cancel": { "post": { "tags": [ "Automations" ], "summary": "Cancel a running automation run", "operationId": "cancelAutomationRun", "description": "Cancel a run that is currently in `running` or `awaiting_approval` status.\nReturns the updated run with status `cancelled`.\n", "parameters": [ { "name": "automationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRunResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/automations/presets": { "get": { "tags": [ "Automations" ], "summary": "List automation presets", "operationId": "listAutomationPresets", "security": [], "description": "Public preset gallery of ready-to-use automation templates.", "responses": { "200": { "description": "Automation preset list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationPresetsResponse" } } } } } } }, "/v1/runtimes": { "post": { "tags": [ "Runtimes" ], "summary": "Create runtime", "operationId": "createRuntime", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRuntimeRequest" } } } }, "responses": { "201": { "description": "Runtime created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "get": { "tags": [ "Runtimes" ], "summary": "List runtimes", "operationId": "listRuntimes", "responses": { "200": { "description": "Runtime list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/runtimes/{runtimeId}": { "get": { "tags": [ "Runtimes" ], "summary": "Get runtime", "operationId": "getRuntime", "parameters": [ { "name": "runtimeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Runtime details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Runtimes" ], "summary": "Update runtime", "operationId": "updateRuntime", "parameters": [ { "name": "runtimeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRuntimeRequest" } } } }, "responses": { "200": { "description": "Runtime updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Runtimes" ], "summary": "Delete runtime", "operationId": "deleteRuntime", "parameters": [ { "name": "runtimeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Runtime deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/runtimes/{runtimeId}/start": { "post": { "tags": [ "Runtimes" ], "summary": "Start runtime", "operationId": "startRuntime", "parameters": [ { "name": "runtimeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Runtime started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/runtimes/{runtimeId}/stop": { "post": { "tags": [ "Runtimes" ], "summary": "Stop runtime", "operationId": "stopRuntime", "parameters": [ { "name": "runtimeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Runtime stopped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/runtimes/{runtimeId}/logs": { "get": { "tags": [ "Runtimes" ], "summary": "Get runtime logs", "operationId": "getRuntimeLogs", "parameters": [ { "name": "runtimeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "tail", "in": "query", "schema": { "type": "integer", "default": 100 }, "description": "Number of recent log lines to return" } ], "responses": { "200": { "description": "Runtime logs", "content": { "application/json": { "schema": { "type": "object", "required": [ "entries" ], "properties": { "entries": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "timestamp": { "type": "string", "format": "date-time" }, "message": { "type": "string" }, "level": { "type": "string" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/runtimes/slug-check/{slug}": { "get": { "tags": [ "Runtimes" ], "summary": "Check slug availability", "operationId": "checkSlugAvailability", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Slug availability result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlugCheckResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/runtimes/{runtimeId}/shell/session": { "post": { "tags": [ "Runtimes" ], "summary": "Create interactive shell session", "description": "Human-only. Creates a short-lived WebSocket session token for the\nruntime's PTY terminal. Requires step-up auth via `password`,\n`totp_code`, `passkey_credential`, or `reauth_token` (from\n`POST /v1/auth/reauth` with purpose `runtime_shell`).\nRuntime must have `shell_access_enabled` and be running.\nEnabling shell on a running runtime may require stop/start, or\nthe server may auto-reconcile the sidecar on connect.\n", "operationId": "createShellSession", "parameters": [ { "name": "runtimeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShellSessionRequest" } } } }, "responses": { "200": { "description": "Shell session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShellSessionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/runtimes/{runtimeId}/shell/passkey/begin": { "post": { "tags": [ "Runtimes" ], "summary": "Begin shell passkey assertion", "description": "Human-only. Starts a WebAuthn assertion ceremony for shell\nstep-up auth (social/Google users without a password).\n", "operationId": "beginShellPasskey", "parameters": [ { "name": "runtimeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Passkey challenge for shell session", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/runtimes/{runtimeId}/chat": { "post": { "tags": [ "Runtimes" ], "summary": "Chat with a running runtime agent", "description": "Human-only. Proxies to the runtime container's OpenAI-compatible\n`POST /v1/chat/completions` (hermes / openclaw / openclaude / opencode chat bridge).\nStarts the runtime if stopped. Streams SSE when `Accept: text/event-stream`\nor `stream: true`. Conversation history is ephemeral (pass `messages`).\nRequires a public URL (shell access, Shroud sidecar, or HTTP hosting).\n", "operationId": "runtimeChat", "parameters": [ { "name": "runtimeId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeChatRequest" } } } }, "responses": { "200": { "description": "Chat completion (JSON) or SSE stream", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/memory": { "get": { "tags": [ "Agent Memory" ], "summary": "List memory namespaces", "operationId": "listMemoryNamespaces", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "responses": { "200": { "description": "Namespace list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryNamespaceListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/memory/{namespace}": { "get": { "tags": [ "Agent Memory" ], "summary": "List entries in namespace", "operationId": "listMemoryEntries", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "namespace", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Memory entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryEntryListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/memory/{namespace}/{key}": { "put": { "tags": [ "Agent Memory" ], "summary": "Put memory entry", "operationId": "putMemoryEntry", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "namespace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutMemoryRequest" } } } }, "responses": { "200": { "description": "Memory entry stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "tags": [ "Agent Memory" ], "summary": "Get memory entry", "operationId": "getMemoryEntry", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "namespace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Memory entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryEntry" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Agent Memory" ], "summary": "Delete memory entry", "operationId": "deleteMemoryEntry", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "namespace", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Memory entry deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/memory/search": { "post": { "tags": [ "Agent Memory" ], "summary": "Semantic search", "operationId": "searchMemory", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemorySearchRequest" } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemorySearchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/card": { "get": { "tags": [ "Discovery" ], "summary": "Get agent card", "description": "Public endpoint returning the agent's discovery card metadata.", "operationId": "getAgentCard", "security": [], "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "responses": { "200": { "description": "Agent card", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCardResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/directory": { "get": { "tags": [ "Discovery" ], "summary": "Public agent directory", "description": "Browse the public directory of discoverable agents.", "operationId": "listDirectory", "security": [], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "tags", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated tag filter" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search query" } ], "responses": { "200": { "description": "Directory listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectoryResponse" } } } } } } }, "/v1/agents/org-directory": { "get": { "tags": [ "agents", "discovery" ], "summary": "List org agents", "description": "List agents within the caller's organization for sub-agent discovery.\nReturns agents with their capabilities, enabling agent-to-agent\ncoordination and discovery within an org. Requires authentication.\n", "operationId": "listOrgDirectory", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search query to filter agents by name or description" }, { "name": "tags", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated tag filter" }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "Org agent directory listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgDirectoryResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/agents/{agent_id}/discovery": { "patch": { "tags": [ "Discovery" ], "summary": "Update discovery settings", "operationId": "updateDiscoverySettings", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDiscoveryRequest" } } } }, "responses": { "200": { "description": "Discovery settings updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCardResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/platform/marketplace": { "get": { "tags": [ "Platform", "Discovery" ], "summary": "Public marketplace", "description": "Browse the public platform marketplace of listed apps and agents. Returns approved platform apps with category, tags, pricing summaries, and screenshots.", "operationId": "listMarketplace", "security": [], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search query" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Filter by app category" } ], "responses": { "200": { "description": "Marketplace listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketplaceResponse" } } } } } } }, "/v1/agents/{agent_id}/chat": { "post": { "tags": [ "Agent Chat" ], "summary": "Send chat message", "description": "Send a message to an agent and receive a response via Shroud LLM.\nSupports SSE streaming when Accept: text/event-stream is set.\n\nAgents can call this endpoint on other agents within the same\norganization for inter-agent communication (agent-to-agent chat).\nThe caller must be authenticated and belong to the same org as\nthe target agent.\n", "operationId": "sendChatMessage", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendChatMessageRequest" } } } }, "responses": { "200": { "description": "Chat response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendChatMessageResponse" } }, "text/event-stream": { "schema": { "type": "string", "description": "SSE stream of response chunks" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/agents/{agent_id}/chat/conversations": { "get": { "tags": [ "Agent Chat" ], "summary": "List conversations", "description": "List all chat conversations for an agent.", "operationId": "listChatConversations", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "responses": { "200": { "description": "Conversation list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatConversationListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/agents/{agent_id}/chat/conversations/{conversation_id}": { "get": { "tags": [ "Agent Chat" ], "summary": "Get conversation", "description": "Get a conversation with its full message history.", "operationId": "getChatConversation", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Conversation detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationDetailResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Agent Chat" ], "summary": "Archive conversation", "description": "Archive (soft-delete) a chat conversation.", "operationId": "deleteChatConversation", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Conversation archived" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/channels": { "post": { "tags": [ "Agent Channels" ], "summary": "Register channel", "description": "Register a new external messaging channel (Telegram, WhatsApp, Discord)\nfor an agent. Human-only. Returns the channel with its webhook URL.\n", "operationId": "createChannel", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChannelRequest" } } } }, "responses": { "201": { "description": "Channel created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "get": { "tags": [ "Agent Channels" ], "summary": "List channels", "description": "List all messaging channels for an agent.", "operationId": "listChannels", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "responses": { "200": { "description": "Channel list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/agents/{agent_id}/channels/{channel_id}": { "patch": { "tags": [ "Agent Channels" ], "summary": "Update channel", "description": "Update a channel's name, active status, or config. Human-only.", "operationId": "updateChannel", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "channel_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChannelRequest" } } } }, "responses": { "200": { "description": "Channel updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Agent Channels" ], "summary": "Delete channel", "description": "Delete a messaging channel. Human-only.", "operationId": "deleteChannel", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "channel_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Channel deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/channels/{channel_id}/send": { "post": { "tags": [ "Agent Channels" ], "summary": "Send outbound message", "description": "Send an outbound message via a registered channel.", "operationId": "sendChannelMessage", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "channel_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendChannelMessageRequest" } } } }, "responses": { "200": { "description": "Message sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelMessageResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/channels/{channel_id}/messages": { "get": { "tags": [ "Agent Channels" ], "summary": "Channel message history", "description": "List inbound and outbound messages for a channel.", "operationId": "listChannelMessages", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "channel_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "Message list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelMessageListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/agents/{agent_id}/channels/{channel_id}/test": { "post": { "tags": [ "Agent Channels" ], "summary": "Test channel connectivity", "description": "Send a test message through the channel to verify connectivity and credentials.", "operationId": "testChannel", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "channel_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "external_chat_id": { "type": "string", "description": "Optional chat ID to send the test message to" }, "content": { "type": "string", "description": "Optional custom test message content" } } } } } }, "responses": { "200": { "description": "Test result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string", "nullable": true }, "error": { "type": "string", "nullable": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/webhooks/telegram/{webhook_path}": { "post": { "tags": [ "Agent Channels" ], "summary": "Telegram webhook", "description": "Public webhook endpoint for receiving Telegram bot updates.", "operationId": "telegramWebhook", "security": [], "parameters": [ { "name": "webhook_path", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Webhook processed" } } } }, "/v1/webhooks/whatsapp/{webhook_path}": { "get": { "tags": [ "Agent Channels" ], "summary": "WhatsApp webhook verification", "description": "Verification endpoint for WhatsApp Cloud API webhook setup.", "operationId": "whatsappWebhookVerify", "security": [], "parameters": [ { "name": "webhook_path", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "hub.mode", "in": "query", "schema": { "type": "string" } }, { "name": "hub.verify_token", "in": "query", "schema": { "type": "string" } }, { "name": "hub.challenge", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Challenge response" } } }, "post": { "tags": [ "Agent Channels" ], "summary": "WhatsApp webhook", "description": "Public webhook endpoint for receiving WhatsApp Cloud API events.", "operationId": "whatsappWebhook", "security": [], "parameters": [ { "name": "webhook_path", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Webhook processed" } } } }, "/v1/webhooks/discord/{webhook_path}": { "post": { "tags": [ "Agent Channels" ], "summary": "Discord webhook", "description": "Public webhook endpoint for receiving Discord bot interactions.", "operationId": "discordWebhook", "security": [], "parameters": [ { "name": "webhook_path", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Webhook processed" } } } }, "/v1/oauth/providers": { "get": { "tags": [ "OAuth Connect" ], "summary": "List OAuth providers", "description": "Returns the list of supported OAuth providers with their metadata,\navailable scopes, and authorization URLs. No authentication required.\n", "operationId": "listOAuthProviders", "security": [], "responses": { "200": { "description": "Provider list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthProviderListResponse" } } } } } } }, "/v1/agents/{agent_id}/oauth/connect": { "post": { "tags": [ "OAuth Connect" ], "summary": "Initiate OAuth connection", "description": "Start an OAuth authorization flow for the specified agent and provider.\nReturns the authorization URL to redirect the user to. Human-only.\n", "operationId": "connectOAuth", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectOAuthRequest" } } } }, "responses": { "200": { "description": "Authorization URL generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectOAuthResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/oauth/connections": { "get": { "tags": [ "OAuth Connect" ], "summary": "List OAuth connections", "description": "List all active OAuth connections for the specified agent.", "operationId": "listOAuthConnections", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "responses": { "200": { "description": "Connection list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthConnectionListResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/oauth/disconnect/{binding_id}": { "post": { "tags": [ "OAuth Connect" ], "summary": "Disconnect OAuth connection", "description": "Disconnect an OAuth connection by revoking tokens and removing the binding.\nHuman-only.\n", "operationId": "disconnectOAuth", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "binding_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Connection disconnected" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/oauth/app-credentials": { "post": { "tags": [ "OAuth Connect" ], "summary": "Save OAuth app credentials", "description": "Store custom OAuth app credentials (client ID/secret) for a provider.\nAllows the agent to use a BYOA (Bring Your Own App) OAuth application\ninstead of 1Claw's shared credentials. Human-only.\n", "operationId": "saveOAuthAppCredentials", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveOAuthAppCredentialsRequest" } } } }, "responses": { "201": { "description": "Credentials saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthAppCredentialResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "tags": [ "OAuth Connect" ], "summary": "List OAuth app credentials", "description": "List stored OAuth app credentials for the agent. Client secrets\nare never returned in the response.\n", "operationId": "listOAuthAppCredentials", "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "responses": { "200": { "description": "Credential list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthAppCredentialListResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/agents/{agent_id}/oauth/app-credentials/{provider_slug}": { "delete": { "tags": [ "OAuth Connect" ], "summary": "Delete OAuth app credentials", "description": "Remove stored OAuth app credentials for a specific provider. Human-only.\n", "operationId": "deleteOAuthAppCredentials", "parameters": [ { "$ref": "#/components/parameters/AgentId" }, { "name": "provider_slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Provider identifier (e.g. \"github\", \"google\", \"slack\")" } ], "responses": { "204": { "description": "Credentials deleted" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/oauth/callback": { "get": { "tags": [ "OAuth Connect" ], "summary": "OAuth callback", "description": "Public callback URL that OAuth providers redirect to after user authorization.\nExchanges the authorization code for tokens and redirects to the dashboard.\n", "operationId": "oauthConnectCallback", "security": [], "parameters": [ { "name": "code", "in": "query", "schema": { "type": "string" }, "description": "Authorization code from the OAuth provider" }, { "name": "state", "in": "query", "schema": { "type": "string" }, "description": "Opaque state parameter for CSRF protection and session binding" }, { "name": "error", "in": "query", "schema": { "type": "string" }, "description": "Error code if the authorization was denied or failed" } ], "responses": { "302": { "description": "Redirect to dashboard with success or error status" } } } }, "/v1/org/cedar-policies": { "post": { "tags": [ "Cedar Policies" ], "summary": "Create a Cedar policy", "description": "Create a new Cedar policy for the organization. Team+ tier required.", "operationId": "createCedarPolicy", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCedarPolicyRequest" } } } }, "responses": { "201": { "description": "Cedar policy created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CedarPolicyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "get": { "tags": [ "Cedar Policies" ], "summary": "List Cedar policies", "description": "List all Cedar policies for the organization.", "operationId": "listCedarPolicies", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Cedar policies list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CedarPolicyListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/org/cedar-policies/{id}": { "get": { "tags": [ "Cedar Policies" ], "summary": "Get a Cedar policy", "description": "Retrieve a specific Cedar policy by ID.", "operationId": "getCedarPolicy", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Cedar policy details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CedarPolicyResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Cedar Policies" ], "summary": "Delete a Cedar policy", "description": "Delete a Cedar policy by ID.", "operationId": "deleteCedarPolicy", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Cedar policy deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/org/cedar-policies/test": { "post": { "tags": [ "Cedar Policies" ], "summary": "Test Cedar policy evaluation", "description": "Evaluate the organization's Cedar policies against a test request.", "operationId": "testCedarPolicy", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CedarPolicyTestRequest" } } } }, "responses": { "200": { "description": "Policy evaluation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CedarPolicyTestResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/org/opa-policies": { "post": { "tags": [ "OPA Policies" ], "summary": "Create an OPA policy", "description": "Create a new OPA Rego policy for the organization. Business+ tier required.", "operationId": "createOpaPolicy", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOpaPolicyRequest" } } } }, "responses": { "201": { "description": "OPA policy created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpaPolicyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "get": { "tags": [ "OPA Policies" ], "summary": "List OPA policies", "description": "List all OPA policies for the organization.", "operationId": "listOpaPolicies", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "OPA policies list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpaPolicyListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/org/opa-policies/{id}": { "get": { "tags": [ "OPA Policies" ], "summary": "Get an OPA policy", "description": "Retrieve a specific OPA policy by ID.", "operationId": "getOpaPolicy", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OPA policy details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpaPolicyResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "OPA Policies" ], "summary": "Delete an OPA policy", "description": "Delete an OPA policy by ID.", "operationId": "deleteOpaPolicy", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "OPA policy deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/org/opa-policies/test": { "post": { "tags": [ "OPA Policies" ], "summary": "Test OPA policy evaluation", "description": "Evaluate the organization's OPA policies against a test input.", "operationId": "testOpaPolicy", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpaPolicyTestRequest" } } } }, "responses": { "200": { "description": "Policy evaluation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpaPolicyTestResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/org/settings/policy-backend": { "get": { "tags": [ "Organization" ], "summary": "Get policy backend settings", "description": "Returns the org's Cedar/OPA enforcement configuration. Default mode is shadow.\nOwner/admin only.\n", "operationId": "getPolicyBackendSettings", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Policy backend settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyBackendSettingsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "patch": { "tags": [ "Organization" ], "summary": "Update policy backend settings", "description": "Configure backend (builtin, cedar, opa, builtin+cedar, builtin+opa), mode (shadow/enforce),\nscope actions, and circuit breaker behavior. Owner/admin only.\n", "operationId": "updatePolicyBackendSettings", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePolicyBackendSettingsRequest" } } } }, "responses": { "200": { "description": "Updated settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyBackendSettingsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/org/policy-shadow-report": { "get": { "tags": [ "Organization" ], "summary": "Get policy shadow divergence report", "description": "Returns divergence statistics when running Cedar/OPA in shadow mode.\nOwner/admin only.\n", "operationId": "getPolicyShadowReport", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Shadow divergence report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyShadowReportResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/org/guardrail-shadow-report": { "get": { "tags": [ "Organization" ], "summary": "Get guardrail shadow divergence report", "description": "Returns Convention 6 shadow-mode violations (`guardrail_shadow.would_deny` audit events)\ngrouped by reason code. Owner/admin only.\n", "operationId": "getGuardrailShadowReport", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Guardrail shadow report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardrailShadowReportResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/org/guardrail-revisions": { "get": { "tags": [ "Organization" ], "summary": "List guardrail revision history", "description": "Audit trail of agent and binding guardrail changes. Owner/admin only.", "operationId": "listGuardrailRevisions", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Guardrail revisions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardrailRevisionListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/org/contract-abis": { "post": { "tags": [ "Contract ABIs" ], "summary": "Register a contract ABI", "description": "Upload an org-scoped ABI for transaction decoding. Owner/admin only.", "operationId": "createContractAbi", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContractAbiRequest" } } } }, "responses": { "201": { "description": "ABI registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractAbiResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "get": { "tags": [ "Contract ABIs" ], "summary": "List contract ABIs", "description": "List org contract ABIs, optionally filtered by chain. Owner/admin only.", "operationId": "listContractAbis", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "chain", "in": "query", "schema": { "type": "string" }, "description": "Filter by chain name" } ], "responses": { "200": { "description": "ABI list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractAbiListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/org/contract-abis/{id}": { "get": { "tags": [ "Contract ABIs" ], "summary": "Get a contract ABI", "operationId": "getContractAbi", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "ABI details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractAbiResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Contract ABIs" ], "summary": "Delete a contract ABI", "operationId": "deleteContractAbi", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "ABI deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/pending-approvals": { "post": { "tags": [ "Pending Approvals" ], "summary": "Submit action for approval", "description": "Submit a signing or transaction action that matches a consensus policy trigger.", "operationId": "submitPendingApproval", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitPendingApprovalRequest" } } } }, "responses": { "202": { "description": "Approval required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitPendingApprovalResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "tags": [ "Pending Approvals" ], "summary": "List pending approvals", "operationId": "listPendingApprovals", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "agent_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Pending approvals list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingApprovalListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/pending-approvals/{id}": { "get": { "tags": [ "Pending Approvals" ], "summary": "Get pending approval details", "operationId": "getPendingApproval", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Pending approval with signatures", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingApprovalResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/pending-approvals/{id}/approve": { "post": { "tags": [ "Pending Approvals" ], "summary": "Approve or reject a pending approval", "operationId": "approvePendingApproval", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovePendingApprovalRequest" } } } }, "responses": { "200": { "description": "Updated pending approval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingApprovalResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/v1/pending-approvals/{id}/execute": { "post": { "tags": [ "Pending Approvals" ], "summary": "Execute an approved action", "description": "Human-only. Marks the approval as executed after verifying signatures.", "operationId": "executePendingApproval", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Action executed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutePendingApprovalResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/pending-approvals/{id}/cancel": { "post": { "tags": [ "Pending Approvals" ], "summary": "Cancel a pending approval", "operationId": "cancelPendingApproval", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Cancelled pending approval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingApprovalResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/org/sub-orgs": { "post": { "tags": [ "Sub-Organizations" ], "summary": "Create a sub-organization", "description": "Create a new sub-organization under the current org.", "operationId": "createSubOrg", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubOrgRequest" } } } }, "responses": { "201": { "description": "Sub-organization created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubOrgResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "get": { "tags": [ "Sub-Organizations" ], "summary": "List sub-organizations", "description": "List all sub-organizations under the current org.", "operationId": "listSubOrgs", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Sub-organizations list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubOrgListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/org/sub-orgs/{sub_org_id}": { "get": { "tags": [ "Sub-Organizations" ], "summary": "Get a sub-organization", "description": "Retrieve a specific sub-organization by ID.", "operationId": "getSubOrg", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "sub_org_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sub-organization details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubOrgResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Sub-Organizations" ], "summary": "Update a sub-organization", "description": "Update sub-organization name, description, or billing model.", "operationId": "updateSubOrg", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "sub_org_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubOrgRequest" } } } }, "responses": { "200": { "description": "Sub-organization updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubOrgResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Sub-Organizations" ], "summary": "Archive a sub-organization", "description": "Archive (soft-delete) a sub-organization.", "operationId": "deleteSubOrg", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "sub_org_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Sub-organization archived" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/org/sub-orgs/{sub_org_id}/users": { "post": { "tags": [ "Sub-Organizations" ], "summary": "Add a user to a sub-organization", "description": "Add a user to a sub-organization with a specified role.", "operationId": "addSubOrgUser", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "sub_org_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubOrgAddUserRequest" } } } }, "responses": { "201": { "description": "User added to sub-organization" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/org/sub-orgs/{sub_org_id}/permissions": { "post": { "tags": [ "Sub-Organizations" ], "summary": "Grant permissions to a sub-organization", "description": "Grant a permission scope to the sub-organization.", "operationId": "grantSubOrgPermission", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "sub_org_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubOrgPermissionRequest" } } } }, "responses": { "201": { "description": "Permission granted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/org/sub-orgs/{sub_org_id}/permissions/{permission}": { "delete": { "tags": [ "Sub-Organizations" ], "summary": "Revoke a sub-organization permission", "description": "Revoke a specific permission scope from the sub-organization.", "operationId": "revokeSubOrgPermission", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "sub_org_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "permission", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The permission scope to revoke" } ], "responses": { "204": { "description": "Permission revoked" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/org/sub-orgs/{sub_org_id}/wallets/generate": { "post": { "tags": [ "Sub-Organizations" ], "summary": "Generate wallets for a sub-organization", "description": "Generate treasury wallets for specified chains within the sub-org.", "operationId": "generateSubOrgWallets", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "sub_org_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubOrgGenerateWalletsRequest" } } } }, "responses": { "201": { "description": "Wallets generated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/portfolio": { "get": { "tags": [ "Portfolio" ], "summary": "Get unified portfolio", "description": "Returns an aggregated view of all wallet balances (treasury wallets,\nsigning keys, smart accounts) with USD estimates.\n", "operationId": "getPortfolio", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "chains", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated list of chain names to filter by (e.g. \"ethereum,solana\")" }, { "name": "include_tokens", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Whether to include token balances alongside native balances" } ], "responses": { "200": { "description": "Portfolio summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortfolioResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/agents/{agent_id}/smart-accounts/import": { "post": { "tags": [ "Agents" ], "summary": "Import an existing Safe smart account", "description": "Import an existing Safe smart account for an agent. Optionally verifies\non-chain that the agent's EOA is a signer on the Safe.\n", "operationId": "importSmartAccount", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/AgentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportSmartAccountRequest" } } } }, "responses": { "201": { "description": "Smart account imported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportSmartAccountResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/treasury/wallets/access-policies": { "post": { "tags": [ "Wallet Access" ], "summary": "Create a wallet access policy", "description": "Create a role-based wallet access policy granting an agent, user, role,\nor platform app specific permissions on treasury wallets within a scope\n(org-wide, platform app, or single wallet). Requires Pro+ tier.\n", "operationId": "createWalletAccessPolicy", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWalletAccessPolicyRequest" } } } }, "responses": { "201": { "description": "Policy created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletAccessPolicyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "get": { "tags": [ "Wallet Access" ], "summary": "List wallet access policies for the org", "operationId": "listWalletAccessPolicies", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "scope_type", "in": "query", "schema": { "type": "string", "enum": [ "wallet", "platform_app", "org" ] }, "description": "Filter by scope type" }, { "name": "scope_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filter by scope ID (wallet or platform app UUID)" } ], "responses": { "200": { "description": "Policy list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletAccessPolicyListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/treasury/wallets/access-policies/{id}": { "delete": { "tags": [ "Wallet Access" ], "summary": "Delete a wallet access policy", "operationId": "deleteWalletAccessPolicy", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Policy deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/auth/credential-recovery/request": { "post": { "tags": [ "Credential Recovery" ], "summary": "Initiate credential recovery", "description": "Start a credential recovery request for MFA reset, passkey reset,\nor password reset. Requires admin approval per org policy.\n", "operationId": "requestCredentialRecovery", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRecoveryRequest" } } } }, "responses": { "201": { "description": "Recovery request created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRecoveryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/auth/credential-recovery/requests": { "get": { "tags": [ "Credential Recovery" ], "summary": "List recovery requests for the org", "description": "Admin/owner only. Returns pending, approved, and rejected recovery requests.", "operationId": "listCredentialRecoveryRequests", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending_approval", "approved", "rejected", "expired" ] }, "description": "Filter by status" } ], "responses": { "200": { "description": "Recovery request list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRecoveryListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/auth/credential-recovery/requests/{id}/approve": { "post": { "tags": [ "Credential Recovery" ], "summary": "Approve a recovery request", "description": "Admin/owner approves a pending recovery request. May return a one-time recovery code.", "operationId": "approveCredentialRecovery", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Request approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRecoveryApproveResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/auth/credential-recovery/requests/{id}/execute": { "post": { "tags": [ "Credential Recovery" ], "summary": "Execute an approved credential recovery request", "description": "Execute an approved credential recovery request after the delay window has elapsed. Only org owners or admins can execute.", "operationId": "executeCredentialRecovery", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Recovery executed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRecoveryExecuteResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/auth/credential-recovery/requests/{id}": { "delete": { "tags": [ "Credential Recovery" ], "summary": "Cancel or reject a recovery request", "operationId": "cancelCredentialRecovery", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Request cancelled" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/org/credential-recovery-policy": { "get": { "tags": [ "Credential Recovery" ], "summary": "Get org credential recovery policy", "operationId": "getCredentialRecoveryPolicy", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Recovery policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRecoveryPolicyResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "patch": { "tags": [ "Credential Recovery" ], "summary": "Update org credential recovery policy", "operationId": "updateCredentialRecoveryPolicy", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRecoveryPolicyRequest" } } } }, "responses": { "200": { "description": "Policy updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialRecoveryPolicyResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/org/shamir-kek/setup": { "post": { "tags": [ "Shamir KEK" ], "summary": "Set up Shamir KEK for the org", "description": "Initialize a Shamir secret-sharing KEK for the org. Splits the master\nkey into shares distributed to custodians. Shares are returned one-time\nonly and must be stored securely by each custodian.\n", "operationId": "setupShamirKek", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShamirKekSetupRequest" } } } }, "responses": { "201": { "description": "Shamir KEK configured (shares returned one-time)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShamirKekSetupResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/org/shamir-kek": { "get": { "tags": [ "Shamir KEK" ], "summary": "Get Shamir KEK status", "description": "Returns the current Shamir KEK configuration status for the org.", "operationId": "getShamirKekStatus", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Shamir KEK status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShamirKekStatusResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/org/shamir-kek/reconstruct": { "post": { "tags": [ "Shamir KEK" ], "summary": "Reconstruct KEK from shares", "description": "Submit Shamir shares to reconstruct the org KEK. Requires at least\n`threshold` valid shares. Used during disaster recovery.\n", "operationId": "reconstructShamirKek", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShamirKekReconstructRequest" } } } }, "responses": { "200": { "description": "Reconstruction result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShamirKekReconstructResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/v1/org/shamir-kek/recovery-codes": { "get": { "tags": [ "Shamir KEK" ], "summary": "Get Shamir recovery codes (one-time)", "description": "Returns the one-time recovery codes for the Shamir KEK. These codes\ncan be used as an emergency fallback if custodian shares are lost.\nCodes are only returned once — subsequent calls return 410.\n", "operationId": "getShamirKekRecoveryCodes", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Recovery codes (one-time)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShamirKekRecoveryCodesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "410": { "description": "Codes already retrieved" } } } }, "/v1/org/shamir-kek/verify-recovery-code": { "post": { "tags": [ "Shamir KEK" ], "summary": "Verify a Shamir recovery code", "description": "Check whether a recovery code is valid without consuming it.", "operationId": "verifyShamirKekRecoveryCode", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShamirKekVerifyCodeRequest" } } } }, "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShamirKekVerifyCodeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "ApiKeyAuth": { "type": "http", "scheme": "bearer", "description": "1ck_ prefixed API key used as Bearer token" } }, "parameters": { "VaultId": { "name": "vault_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "SecretPath": { "name": "path", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Secret path (e.g. \"db/credentials\")" }, "AgentId": { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "PolicyId": { "name": "policy_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "CardId": { "name": "card_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "IncludeSignedTx": { "name": "include_signed_tx", "in": "query", "required": false, "description": "Set to `true` or `1` to include the raw signed transaction hex in the response. Omitted by default to reduce key exfiltration risk. Only the literal values \"true\" or \"1\" enable inclusion; any other value or omission returns responses without signed_tx. Applies to GET /v1/agents/{agent_id}/transactions and GET /v1/agents/{agent_id}/transactions/{tx_id}.\n", "schema": { "type": "boolean", "default": false, "example": false } } }, "responses": { "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "Authentication required or invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "PaymentRequired": { "description": "x402 payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequirement" } } } }, "Conflict": { "description": "Resource already exists or conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "schemas": { "OrderCardRequest": { "type": "object", "required": [ "kind", "amount_usd" ], "properties": { "kind": { "type": "string", "enum": [ "prepaid", "gift_card" ] }, "amount_usd": { "type": "string", "description": "USD amount to load onto the card.", "example": "25.00" }, "laso_server_id": { "type": "string", "description": "Optional Laso gift-card server/brand id (gift cards only)." }, "country": { "type": "string", "description": "Optional country (prepaid cards; defaults to US)." } } }, "CardResponse": { "type": "object", "description": "Masked card view — never contains PAN/CVV.", "required": [ "id", "issuer", "kind", "currency", "status", "storage_mode", "reveal_policy", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid", "nullable": true }, "issuer": { "type": "string", "enum": [ "laso", "manual" ] }, "kind": { "type": "string", "enum": [ "prepaid", "gift_card" ] }, "brand": { "type": "string" }, "last4": { "type": "string" }, "exp_month": { "type": "integer" }, "exp_year": { "type": "integer" }, "currency": { "type": "string" }, "order_amount_usd": { "type": "string" }, "balance": { "type": "string" }, "status": { "type": "string", "enum": [ "ordering", "pending", "ready", "depleted", "expired", "voided", "orphaned_payment", "awaiting_approval", "rejected" ] }, "storage_mode": { "type": "string", "enum": [ "reference", "full" ] }, "reveal_policy": { "type": "object", "additionalProperties": true }, "approval_id": { "type": "string", "format": "uuid", "description": "Linked approval when status is awaiting_approval" }, "void_after": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CardListResponse": { "type": "object", "required": [ "cards" ], "properties": { "cards": { "type": "array", "items": { "$ref": "#/components/schemas/CardResponse" } } } }, "CardRevealResponse": { "type": "object", "description": "Revealed card details — sensitive. Returned only by the reveal endpoint.", "required": [ "id", "disclaimer" ], "properties": { "id": { "type": "string", "format": "uuid" }, "pan": { "type": "string" }, "cvv": { "type": "string" }, "exp_month": { "type": "integer" }, "exp_year": { "type": "integer" }, "brand": { "type": "string" }, "redemption": { "type": "object", "additionalProperties": true, "description": "Gift-card redemption payload (URL/code/PIN) when applicable." }, "disclaimer": { "type": "string" } } }, "UpdateCardRequest": { "type": "object", "description": "Human-settable per-card reveal policy + lifecycle controls.", "properties": { "agent_reveal": { "type": "boolean" }, "max_reveals": { "type": "integer" }, "reveal_expires_at": { "type": "string", "format": "date-time", "nullable": true }, "void_after": { "type": "string", "format": "date-time", "nullable": true } } }, "ImportCardRequest": { "type": "object", "required": [ "pan", "cvv", "exp_month", "exp_year" ], "properties": { "pan": { "type": "string" }, "cvv": { "type": "string" }, "exp_month": { "type": "integer" }, "exp_year": { "type": "integer" }, "brand": { "type": "string" }, "currency": { "type": "string" }, "balance": { "type": "string" }, "agent_id": { "type": "string", "format": "uuid" } } }, "SearchGiftCardsRequest": { "type": "object", "properties": { "query": { "type": "string" }, "country": { "type": "string" } } }, "ProblemDetails": { "type": "object", "description": "RFC 7807 error envelope", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } } }, "ResetUsageEventsResponse": { "type": "object", "required": [ "deleted_events" ], "properties": { "deleted_events": { "type": "integer", "format": "int64", "description": "Number of usage_events rows removed" } } }, "ResetUsageForUserEmailRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } }, "ResetUsageForUserEmailResponse": { "type": "object", "required": [ "deleted_events", "org_id", "user_id", "email", "display_name" ], "properties": { "deleted_events": { "type": "integer", "format": "int64" }, "org_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "display_name": { "type": "string" } } }, "LoginRequest": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" } } }, "LoginResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string" }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" }, "mfa_required": { "type": "boolean" }, "mfa_token": { "type": "string" }, "mfa_method": { "type": "string", "enum": [ "totp", "passkey" ], "description": "When MFA is required, which second factor to collect" } } }, "TokenResponse": { "type": "object", "required": [ "access_token", "token_type" ], "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string" }, "expires_in": { "type": "integer" }, "refresh_token": { "type": "string" }, "mfa_required": { "type": "boolean" }, "mfa_token": { "type": "string" }, "mfa_method": { "type": "string", "enum": [ "totp", "passkey" ] } } }, "AgentTokenRequest": { "type": "object", "required": [ "api_key" ], "properties": { "agent_id": { "type": "string", "format": "uuid", "description": "Optional when using key-only auth (ocv_ keys auto-resolve agent)" }, "api_key": { "type": "string" } } }, "UserApiKeyTokenRequest": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string" } } }, "TokenExchangeRequest": { "type": "object", "required": [ "grant_type", "subject_token", "subject_token_type", "audience" ], "description": "RFC 8693 token-exchange request body. `subject_token_type`\naccepts the standard JWT URI or 1claw's API-key URI:\n - `urn:ietf:params:oauth:token-type:jwt`\n - `urn:1claw:params:oauth:token-type:api-key`\n", "properties": { "grant_type": { "type": "string", "enum": [ "urn:ietf:params:oauth:grant-type:token-exchange" ] }, "subject_token": { "type": "string", "description": "1claw JWT or `ocv_` API key authorising the exchange." }, "subject_token_type": { "type": "string", "enum": [ "urn:ietf:params:oauth:token-type:jwt", "urn:1claw:params:oauth:token-type:api-key" ] }, "audience": { "type": "string", "format": "uri", "description": "Required `aud` claim for the issued federation token (must be in agent's allowlist).", "example": "https://api.anthropic.com" }, "scope": { "type": "string", "description": "Optional space-separated subset of the agent's existing scopes." }, "requested_token_type": { "type": "string", "description": "Optional. Defaults to `urn:ietf:params:oauth:token-type:jwt`." } } }, "TokenExchangeResponse": { "type": "object", "required": [ "access_token", "issued_token_type", "token_type", "expires_in" ], "properties": { "access_token": { "type": "string", "description": "RS256-signed federation JWT." }, "issued_token_type": { "type": "string" }, "token_type": { "type": "string" }, "expires_in": { "type": "integer" }, "scope": { "type": "string" } } }, "SignupRequest": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "format": "password" }, "display_name": { "type": "string" } } }, "SignupResponse": { "type": "object", "properties": { "message": { "type": "string" }, "email": { "type": "string" }, "access_token": { "type": "string" }, "token_type": { "type": "string" } } }, "GoogleAuthRequest": { "type": "object", "required": [ "id_token" ], "properties": { "id_token": { "type": "string" } } }, "ChangePasswordRequest": { "type": "object", "required": [ "current_password", "new_password" ], "properties": { "current_password": { "type": "string" }, "new_password": { "type": "string" } } }, "ForgotPasswordRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } }, "ForgotPasswordResponse": { "type": "object", "required": [ "message", "status" ], "properties": { "message": { "type": "string" }, "status": { "type": "string", "enum": [ "email_sent", "no_account", "social_account", "invalid" ], "description": "Outcome of the reset request:\n- email_sent: password reset email dispatched\n- no_account: no account found for the email\n- social_account: account uses Google/SSO sign-in\n- invalid: request was malformed\n" } } }, "ResetPasswordRequest": { "type": "object", "required": [ "token", "new_password" ], "properties": { "token": { "type": "string" }, "new_password": { "type": "string" } } }, "ResetPasswordResponse": { "type": "object", "properties": { "message": { "type": "string" } } }, "MfaStatusResponse": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "eligible": { "type": "boolean" }, "totp_enabled": { "type": "boolean" }, "passkey_mfa_enabled": { "type": "boolean" } } }, "MfaSetupResponse": { "type": "object", "properties": { "otpauth_uri": { "type": "string" }, "secret": { "type": "string" } } }, "MfaVerifySetupRequest": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } }, "MfaVerifySetupResponse": { "type": "object", "properties": { "recovery_codes": { "type": "array", "items": { "type": "string" } } } }, "MfaVerifyRequest": { "type": "object", "required": [ "code", "mfa_token" ], "properties": { "code": { "type": "string" }, "mfa_token": { "type": "string" } } }, "MfaDisableRequest": { "type": "object", "properties": { "code": { "type": "string", "description": "TOTP or recovery code" }, "password": { "type": "string", "description": "Deprecated. Password is no longer sufficient to disable MFA.", "deprecated": true } } }, "DeviceCodeRequest": { "type": "object", "required": [ "client_id", "email" ], "properties": { "client_id": { "type": "string" }, "email": { "type": "string", "format": "email", "description": "Account email; only that user may approve the code in the dashboard." } } }, "DeviceCodeResponse": { "type": "object", "properties": { "device_code": { "type": "string" }, "user_code": { "type": "string" }, "verification_uri": { "type": "string", "format": "uri" }, "expires_in": { "type": "integer" }, "interval": { "type": "integer" } } }, "DeviceTokenRequest": { "type": "object", "required": [ "device_code", "grant_type" ], "properties": { "device_code": { "type": "string" }, "grant_type": { "type": "string" } } }, "DeviceTokenResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string" }, "expires_in": { "type": "integer" }, "error": { "type": "string" }, "email": { "type": "string" }, "user_id": { "type": "string" }, "org_id": { "type": "string" } } }, "DeviceApproveRequest": { "type": "object", "required": [ "user_code" ], "properties": { "user_code": { "type": "string" } } }, "UserProfileResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "display_name": { "type": "string" }, "auth_method": { "type": "string" }, "role": { "type": "string" }, "email_verified": { "type": "boolean" }, "marketing_emails": { "type": "boolean" }, "totp_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "UpdateProfileRequest": { "type": "object", "properties": { "display_name": { "type": "string" }, "marketing_emails": { "type": "boolean" } } }, "CreateApiKeyRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": "string", "format": "date-time" } } }, "ApiKeyResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "key_prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": "string", "format": "date-time" } } }, "ApiKeyCreatedResponse": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/ApiKeyResponse" }, "api_key": { "type": "string", "description": "Full key (shown once)" } } }, "ApiKeyListResponse": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyResponse" } } } }, "CreateVaultRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "mpc_custody": { "type": "string", "description": "MPC custody mode to enable at creation (e.g. \"2-of-2\", \"2-of-3\")" } } }, "VaultResponse": { "type": "object", "required": [ "id", "name", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "created_by": { "type": "string" }, "created_by_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "cmek_enabled": { "type": "boolean", "description": "Whether client-managed encryption is enabled" }, "cmek_fingerprint": { "type": "string", "description": "SHA-256 fingerprint of the CMEK key (64 hex chars)" }, "mpc_custody": { "type": "string", "description": "MPC custody mode (e.g. \"2-of-2\", \"2-of-3\"), absent when MPC is not enabled" }, "mpc_threshold": { "type": "integer", "description": "Number of shares required to reconstruct the key" }, "mpc_providers": { "type": "array", "items": { "type": "string" }, "description": "List of MPC share providers (e.g. [\"server\", \"client\"])" } } }, "VaultListResponse": { "type": "object", "properties": { "vaults": { "type": "array", "items": { "$ref": "#/components/schemas/VaultResponse" } } } }, "EnableCmekRequest": { "type": "object", "required": [ "fingerprint" ], "properties": { "fingerprint": { "type": "string", "description": "SHA-256 hex fingerprint of the CMEK key (64 chars)" } } }, "CmekRotateRequest": { "type": "object", "required": [ "new_fingerprint" ], "properties": { "new_fingerprint": { "type": "string", "description": "SHA-256 hex fingerprint of the new CMEK key" } } }, "CmekRotationJobResponse": { "type": "object", "required": [ "id", "vault_id", "status", "total_secrets", "processed", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "vault_id": { "type": "string", "format": "uuid" }, "old_fingerprint": { "type": "string" }, "new_fingerprint": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] }, "total_secrets": { "type": "integer" }, "processed": { "type": "integer" }, "error": { "type": "string" }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "EnableMpcRequest": { "type": "object", "required": [ "mpc_custody" ], "properties": { "mpc_custody": { "type": "string", "description": "MPC custody mode (e.g. \"2-of-2\", \"2-of-3\")" } } }, "PutSecretRequest": { "type": "object", "required": [ "value" ], "properties": { "type": { "type": "string", "description": "Secret type (generic, password, api_key, certificate, private_key, ssh_key, env)", "default": "generic" }, "value": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "expires_at": { "type": "string", "format": "date-time" }, "rotation_policy": { "type": "object", "additionalProperties": true }, "max_access_count": { "type": "integer" } } }, "SecretMetadataResponse": { "type": "object", "required": [ "id", "path", "type", "version", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "path": { "type": "string" }, "type": { "type": "string" }, "version": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "is_disabled": { "type": "boolean", "description": "Whether this version has been disabled (retained for audit but unreadable)" } } }, "SecretCreatedResponse": { "description": "Returned when a secret is created or updated. Extends SecretMetadataResponse with an optional client_share for MPC vaults.", "type": "object", "required": [ "id", "path", "type", "version", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "path": { "type": "string" }, "type": { "type": "string" }, "version": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "client_share": { "type": "string", "description": "Base64-encoded client key share. Returned only for MPC 2-of-2 vaults. The client must store this share securely — it is not persisted server-side." } } }, "SecretResponse": { "type": "object", "required": [ "id", "path", "type", "value", "version", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "path": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "version": { "type": "integer" }, "metadata": { "type": "object", "additionalProperties": true }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "cmek_encrypted": { "type": "boolean", "description": "Whether this secret value is CMEK-encrypted (requires client-side decryption)" } } }, "SecretListResponse": { "type": "object", "properties": { "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SecretMetadataResponse" } } } }, "SecretVersionListResponse": { "type": "object", "properties": { "versions": { "type": "array", "items": { "$ref": "#/components/schemas/SecretMetadataResponse" } } } }, "RotateSecretRequest": { "type": "object", "properties": { "length": { "type": "integer", "minimum": 8, "maximum": 1024, "description": "Length of the generated value (default 32)" }, "charset": { "type": "string", "enum": [ "hex", "base64", "alphanumeric", "ascii" ], "description": "Character set for the generated value (default hex)" }, "type": { "type": "string", "description": "Override the secret type (defaults to existing secret's type)" } } }, "CreatePolicyRequest": { "type": "object", "required": [ "secret_path_pattern", "principal_type", "principal_id", "permissions" ], "properties": { "secret_path_pattern": { "type": "string" }, "principal_type": { "type": "string", "enum": [ "user", "agent" ] }, "principal_id": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "conditions": { "type": "object", "additionalProperties": true }, "expires_at": { "type": "string", "format": "date-time" }, "effect": { "type": "string", "enum": [ "allow", "deny" ], "default": "allow" }, "priority": { "type": "integer", "minimum": 0, "default": 0 }, "attribute_conditions": { "type": "object", "additionalProperties": true }, "consensus_trigger": { "$ref": "#/components/schemas/ConsensusTrigger" }, "tx_conditions": { "$ref": "#/components/schemas/TxConditions" }, "approval_id": { "type": "string", "format": "uuid", "description": "Optional completed approval ID for control-plane consensus bypass. When control-plane consensus policies match, resubmit with this field after the approval has been executed.\n" }, "policy_schema_version": { "type": "integer", "default": 2, "description": "Policy schema version. Version 1 = legacy field-matching only.\nVersion 2 = expression engine support in tx_conditions.\n" } } }, "UpdatePolicyRequest": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "type": "string" } }, "conditions": { "type": "object", "additionalProperties": true }, "expires_at": { "type": "string", "format": "date-time" }, "effect": { "type": "string", "enum": [ "allow", "deny" ], "default": "allow" }, "priority": { "type": "integer", "minimum": 0, "default": 0 }, "attribute_conditions": { "type": "object", "additionalProperties": true }, "consensus_trigger": { "$ref": "#/components/schemas/ConsensusTrigger" }, "tx_conditions": { "$ref": "#/components/schemas/TxConditions" }, "approval_id": { "type": "string", "format": "uuid", "description": "Optional completed approval ID for control-plane consensus bypass.\n" } } }, "PolicyResponse": { "type": "object", "required": [ "id", "vault_id", "secret_path_pattern", "principal_type", "principal_id", "permissions", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "vault_id": { "type": "string", "format": "uuid" }, "secret_path_pattern": { "type": "string" }, "principal_type": { "type": "string" }, "principal_id": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "conditions": { "type": "object", "additionalProperties": true }, "expires_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string" }, "created_by_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "effect": { "type": "string", "enum": [ "allow", "deny" ], "default": "allow" }, "priority": { "type": "integer", "minimum": 0, "default": 0 }, "attribute_conditions": { "type": "object", "additionalProperties": true }, "consensus_trigger": { "$ref": "#/components/schemas/ConsensusTrigger" }, "tx_conditions": { "$ref": "#/components/schemas/TxConditions" }, "policy_schema_version": { "type": "integer", "description": "Policy schema version (1 = legacy, 2 = expression engine)" } } }, "PolicyListResponse": { "type": "object", "properties": { "policies": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyResponse" } } } }, "EnrollAgentRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Display name for the new agent" }, "human_email": { "type": "string", "format": "email", "description": "Optional. If set, pending enrollment is bound to that 1Claw account email\nand Allow/Deny links are emailed. If omitted, only `approval_url` is used\n(link-only enrollment; human must open the URL while signed in).\n" }, "description": { "type": "string", "description": "Optional agent description" } } }, "EnrollAgentResponse": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid", "description": "UUID of the created agent (nil UUID until approved — uniform response)" }, "message": { "type": "string", "description": "Status message (worded to limit email enumeration where applicable)" }, "approval_url": { "type": "string", "format": "uri", "description": "Present when a pending enrollment was created and the client should show\nthis link (email flow includes it as a fallback; name-only flow requires it).\n" } } }, "CreateAgentRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "auth_method": { "type": "string", "enum": [ "api_key", "mtls", "oidc_client_credentials" ], "default": "api_key", "description": "Authentication method. api_key generates a one-time key; mtls requires client_cert_fingerprint; oidc_client_credentials requires oidc_issuer and oidc_client_id." }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": "string", "format": "date-time" }, "intents_api_enabled": { "type": "boolean", "default": false }, "tx_to_allowlist": { "type": "array", "items": { "type": "string" } }, "tx_max_value": { "type": "string", "description": "Maximum value per transaction in native major units for the transacting chain family (ETH on EVM, BTC on Bitcoin, SOL on Solana, XRP, ADA, TRX)." }, "tx_daily_limit": { "type": "string", "description": "Rolling daily spend cap in native major units, enforced per chain family at signing time." }, "tx_max_value_eth": { "type": "string", "deprecated": true, "description": "Deprecated alias for tx_max_value. Same unit semantics (native major units, not ETH-only)." }, "tx_daily_limit_eth": { "type": "string", "deprecated": true, "description": "Deprecated alias for tx_daily_limit." }, "tx_allowed_chains": { "type": "array", "items": { "type": "string" } }, "token_ttl_seconds": { "type": "integer", "nullable": true, "description": "Per-agent token TTL in seconds (overrides global default)" }, "vault_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Restrict agent to specific vault UUIDs (empty = all vaults in org)" }, "client_cert_fingerprint": { "type": "string", "description": "SHA-256 fingerprint of the client certificate (required for mTLS auth)" }, "oidc_issuer": { "type": "string", "description": "OIDC issuer URL (required for oidc_client_credentials auth)" }, "oidc_client_id": { "type": "string", "description": "OIDC client ID (required for oidc_client_credentials auth)" }, "shroud_enabled": { "type": "boolean", "default": false, "description": "Enable Shroud LLM Proxy for this agent" }, "shroud_config": { "$ref": "#/components/schemas/ShroudConfig" }, "execution_intents_enabled": { "type": "boolean", "default": false, "description": "Enable Execution Intents (bindings and execute endpoint) for this agent" }, "execution_guardrails": { "type": "object", "additionalProperties": true, "description": "Guardrails applied to all execution intents for this agent" }, "intents_require_tee": { "type": "boolean", "default": false, "description": "When true, transaction/sign requests must arrive via a TEE host (Pro+ only)" }, "execution_require_tee": { "type": "boolean", "default": false, "description": "When true, execute requests must arrive via TEE and all direct secret reads are blocked (Pro+ only)" }, "tx_token_allowlist": { "type": "array", "items": { "type": "string" }, "description": "Token contract/mint addresses this agent may interact with. Empty = unrestricted." }, "tx_known_tokens_only": { "type": "boolean", "default": false, "description": "When true, only tokens in the known_tokens registry may be used." }, "xrpl_allowed_tx_types": { "type": "array", "items": { "type": "string" }, "description": "Allowed XRP Ledger transaction types (Payment, TrustSet, etc.). Empty = all allowed." }, "per_chain_guardrails": { "type": "object", "additionalProperties": true, "description": "Per-chain guardrail overrides. Keys are signing chains (ethereum, bitcoin, solana, xrp, cardano, tron).\nEach value may include max_value, daily_limit, to_allowlist, token_allowlist, max_per_day,\noverhead_budget, max_ata_creates_per_day, max_fee_per_gas_gwei, max_gas_limit,\ngas_daily_budget_native (UTC-day cumulative EVM gas estimate in native units).\nStrictest of global and per-chain limits wins. Daily limits apply per chain family spend, not cross-chain totals.\n" }, "tx_max_per_day": { "type": "integer", "nullable": true, "description": "Max transactions per UTC calendar day. Null = unlimited." }, "tx_overhead_budget": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" }, "description": "Per-chain daily overhead budget in native units (e.g. {\"solana\":\"0.5\",\"xrp\":\"100\"})." }, "solana_ata_allowlist": { "type": "array", "items": { "type": "string" }, "description": "Solana wallet addresses whose ATAs may be created. Empty = unrestricted." }, "cards_enabled": { "type": "boolean", "description": "Whether this agent may order payment cards (x402 card ordering). Pro+ tier." }, "card_max_order_usd": { "type": "string", "description": "Maximum USD amount for a single card order." }, "card_daily_limit_usd": { "type": "string", "description": "Maximum cumulative USD spent ordering cards per rolling 24h window." }, "card_payto_allowlist": { "type": "array", "items": { "type": "string" }, "description": "Allowed x402 payTo recipients for card orders (empty = built-in Laso recipients)." }, "card_reveal_enabled": { "type": "boolean", "description": "Whether agents may reveal card details subject to per-card reveal policy." }, "card_require_approval": { "type": "boolean", "default": true, "description": "When true, card orders route through the human approval queue before x402 payment." }, "tx_approval_policy": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Graduated transaction approval policy (HITL thresholds). Separate from hard guardrails." }, "typed_data_policy": { "type": "string", "enum": [ "deny", "approve" ], "description": "EIP-712 escalation when typed_data matches no allowlist — deny (403) or route to HITL (approve)." }, "simulation_failure_policy": { "type": "string", "enum": [ "deny", "approve" ], "description": "Simulation failure escalation — deny (422) or route to HITL (approve)." }, "tx_block_unlimited_approvals": { "type": "boolean", "default": false, "description": "Block unlimited ERC-20 approvals (max uint256 / setApprovalForAll)." }, "tx_per_recipient_max_per_day": { "type": "integer", "nullable": true, "description": "Max transactions to the same recipient address per UTC day." }, "tx_per_recipient_daily_limit": { "type": "string", "nullable": true, "description": "Max native-unit spend to the same recipient per UTC day." }, "new_recipient_cap_native": { "type": "string", "nullable": true, "description": "Cap on first-time recipient spend in native units." }, "tx_max_value_usd": { "type": "string", "nullable": true, "description": "Per-transaction USD cap (requires price oracle)." }, "tx_daily_limit_usd": { "type": "string", "nullable": true, "description": "Rolling 24h USD spend cap (requires price oracle)." }, "raw_signing_policy": { "type": "string", "enum": [ "allow", "deny", "approve" ], "default": "allow", "description": "Raw digest signing policy — allow, deny, or route to HITL (approve)." }, "personal_sign_policy": { "type": "object", "additionalProperties": true, "description": "personal_sign guardrails (message allowlist, max bytes, etc.)." }, "allow_erc4337": { "type": "boolean", "default": false, "description": "Allow ERC-4337 gasless UserOperations." }, "allow_eip7702": { "type": "boolean", "default": false, "description": "Allow EIP-7702 (tx type 4) set-code transactions." }, "api_key_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Optional expiration time for the agent's API key." }, "environment": { "type": "string", "description": "Named environment for this agent (production, preview, development, or custom)." }, "environment_locked": { "type": "boolean", "default": false, "description": "When true, the environment tag cannot be changed after creation." }, "env_auto_resolve": { "type": "boolean", "default": false, "description": "When true, env var resolve endpoints auto-fill environment from this agent's tag." }, "approval_id": { "type": "string", "format": "uuid", "description": "Optional completed approval ID for control-plane consensus bypass when creating an agent under a control-plane governance policy.\n" } } }, "UpdateAgentRequest": { "type": "object", "properties": { "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time" }, "intents_api_enabled": { "type": "boolean" }, "tx_to_allowlist": { "type": "array", "items": { "type": "string" } }, "tx_max_value": { "type": "string", "description": "Maximum value per transaction in native major units for the transacting chain family (ETH on EVM, BTC on Bitcoin, SOL on Solana, XRP, ADA, TRX)." }, "tx_daily_limit": { "type": "string", "description": "Rolling daily spend cap in native major units, enforced per chain family at signing time." }, "tx_max_value_eth": { "type": "string", "deprecated": true, "description": "Deprecated alias for tx_max_value. Same unit semantics (native major units, not ETH-only)." }, "tx_daily_limit_eth": { "type": "string", "deprecated": true, "description": "Deprecated alias for tx_daily_limit." }, "tx_allowed_chains": { "type": "array", "items": { "type": "string" } }, "token_ttl_seconds": { "type": "integer", "nullable": true }, "vault_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "shroud_enabled": { "type": "boolean", "description": "Enable/disable Shroud LLM Proxy" }, "shroud_config": { "$ref": "#/components/schemas/ShroudConfig" }, "execution_intents_enabled": { "type": "boolean", "description": "Enable/disable Execution Intents for this agent" }, "execution_guardrails": { "type": "object", "additionalProperties": true, "description": "Guardrails applied to all execution intents for this agent" }, "intents_require_tee": { "type": "boolean", "description": "When true, transaction/sign requests must arrive via a TEE host (Pro+ only)" }, "execution_require_tee": { "type": "boolean", "description": "When true, execute requests must arrive via TEE and all direct secret reads are blocked (Pro+ only)" }, "tx_max_per_day": { "type": "integer", "nullable": true, "description": "Max transactions per UTC calendar day. Null = unlimited." }, "tx_overhead_budget": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" }, "description": "Per-chain daily overhead budget in native units." }, "solana_ata_allowlist": { "type": "array", "items": { "type": "string" }, "description": "Solana wallet addresses whose ATAs may be created." }, "cards_enabled": { "type": "boolean", "description": "Whether this agent may order payment cards (x402 card ordering). Pro+ tier." }, "card_max_order_usd": { "type": "string", "nullable": true, "description": "Maximum USD amount for a single card order. null clears." }, "card_daily_limit_usd": { "type": "string", "nullable": true, "description": "Maximum cumulative USD spent ordering cards per rolling 24h window. null clears." }, "card_payto_allowlist": { "type": "array", "items": { "type": "string" }, "description": "Allowed x402 payTo recipients for card orders (empty = built-in Laso recipients)." }, "card_reveal_enabled": { "type": "boolean", "description": "Whether agents may reveal card details subject to per-card reveal policy." }, "card_require_approval": { "type": "boolean", "description": "When true, card orders route through the human approval queue before x402 payment." }, "tx_approval_policy": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Graduated transaction approval policy (HITL thresholds)." }, "typed_data_policy": { "type": "string", "enum": [ "deny", "approve" ], "nullable": true, "description": "EIP-712 escalation policy." }, "simulation_failure_policy": { "type": "string", "enum": [ "deny", "approve" ], "nullable": true, "description": "Simulation failure escalation policy." }, "tx_block_unlimited_approvals": { "type": "boolean", "description": "Block unlimited ERC-20 approvals (max uint256 / setApprovalForAll)." }, "tx_per_recipient_max_per_day": { "type": "integer", "nullable": true, "description": "Max transactions to the same recipient per UTC day. Null clears." }, "tx_per_recipient_daily_limit": { "type": "string", "nullable": true, "description": "Max native spend to same recipient per UTC day. Null clears." }, "new_recipient_cap_native": { "type": "string", "nullable": true, "description": "First-time recipient native cap. Null clears." }, "tx_max_value_usd": { "type": "string", "nullable": true, "description": "Per-tx USD cap. Null clears." }, "tx_daily_limit_usd": { "type": "string", "nullable": true, "description": "Rolling 24h USD spend cap. Null clears." }, "raw_signing_policy": { "type": "string", "enum": [ "allow", "deny", "approve" ], "description": "Raw digest signing policy." }, "personal_sign_policy": { "type": "object", "additionalProperties": true, "description": "personal_sign guardrails JSON." }, "allow_erc4337": { "type": "boolean", "description": "Allow ERC-4337 gasless UserOperations." }, "allow_eip7702": { "type": "boolean", "description": "Allow EIP-7702 (tx type 4)." }, "clear_auto_suspended": { "type": "boolean", "description": "When true, clears circuit-breaker auto-suspension (human owner/admin only)." }, "federation_enabled": { "type": "boolean", "description": "Enable OIDC federation (RFC 8693 token-exchange) for this agent.\nWhen true, the agent may call POST /v1/auth/federated-token to mint\nfederation tokens for the audiences listed in `federation_audiences`.\n" }, "federation_audiences": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Allowlist of `aud` values the federation token-exchange may issue\ntokens for (e.g. `[\"https://api.anthropic.com\"]`). Empty array\nblocks all federation requests (zero-trust default).\n" }, "federated_token_ttl_seconds": { "type": "integer", "minimum": 60, "maximum": 3600, "nullable": true, "description": "Per-agent TTL override for federation tokens (seconds). NULL falls\nback to the global default (`ONECLAW_JWT_FEDERATED_TOKEN_EXPIRY_SECS`).\nHard-capped at 3600 seconds.\n" }, "tx_token_allowlist": { "type": "array", "items": { "type": "string" }, "description": "Token contract/mint addresses this agent may interact with. Empty = unrestricted." }, "tx_known_tokens_only": { "type": "boolean", "default": false, "description": "When true, only tokens in the known_tokens registry may be used." }, "xrpl_allowed_tx_types": { "type": "array", "items": { "type": "string" }, "description": "Allowed XRP Ledger transaction types (Payment, TrustSet, etc.). Empty = all allowed." }, "per_chain_guardrails": { "type": "object", "additionalProperties": true, "description": "Per-chain guardrail overrides. Keys are signing chains (ethereum, bitcoin, solana, xrp, cardano, tron).\nEach value may include max_value, daily_limit, to_allowlist, token_allowlist (legacy *_eth keys accepted),\nmax_fee_per_gas_gwei, max_gas_limit, gas_daily_budget_native (UTC-day cumulative EVM gas in native units).\nStrictest of global and per-chain limits wins. Daily limits apply per chain family spend, not cross-chain totals.\n" }, "api_key_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Optional expiration time for the agent's API key. Set to null to clear." }, "environment": { "type": "string", "nullable": true, "description": "Named environment for this agent (production, preview, development, or custom)." }, "environment_locked": { "type": "boolean", "description": "When true, the environment tag cannot be changed after creation." }, "env_auto_resolve": { "type": "boolean", "description": "When true, env var resolve endpoints auto-fill environment from this agent's tag." }, "per_environment_guardrails": { "type": "object", "additionalProperties": true, "description": "Per-environment guardrail overrides keyed by environment slug." }, "address_screening_policy": { "type": "object", "additionalProperties": true, "description": "Recipient address screening policy. `mode` may be `off`, `deny`, or `approve`." }, "approval_id": { "type": "string", "format": "uuid", "description": "Approved policy_change id when applying a queued guardrail widening. Resubmit PATCH with this field after the approval has been approved via POST /v1/approvals/{approval_id}/decide.\n" } } }, "AgentResponse": { "type": "object", "required": [ "id", "name", "auth_method", "is_active", "intents_api_enabled", "shroud_enabled", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "auth_method": { "type": "string", "enum": [ "api_key", "mtls", "oidc_client_credentials" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "intents_api_enabled": { "type": "boolean" }, "tx_to_allowlist": { "type": "array", "items": { "type": "string" } }, "tx_max_value": { "type": "string", "description": "Maximum value per transaction in native major units for the transacting chain family (ETH on EVM, BTC on Bitcoin, SOL on Solana, XRP, ADA, TRX)." }, "tx_daily_limit": { "type": "string", "description": "Rolling daily spend cap in native major units, enforced per chain family at signing time." }, "tx_max_value_eth": { "type": "string", "deprecated": true, "description": "Deprecated alias for tx_max_value. Same unit semantics (native major units, not ETH-only)." }, "tx_daily_limit_eth": { "type": "string", "deprecated": true, "description": "Deprecated alias for tx_daily_limit." }, "tx_spent_today": { "type": "string", "description": "Sum of today's spend across all chain families in major units. Prefer tx_spent_today_by_chain." }, "tx_spent_today_eth": { "type": "string", "deprecated": true, "description": "Deprecated alias for tx_spent_today." }, "tx_allowed_chains": { "type": "array", "items": { "type": "string" } }, "token_ttl_seconds": { "type": "integer", "nullable": true }, "vault_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "client_cert_fingerprint": { "type": "string", "description": "SHA-256 fingerprint of the client certificate (mTLS agents)" }, "oidc_issuer": { "type": "string", "description": "OIDC issuer URL (oidc_client_credentials agents)" }, "oidc_client_id": { "type": "string", "description": "OIDC client ID (oidc_client_credentials agents)" }, "ssh_public_key": { "type": "string", "description": "Ed25519 SSH public key (base64-encoded, auto-generated at creation)" }, "ecdh_public_key": { "type": "string", "description": "P-256 ECDH public key (base64 SEC1 uncompressed point, auto-generated at creation)" }, "shroud_enabled": { "type": "boolean", "description": "Whether this agent routes LLM traffic through the Shroud TEE proxy" }, "shroud_config": { "$ref": "#/components/schemas/ShroudConfig" }, "execution_intents_enabled": { "type": "boolean", "description": "Whether Execution Intents (bindings and execute endpoint) are enabled for this agent" }, "execution_guardrails": { "type": "object", "additionalProperties": true, "description": "Guardrails applied to all execution intents for this agent" }, "intents_require_tee": { "type": "boolean", "description": "When true, transaction/sign requests must arrive via a TEE host (Pro+ only)" }, "execution_require_tee": { "type": "boolean", "description": "When true, execute requests must arrive via TEE and all direct secret reads are blocked (Pro+ only)" }, "tx_max_per_day": { "type": "integer", "nullable": true, "description": "Max transactions per UTC calendar day. Null = unlimited." }, "tx_overhead_budget": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" }, "description": "Per-chain daily overhead budget in native units." }, "solana_ata_allowlist": { "type": "array", "items": { "type": "string" }, "description": "Solana wallet addresses whose ATAs may be created." }, "cards_enabled": { "type": "boolean", "description": "Whether this agent may order payment cards (x402 card ordering)." }, "card_max_order_usd": { "type": "string", "description": "Maximum USD amount for a single card order." }, "card_daily_limit_usd": { "type": "string", "description": "Maximum cumulative USD spent ordering cards per rolling 24h window." }, "card_payto_allowlist": { "type": "array", "items": { "type": "string" }, "description": "Allowed x402 payTo recipients for card orders (empty = built-in Laso recipients)." }, "card_reveal_enabled": { "type": "boolean", "description": "Whether agents may reveal card details subject to per-card reveal policy." }, "card_require_approval": { "type": "boolean", "description": "When true, card orders route through the human approval queue before x402 payment." }, "tx_approval_policy": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Graduated transaction approval policy (HITL thresholds)." }, "typed_data_policy": { "type": "string", "enum": [ "deny", "approve" ], "nullable": true }, "simulation_failure_policy": { "type": "string", "enum": [ "deny", "approve" ], "nullable": true }, "tx_block_unlimited_approvals": { "type": "boolean", "description": "Block unlimited ERC-20 approvals." }, "tx_per_recipient_max_per_day": { "type": "integer", "nullable": true }, "tx_per_recipient_daily_limit": { "type": "string", "nullable": true }, "new_recipient_cap_native": { "type": "string", "nullable": true }, "tx_max_value_usd": { "type": "string", "nullable": true }, "tx_daily_limit_usd": { "type": "string", "nullable": true }, "raw_signing_policy": { "type": "string", "enum": [ "allow", "deny", "approve" ] }, "personal_sign_policy": { "type": "object", "additionalProperties": true, "nullable": true }, "allow_erc4337": { "type": "boolean" }, "allow_eip7702": { "type": "boolean" }, "auto_suspended": { "type": "boolean", "description": "True when circuit breaker auto-suspended the agent after repeated guardrail denials." }, "tx_count_today": { "type": "integer", "description": "Today's transaction count (UTC calendar day). Present when intents_api_enabled." }, "tx_overhead_today_by_chain": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Today's overhead spend by chain in native units." }, "federation_enabled": { "type": "boolean", "description": "Whether this agent may mint OIDC federation tokens via\nPOST /v1/auth/federated-token. False by default.\n" }, "federation_audiences": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Allowlist of audience URIs the agent may federate to." }, "federated_token_ttl_seconds": { "type": "integer", "nullable": true, "description": "Per-agent TTL override for federation tokens (60..=3600)." }, "signing_chains": { "type": "array", "items": { "type": "string" }, "description": "Chains for which this agent has provisioned signing keys." }, "eip712_domain_allowlist": { "type": "array", "items": { "type": "object" }, "description": "JSON array of allowed EIP-712 domain entries." }, "eip712_default_policy": { "type": "string", "enum": [ "deny", "allow" ], "description": "Default EIP-712 policy (deny blocks all unless allowlisted)." }, "message_signing_enabled": { "type": "boolean", "description": "Whether EIP-191 personal_sign is enabled." }, "raw_signing_enabled": { "type": "boolean", "description": "Whether the raw/precomputed-digest signing intent (eip712_digest) is enabled. Blind signing — bypasses transaction guardrails; OFF by default and human-set. Required for ERC-1271/ERC-7739 flows (e.g. Polymarket).\n" }, "tx_token_allowlist": { "type": "array", "items": { "type": "string" }, "description": "Token contract/mint addresses this agent may interact with." }, "tx_known_tokens_only": { "type": "boolean", "description": "When true, only tokens in the known_tokens registry may be used." }, "xrpl_allowed_tx_types": { "type": "array", "items": { "type": "string" }, "description": "Allowed XRP Ledger transaction types." }, "per_chain_guardrails": { "type": "object", "additionalProperties": true, "description": "Per-chain guardrail overrides." }, "tx_spent_today_by_chain": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Per-chain-family daily spend in native major units (keys: evm, bitcoin, solana, xrp, cardano, tron)." }, "api_key_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Optional expiration time for the agent's API key." }, "evm_address": { "type": "string", "nullable": true, "description": "Agent's Ethereum EOA address (used as Safe signer for smart accounts and Intents API)." }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "last_active_at": { "type": "string", "format": "date-time" }, "smart_accounts": { "type": "array", "description": "Multi-chain; one Safe per chain", "items": { "$ref": "#/components/schemas/AgentSmartAccountResponse" } }, "environment": { "type": "string", "nullable": true, "description": "Named environment this agent belongs to (production, preview, development, or custom)." }, "environment_locked": { "type": "boolean", "description": "When true, the environment tag is locked and cannot be changed." }, "env_auto_resolve": { "type": "boolean", "description": "When true, env var resolve endpoints auto-fill environment from this agent's tag." }, "per_environment_guardrails": { "type": "object", "additionalProperties": true, "description": "Per-environment guardrail overrides keyed by environment slug." }, "address_screening_policy": { "type": "object", "additionalProperties": true, "description": "Recipient address screening policy. `mode` may be `off`, `deny`, or `approve`." } } }, "KnownToken": { "type": "object", "required": [ "id", "chain", "symbol", "name", "contract_address", "decimals", "is_testnet", "is_verified" ], "properties": { "id": { "type": "string", "format": "uuid" }, "chain": { "type": "string" }, "symbol": { "type": "string" }, "name": { "type": "string" }, "contract_address": { "type": "string" }, "decimals": { "type": "integer" }, "is_testnet": { "type": "boolean" }, "is_verified": { "type": "boolean" }, "logo_url": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "KnownTokenListResponse": { "type": "object", "required": [ "tokens" ], "properties": { "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/KnownToken" } } } }, "CreateKnownTokenRequest": { "type": "object", "required": [ "chain", "symbol", "name", "contract_address", "decimals" ], "properties": { "chain": { "type": "string" }, "symbol": { "type": "string" }, "name": { "type": "string" }, "contract_address": { "type": "string" }, "decimals": { "type": "integer" }, "is_testnet": { "type": "boolean", "default": false }, "is_verified": { "type": "boolean", "default": true }, "logo_url": { "type": "string", "nullable": true } } }, "AgentSmartAccountResponse": { "type": "object", "description": "One Safe smart account per chain for an agent", "properties": { "id": { "type": "string", "format": "uuid" }, "chain": { "type": "string" }, "chain_id": { "type": "integer" }, "safe_address": { "type": "string" }, "nonce": { "type": "string" }, "init_data": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" } } }, "AddSmartAccountRequest": { "type": "object", "required": [ "chain", "chain_id", "safe_address" ], "properties": { "chain": { "type": "string" }, "chain_id": { "type": "integer" }, "safe_address": { "type": "string" }, "nonce": { "type": "string" }, "init_data": { "type": "object" } } }, "AgentSelfResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "org_id": { "type": "string", "format": "uuid" }, "scopes": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "intents_api_enabled": { "type": "boolean" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "last_active_at": { "type": "string", "format": "date-time" }, "ssh_public_key": { "type": "string", "description": "Ed25519 SSH public key (base64-encoded)" }, "ecdh_public_key": { "type": "string", "description": "P-256 ECDH public key (base64 SEC1 uncompressed point)" }, "shroud_enabled": { "type": "boolean", "description": "Whether this agent routes LLM traffic through the Shroud TEE proxy" }, "shroud_config": { "$ref": "#/components/schemas/ShroudConfig" } } }, "ShroudConfig": { "type": "object", "description": "Per-agent Shroud LLM Proxy configuration", "properties": { "pii_policy": { "type": "string", "enum": [ "block", "redact", "warn", "allow" ], "default": "redact", "description": "How PII detections are handled" }, "injection_threshold": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.7, "description": "Prompt injection score threshold (0.0–1.0). Requests above are blocked" }, "context_injection_threshold": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.7, "description": "Context injection score threshold (0.0–1.0)" }, "allowed_providers": { "type": "array", "items": { "type": "string" }, "description": "LLM providers this agent may use (empty = all)" }, "allowed_models": { "type": "array", "items": { "type": "string" }, "description": "Specific models allowed (empty = all)" }, "denied_models": { "type": "array", "items": { "type": "string" }, "description": "Models explicitly blocked" }, "max_tokens_per_request": { "type": "integer", "description": "Maximum input tokens per request" }, "max_requests_per_minute": { "type": "integer", "description": "Rate limit (requests per minute)" }, "max_requests_per_day": { "type": "integer", "description": "Rate limit (requests per day)" }, "daily_budget_usd": { "type": "number", "description": "Daily LLM spend cap in USD (0 = unlimited)" }, "enable_secret_redaction": { "type": "boolean", "default": true, "description": "Whether vault secrets are redacted from prompts/responses" }, "enable_response_filtering": { "type": "boolean", "default": true, "description": "Whether response credential scanning is active" }, "unicode_normalization": { "$ref": "#/components/schemas/UnicodeNormalizationConfig" }, "command_injection_detection": { "$ref": "#/components/schemas/CommandInjectionConfig" }, "social_engineering_detection": { "$ref": "#/components/schemas/SocialEngineeringConfig" }, "encoding_detection": { "$ref": "#/components/schemas/EncodingDetectionConfig" }, "network_detection": { "$ref": "#/components/schemas/NetworkDetectionConfig" }, "filesystem_detection": { "$ref": "#/components/schemas/FilesystemDetectionConfig" }, "sanitization_mode": { "type": "string", "enum": [ "block", "surgical", "log_only" ], "default": "block", "description": "Global behavior when threats are detected (block=reject, surgical=remove only malicious parts, log_only=audit without action)" }, "threat_logging": { "type": "boolean", "default": true, "description": "Whether to log all detected threats to audit (even when action is allow/warn)" }, "tool_call_inspection": { "$ref": "#/components/schemas/ToolCallPolicy" }, "output_policy": { "$ref": "#/components/schemas/OutputPolicy" }, "secret_injection_detection": { "$ref": "#/components/schemas/SecretInjectionConfig" }, "advanced_redaction": { "$ref": "#/components/schemas/AdvancedRedactionConfig" }, "semantic_policy": { "$ref": "#/components/schemas/SemanticPolicy" }, "flagged_request_retention_days": { "type": "integer", "minimum": 0, "maximum": 365, "description": "Number of days to retain flagged request bodies for replay/investigation" } } }, "UnicodeNormalizationConfig": { "type": "object", "description": "Unicode normalization and homoglyph detection settings", "properties": { "enabled": { "type": "boolean", "default": true, "description": "Enable Unicode normalization" }, "strip_zero_width": { "type": "boolean", "default": true, "description": "Remove zero-width and invisible Unicode characters" }, "normalize_homoglyphs": { "type": "boolean", "default": true, "description": "Replace look-alike characters (e.g., Cyrillic а → Latin a)" }, "normalization_form": { "type": "string", "enum": [ "NFC", "NFKC", "NFD", "NFKD" ], "default": "NFKC", "description": "Unicode normalization form to apply" } } }, "CommandInjectionConfig": { "type": "object", "description": "Shell/command injection detection settings", "properties": { "enabled": { "type": "boolean", "default": true, "description": "Enable command injection detection" }, "action": { "type": "string", "enum": [ "block", "sanitize", "warn", "log" ], "default": "block", "description": "Action when command injection is detected" }, "patterns": { "type": "string", "enum": [ "default", "strict", "custom" ], "default": "default", "description": "Pattern strictness level" }, "custom_patterns": { "type": "array", "items": { "type": "string" }, "description": "Custom regex patterns for detection (only used when patterns=custom)" } } }, "SocialEngineeringConfig": { "type": "object", "description": "Social engineering and manipulation detection settings", "properties": { "enabled": { "type": "boolean", "default": true, "description": "Enable social engineering detection" }, "action": { "type": "string", "enum": [ "block", "warn", "log" ], "default": "warn", "description": "Action when manipulation attempts are detected" }, "sensitivity": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium", "description": "Detection sensitivity level" } } }, "EncodingDetectionConfig": { "type": "object", "description": "Encoding/obfuscation detection settings", "properties": { "enabled": { "type": "boolean", "default": true, "description": "Enable encoding detection" }, "action": { "type": "string", "enum": [ "block", "decode", "warn", "log" ], "default": "warn", "description": "Action when obfuscated content is detected" }, "detect_base64": { "type": "boolean", "default": true, "description": "Detect Base64-encoded content" }, "detect_hex": { "type": "boolean", "default": true, "description": "Detect hex-encoded content (\\\\x41, 0x41)" }, "detect_unicode_escape": { "type": "boolean", "default": true, "description": "Detect Unicode escape sequences (\\\\u0041)" } } }, "NetworkDetectionConfig": { "type": "object", "description": "Suspicious URL/domain detection settings", "properties": { "enabled": { "type": "boolean", "default": true, "description": "Enable network/URL detection" }, "action": { "type": "string", "enum": [ "block", "warn", "log" ], "default": "warn", "description": "Action when suspicious URLs are detected" }, "blocked_domains": { "type": "array", "items": { "type": "string" }, "description": "Domains to always block (e.g., pastebin.com, ngrok.io)" }, "allowed_domains": { "type": "array", "items": { "type": "string" }, "description": "Domains to always allow (allowlist mode when non-empty)" } } }, "FilesystemDetectionConfig": { "type": "object", "description": "Filesystem path detection settings", "properties": { "enabled": { "type": "boolean", "default": false, "description": "Enable filesystem path detection (disabled by default as it can be noisy)" }, "action": { "type": "string", "enum": [ "block", "sanitize", "warn", "log" ], "default": "log", "description": "Action when filesystem paths are detected" }, "blocked_paths": { "type": "array", "items": { "type": "string" }, "description": "Path patterns to block (e.g., /etc/passwd, ~/.ssh)" } } }, "ToolCallPolicy": { "type": "object", "description": "Tool/function call inspection settings", "properties": { "enabled": { "type": "boolean", "default": false, "description": "Enable tool call inspection" }, "allowed_tool_names": { "type": "array", "items": { "type": "string" }, "description": "Allowed tool/function names (empty = all allowed)" }, "denied_tool_names": { "type": "array", "items": { "type": "string" }, "description": "Denied tool/function names" }, "scan_arguments": { "type": "boolean", "default": true, "description": "Scan tool call arguments for credential exfiltration" }, "block_credential_exfil": { "type": "boolean", "default": true, "description": "Block tool calls that appear to exfiltrate credentials" }, "action": { "type": "string", "enum": [ "block", "sanitize", "warn", "log" ], "default": "block", "description": "Action when a tool call violation is detected" } } }, "OutputPolicy": { "type": "object", "description": "Output content policy settings for LLM responses", "properties": { "enabled": { "type": "boolean", "default": false, "description": "Enable output content policies" }, "blocked_patterns": { "type": "array", "items": { "type": "string" }, "description": "Custom regex patterns to block in responses" }, "blocked_entities": { "type": "array", "items": { "type": "string" }, "description": "Named entities to block (e.g., competitor names)" }, "block_harmful_content": { "type": "boolean", "default": false, "description": "Block responses containing harmful content categories" }, "harmful_categories": { "type": "array", "items": { "type": "string", "enum": [ "violence", "self_harm", "illegal", "hate", "sexual", "malware" ] }, "description": "Harm categories to block" }, "action": { "type": "string", "enum": [ "block", "sanitize", "warn", "log" ], "default": "warn", "description": "Action when output policy is violated" } } }, "SecretInjectionConfig": { "type": "object", "description": "Detects credentials injected into prompts that are not from the vault", "properties": { "enabled": { "type": "boolean", "default": false, "description": "Enable secret injection detection" }, "action": { "type": "string", "enum": [ "block", "sanitize", "warn", "log" ], "default": "block", "description": "Action when injected credentials are detected" }, "sensitivity": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium", "description": "Detection sensitivity level" } } }, "AdvancedRedactionConfig": { "type": "object", "description": "Advanced secret redaction settings (base64-encoded, split, prefix leaks)", "properties": { "enabled": { "type": "boolean", "default": false, "description": "Enable advanced redaction checks" }, "detect_base64_encoded": { "type": "boolean", "default": false, "description": "Detect base64-encoded vault secrets" }, "detect_split_secrets": { "type": "boolean", "default": false, "description": "Detect secrets split across tokens or messages" }, "detect_prefix_leak": { "type": "boolean", "default": false, "description": "Detect partial/prefix leaks of vault secrets" }, "min_secret_length": { "type": "integer", "default": 16, "description": "Minimum secret length to consider for advanced matching" } } }, "SemanticPolicy": { "type": "object", "description": "Semantic/intent-level policy enforcement", "properties": { "enabled": { "type": "boolean", "default": false, "description": "Enable semantic policy enforcement" }, "allowed_topics": { "type": "array", "items": { "type": "string" }, "description": "Topics the agent is allowed to discuss (empty = all)" }, "denied_topics": { "type": "array", "items": { "type": "string" }, "description": "Topics to block" }, "allowed_tasks": { "type": "array", "items": { "type": "string" }, "description": "Tasks the agent is allowed to perform (empty = all)" }, "denied_tasks": { "type": "array", "items": { "type": "string" }, "description": "Tasks to block (e.g., code_generation, data_export)" }, "action": { "type": "string", "enum": [ "block", "sanitize", "warn", "log" ], "default": "warn", "description": "Action when semantic policy is violated" } } }, "AgentCreatedResponse": { "type": "object", "required": [ "agent" ], "properties": { "agent": { "$ref": "#/components/schemas/AgentResponse" }, "api_key": { "type": "string", "description": "One-time API key (only present for api_key auth method)" } } }, "AgentListResponse": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/AgentResponse" } } } }, "AgentKeyRotatedResponse": { "type": "object", "properties": { "api_key": { "type": "string" } } }, "SubmitTransactionRequest": { "type": "object", "required": [ "to", "value", "chain" ], "properties": { "to": { "type": "string", "description": "Destination address (0x-prefixed)" }, "value": { "type": "string", "description": "Value in ETH" }, "chain": { "type": "string", "description": "Chain name or numeric ID" }, "data": { "type": "string", "description": "Hex-encoded calldata" }, "signing_key_path": { "type": "string", "description": "Vault path to signing key. Auto-resolves per-chain signing key if provisioned, otherwise keys/{chain}-signer." }, "nonce": { "type": "integer" }, "gas_price": { "type": "string" }, "gas_limit": { "type": "integer" }, "max_fee_per_gas": { "type": "string" }, "max_priority_fee_per_gas": { "type": "string" }, "simulate_first": { "type": "boolean", "default": false }, "mode": { "type": "string", "description": "Transaction mode", "enum": [ "eoa", "smart_account" ], "default": "eoa" }, "gasless": { "type": "boolean", "description": "Whether to submit as a gasless (sponsored) transaction", "default": false }, "destination_tag": { "type": "integer", "description": "Non-EVM (XRP): destination tag for exchange deposits" }, "memo": { "type": "string", "description": "Non-EVM (XRP, Solana): optional memo" }, "fee_rate_sat_per_vbyte": { "type": "integer", "description": "Non-EVM (Bitcoin): override the fetched fee rate (sat/vByte)" }, "fee_limit_sun": { "type": "integer", "description": "Non-EVM (Tron): TRC-20 energy fee limit in sun" }, "token_mint": { "type": "string", "description": "Non-EVM (Solana SPL / Tron TRC-20): token mint or contract address; omit for native transfer" }, "token_decimals": { "type": "integer", "description": "Non-EVM (Solana, Tron): token decimals (default 6)" }, "ttl": { "type": "integer", "description": "Non-EVM (Cardano): transaction time-to-live (absolute slot)" }, "xrpl_tx_json": { "type": "object", "additionalProperties": true, "description": "Raw XRPL transaction JSON for full transaction type coverage. When present (and chain is XRP), the handler uses the xrpl-rust binary codec to encode and sign the transaction as-is. Supports all XRPL transaction types: Payment, TrustSet, OfferCreate, OfferCancel, AccountSet, EscrowCreate, NFTokenMint, AMMCreate, and 20+ more. Account, Sequence, Fee, LastLedgerSequence, and SigningPubKey are auto-filled when absent.\n" }, "approval_id": { "type": "string", "format": "uuid", "description": "Optional pending approval ID. When consensus policies match, clients resubmit with this field set to bypass the 202 gate after the approval has been executed.\n" }, "raw_transaction": { "type": "string", "description": "Pre-built raw transaction as a base64-encoded byte string. When provided, the handler decodes and deep-inspects the transaction for policy evaluation before signing. Supported for non-EVM chains where the client constructs the transaction payload.\n" }, "tron_transaction": { "type": "object", "additionalProperties": true, "description": "Pre-built Tron transaction JSON object. When provided, the handler signs the transaction as-is using the Tron protobuf format. Enables full Tron transaction type coverage beyond simple TRX/TRC-20 transfers.\n" } } }, "SignTransactionRequest": { "type": "object", "required": [ "to", "value", "chain" ], "properties": { "to": { "type": "string", "description": "Destination address (0x-prefixed)" }, "value": { "type": "string", "description": "Value in ETH" }, "chain": { "type": "string", "description": "Chain name or numeric ID" }, "data": { "type": "string", "description": "Hex-encoded calldata" }, "signing_key_path": { "type": "string", "description": "Vault path to signing key. Auto-resolves per-chain signing key if provisioned, otherwise keys/{chain}-signer." }, "nonce": { "type": "integer" }, "gas_price": { "type": "string" }, "gas_limit": { "type": "integer" }, "max_fee_per_gas": { "type": "string" }, "max_priority_fee_per_gas": { "type": "string" }, "simulate_first": { "type": "boolean", "default": false }, "destination_tag": { "type": "integer", "description": "Non-EVM (XRP): destination tag for exchange deposits" }, "memo": { "type": "string", "description": "Non-EVM (XRP, Solana): optional memo" }, "fee_rate_sat_per_vbyte": { "type": "integer", "description": "Non-EVM (Bitcoin): override the fetched fee rate (sat/vByte)" }, "fee_limit_sun": { "type": "integer", "description": "Non-EVM (Tron): TRC-20 energy fee limit in sun" }, "token_mint": { "type": "string", "description": "Non-EVM (Solana SPL / Tron TRC-20): token mint or contract address; omit for native transfer" }, "token_decimals": { "type": "integer", "description": "Non-EVM (Solana, Tron): token decimals (default 6)" }, "ttl": { "type": "integer", "description": "Non-EVM (Cardano): transaction time-to-live (absolute slot)" }, "xrpl_tx_json": { "type": "object", "additionalProperties": true, "description": "Raw XRPL transaction JSON for full transaction type coverage. When present (and chain is XRP), the handler uses the xrpl-rust binary codec to encode and sign the transaction as-is. Supports all XRPL transaction types: Payment, TrustSet, OfferCreate, OfferCancel, AccountSet, EscrowCreate, NFTokenMint, AMMCreate, and 20+ more. Account, Sequence, Fee, LastLedgerSequence, and SigningPubKey are auto-filled when absent.\n" } } }, "SignTransactionResponse": { "type": "object", "properties": { "signed_tx": { "type": "string", "description": "Raw signed transaction hex (always included)" }, "tx_hash": { "type": "string" }, "from": { "type": "string", "description": "Derived sender address" }, "to": { "type": "string" }, "chain": { "type": "string" }, "chain_id": { "type": "integer" }, "nonce": { "type": "integer" }, "value_wei": { "type": "string" }, "status": { "type": "string", "enum": [ "sign_only" ] }, "simulation_id": { "type": "string" }, "simulation_status": { "type": "string" }, "max_fee_per_gas": { "type": "string" }, "max_priority_fee_per_gas": { "type": "string" } } }, "SimulateTransactionRequest": { "type": "object", "required": [ "to", "value", "chain" ], "properties": { "to": { "type": "string" }, "value": { "type": "string" }, "chain": { "type": "string" }, "data": { "type": "string" }, "signing_key_path": { "type": "string", "description": "Vault path to signing key. Auto-resolves per-chain signing key if provisioned, otherwise keys/{chain}-signer." }, "gas_limit": { "type": "integer" } } }, "SimulateBundleRequest": { "type": "object", "required": [ "transactions" ], "properties": { "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/SimulateTransactionRequest" } } } }, "CreateSigningKeyRequest": { "type": "object", "required": [ "chain" ], "properties": { "chain": { "type": "string", "enum": [ "ethereum", "bitcoin", "solana", "xrp", "cardano", "tron" ] } } }, "SigningKeyResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "chain": { "type": "string" }, "curve": { "type": "string" }, "public_key": { "type": "string" }, "address": { "type": "string", "nullable": true }, "key_version": { "type": "integer" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "rotated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "SigningKeyListResponse": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/SigningKeyResponse" } } } }, "LeaseBankrKeyRequest": { "type": "object", "properties": { "wallet_id": { "type": "string", "description": "Bankr wallet ID (wlt_...). Uses org default if omitted." }, "ttl_seconds": { "type": "integer", "description": "Lease TTL in seconds (default 3600, max 86400).", "minimum": 60, "maximum": 86400 }, "permissions": { "$ref": "#/components/schemas/LeaseBankrPermissions" } } }, "LeaseBankrPermissions": { "type": "object", "properties": { "llm_gateway_enabled": { "type": "boolean", "default": true }, "agent_api_enabled": { "type": "boolean", "default": false }, "read_only": { "type": "boolean", "default": true } } }, "LeaseBankrKeyResponse": { "type": "object", "properties": { "lease_id": { "type": "string", "format": "uuid" }, "api_key": { "type": "string", "description": "Ephemeral bk_usr_ key. Present for human callers only; omitted for agent JWTs." }, "wallet_id": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } }, "BankrKeyLeaseResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "wallet_id": { "type": "string" }, "bankr_key_id": { "type": "string" }, "permissions": { "type": "object" }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "BankrKeyLeaseListResponse": { "type": "object", "properties": { "leases": { "type": "array", "items": { "$ref": "#/components/schemas/BankrKeyLeaseResponse" } } } }, "CreateDelegationRequest": { "type": "object", "required": [ "delegate_id" ], "properties": { "delegate_id": { "type": "string", "format": "uuid", "description": "The agent ID to delegate to." }, "allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "Tool names the delegate may use. Empty means all tools allowed." }, "blocked_tools": { "type": "array", "items": { "type": "string" }, "description": "Tool names the delegate may NOT use." }, "max_daily_delegations": { "type": "integer", "description": "Maximum delegation calls per UTC day. NULL means unlimited." }, "max_depth": { "type": "integer", "description": "Maximum delegation chain depth (default 3).", "default": 3 }, "guardrails": { "type": "object", "description": "Additional guardrail constraints for this delegation." }, "delegation_mode": { "type": "string", "enum": [ "caller", "target", "both" ], "description": "Execution mode: caller (use delegator's creds), target (use delegate's config), or both.", "default": "caller" }, "expires_at": { "type": "string", "format": "date-time", "description": "Optional expiration timestamp." } } }, "UpdateDelegationRequest": { "type": "object", "properties": { "allowed_tools": { "type": "array", "items": { "type": "string" } }, "blocked_tools": { "type": "array", "items": { "type": "string" } }, "max_daily_delegations": { "type": "integer" }, "max_depth": { "type": "integer" }, "guardrails": { "type": "object" }, "delegation_mode": { "type": "string", "enum": [ "caller", "target", "both" ] }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } } }, "DelegationResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "delegator_id": { "type": "string", "format": "uuid" }, "delegate_id": { "type": "string", "format": "uuid" }, "delegator_name": { "type": "string" }, "delegate_name": { "type": "string" }, "allowed_tools": { "type": "array", "items": { "type": "string" } }, "blocked_tools": { "type": "array", "items": { "type": "string" } }, "max_daily_delegations": { "type": "integer", "nullable": true }, "max_depth": { "type": "integer" }, "guardrails": { "type": "object" }, "delegation_mode": { "type": "string", "enum": [ "caller", "target", "both" ] }, "is_active": { "type": "boolean" }, "created_by": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "delegations_today": { "type": "integer", "description": "Number of delegations used today (present in effective endpoint)." } } }, "DelegationListResponse": { "type": "object", "properties": { "delegations": { "type": "array", "items": { "$ref": "#/components/schemas/DelegationResponse" } } } }, "SignIntentRequest": { "type": "object", "required": [ "intent_type", "chain" ], "properties": { "intent_type": { "type": "string", "enum": [ "personal_sign", "typed_data", "eip712_digest", "transaction" ] }, "chain": { "type": "string" }, "signing_key_path": { "type": "string", "description": "Vault path to signing key. Auto-resolves per-chain signing key if provisioned, otherwise keys/{chain}-signer." }, "message": { "type": "string", "description": "Hex-encoded message bytes (for personal_sign)" }, "typed_data": { "type": "object", "description": "EIP-712 typed data JSON (for typed_data)" }, "hash": { "type": "string", "description": "Client-computed 32-byte digest (0x-prefixed) for the eip712_digest intent. Signed directly (blind signing); requires the agent's raw_signing_enabled flag. Use for ERC-1271/ERC-7739 nested EIP-712 flows (e.g. Polymarket) where the canonical hash is computed client-side.\n" }, "tx_type": { "type": "integer", "description": "EIP-2718 type: 0=legacy, 1=2930, 2=1559, 3=4844, 4=7702" }, "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" }, "nonce": { "type": "integer" }, "gas_limit": { "type": "integer" }, "gas_price": { "type": "string" }, "max_fee_per_gas": { "type": "string" }, "max_priority_fee_per_gas": { "type": "string" }, "access_list": { "type": "array", "items": { "type": "object" } }, "max_fee_per_blob_gas": { "type": "string" }, "blob_versioned_hashes": { "type": "array", "items": { "type": "string" } }, "authorization_list": { "type": "array", "items": { "type": "object" } }, "sign_only": { "type": "boolean", "description": "When true, sign only (do not broadcast). Non-EVM transaction intents only." }, "destination_tag": { "type": "integer", "description": "Non-EVM (XRP): destination tag for exchange deposits" }, "memo": { "type": "string", "description": "Non-EVM (XRP, Solana): optional memo" }, "fee_rate_sat_per_vbyte": { "type": "integer", "description": "Non-EVM (Bitcoin): override the fetched fee rate (sat/vByte)" }, "fee_limit_sun": { "type": "integer", "description": "Non-EVM (Tron): TRC-20 energy fee limit in sun" }, "token_mint": { "type": "string", "description": "Non-EVM (Solana SPL / Tron TRC-20): token mint or contract address; omit for native transfer" }, "token_decimals": { "type": "integer", "description": "Non-EVM (Solana, Tron): token decimals (default 6)" }, "ttl": { "type": "integer", "description": "Non-EVM (Cardano): transaction time-to-live (absolute slot)" }, "xrpl_tx_json": { "type": "object", "additionalProperties": true, "description": "Raw XRPL transaction JSON for full transaction type coverage. When present (and chain is XRP), the handler uses the xrpl-rust binary codec to encode and sign the transaction as-is. Supports all XRPL transaction types: Payment, TrustSet, OfferCreate, OfferCancel, AccountSet, EscrowCreate, NFTokenMint, AMMCreate, and 20+ more. Account, Sequence, Fee, LastLedgerSequence, and SigningPubKey are auto-filled when absent.\n" }, "approval_id": { "type": "string", "format": "uuid", "description": "Optional pending approval ID. When consensus policies match, clients resubmit with this field set to bypass the 202 gate after the approval has been executed.\n" }, "raw_transaction": { "type": "string", "description": "Pre-built raw transaction as a base64-encoded byte string. When provided, the handler decodes and deep-inspects the transaction for policy evaluation before signing. Supported for non-EVM chains where the client constructs the transaction payload.\n" }, "tron_transaction": { "type": "object", "additionalProperties": true, "description": "Pre-built Tron transaction JSON object. When provided, the handler signs the transaction as-is using the Tron protobuf format. Enables full Tron transaction type coverage beyond simple TRX/TRC-20 transfers.\n" } } }, "SignIntentResponse": { "type": "object", "properties": { "intent_type": { "type": "string" }, "chain": { "type": "string" }, "from": { "type": "string" }, "signature": { "type": "string", "nullable": true }, "signed_tx": { "type": "string", "nullable": true }, "tx_hash": { "type": "string", "nullable": true }, "message_hash": { "type": "string", "nullable": true }, "typed_data_hash": { "type": "string", "nullable": true }, "tx_type": { "type": "integer", "nullable": true } } }, "TransactionResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "chain": { "type": "string" }, "chain_id": { "type": "integer" }, "to": { "type": "string" }, "value_wei": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "signed", "sign_only", "broadcast", "failed", "simulation_failed" ] }, "signed_tx": { "type": "string", "nullable": true, "description": "Raw signed transaction hex. On GET list and GET by id, this property is omitted by default (absent from the response). Pass `include_signed_tx=true` on those endpoints to include it. Always present on the initial POST submit response.\n" }, "tx_hash": { "type": "string" }, "error_message": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "signed_at": { "type": "string", "format": "date-time" }, "simulation_id": { "type": "string" }, "simulation_status": { "type": "string" }, "tenderly_dashboard_url": { "type": "string", "format": "uri" }, "max_fee_per_gas": { "type": "string" }, "max_priority_fee_per_gas": { "type": "string" } } }, "TransactionListResponse": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionResponse" } } } }, "BalanceChange": { "type": "object", "properties": { "address": { "type": "string" }, "token": { "type": "string" }, "token_symbol": { "type": "string" }, "before": { "type": "string" }, "after": { "type": "string" }, "change": { "type": "string" } } }, "SimulationResponse": { "type": "object", "properties": { "simulation_id": { "type": "string" }, "status": { "type": "string", "enum": [ "success", "reverted", "error" ] }, "gas_used": { "type": "integer" }, "gas_estimate_usd": { "type": "string" }, "balance_changes": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceChange" } }, "error": { "type": "string" }, "error_code": { "type": "string" }, "error_human_readable": { "type": "string" }, "revert_reason": { "type": "string" }, "tenderly_dashboard_url": { "type": "string", "format": "uri" }, "simulated_at": { "type": "string", "format": "date-time" } } }, "BundleSimulationResponse": { "type": "object", "properties": { "simulations": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationResponse" } } } }, "ChainResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "display_name": { "type": "string" }, "chain_id": { "type": "integer" }, "rpc_url": { "type": "string" }, "ws_url": { "type": "string" }, "explorer_url": { "type": "string" }, "native_currency": { "type": "string" }, "is_testnet": { "type": "boolean" }, "is_enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ChainListResponse": { "type": "object", "properties": { "chains": { "type": "array", "items": { "$ref": "#/components/schemas/ChainResponse" } } } }, "CreateChainRequest": { "type": "object", "required": [ "name", "display_name", "chain_id" ], "properties": { "name": { "type": "string" }, "display_name": { "type": "string" }, "chain_id": { "type": "integer" }, "rpc_url": { "type": "string" }, "ws_url": { "type": "string" }, "explorer_url": { "type": "string" }, "native_currency": { "type": "string", "default": "ETH" }, "is_testnet": { "type": "boolean", "default": false }, "is_enabled": { "type": "boolean", "default": true } } }, "UpdateChainRequest": { "type": "object", "properties": { "display_name": { "type": "string" }, "rpc_url": { "type": "string" }, "ws_url": { "type": "string" }, "explorer_url": { "type": "string" }, "native_currency": { "type": "string" }, "is_testnet": { "type": "boolean" }, "is_enabled": { "type": "boolean" } } }, "CreateShareRequest": { "type": "object", "required": [ "recipient_type", "expires_at" ], "properties": { "recipient_type": { "type": "string", "enum": [ "user", "agent", "external_email", "anyone_with_link", "creator" ] }, "recipient_id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "permissions": { "type": "array", "items": { "type": "string" } }, "max_access_count": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" }, "passphrase": { "type": "string" }, "ip_allowlist": { "type": "array", "items": { "type": "string" } } } }, "ShareResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "share_url": { "type": "string", "format": "uri" }, "recipient_type": { "type": "string" }, "recipient_email": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "max_access_count": { "type": "integer" } } }, "SharedSecretResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "path": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "access_count": { "type": "integer" }, "max_access_count": { "type": "integer" } } }, "ShareListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "secret_path": { "type": "string" }, "recipient_type": { "type": "string" }, "recipient_email": { "type": "string" }, "access_count": { "type": "integer" }, "max_access_count": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "is_expired": { "type": "boolean" }, "is_accepted": { "type": "boolean" } } }, "ShareListResponse": { "type": "object", "properties": { "shares": { "type": "array", "items": { "$ref": "#/components/schemas/ShareListItem" } } } }, "OrgMemberResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "display_name": { "type": "string" }, "role": { "type": "string" }, "auth_method": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "OrgMemberListResponse": { "type": "object", "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/OrgMemberResponse" } } } }, "UpdateMemberRoleRequest": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "owner", "admin", "member" ] } } }, "InviteMemberRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string" } } }, "InviteMemberResponse": { "type": "object", "properties": { "message": { "type": "string" }, "email": { "type": "string" } } }, "AgentKeysVaultResponse": { "type": "object", "properties": { "vault_id": { "type": "string", "format": "uuid" } } }, "OrgBankrConfigResponse": { "type": "object", "properties": { "configured": { "type": "boolean" }, "partner_key_prefix": { "type": "string" }, "default_wallet_id": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "using_platform_fallback": { "type": "boolean" } } }, "UpsertOrgBankrConfigRequest": { "type": "object", "required": [ "partner_key" ], "properties": { "partner_key": { "type": "string", "description": "Bankr partner API key (bk_ptr_...)" }, "default_wallet_id": { "type": "string", "description": "Default provisioned wallet (wlt_...)" } } }, "UsageSummaryResponse": { "type": "object", "properties": { "billing_tier": { "type": "string" }, "free_tier_limit": { "type": "integer" }, "current_month": { "type": "object", "properties": { "total_requests": { "type": "integer" }, "paid_requests": { "type": "integer" }, "free_requests": { "type": "integer" }, "total_cost_usd": { "type": "string" } } } } }, "UsageHistoryResponse": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "principal_type": { "type": "string" }, "principal_id": { "type": "string" }, "method": { "type": "string" }, "endpoint": { "type": "string" }, "status_code": { "type": "integer" }, "price_usd": { "type": "string" }, "is_paid": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "SubscribeRequest": { "type": "object", "required": [ "tier", "interval" ], "properties": { "tier": { "type": "string", "enum": [ "pro", "business" ] }, "interval": { "type": "string", "enum": [ "monthly", "yearly" ] }, "trial": { "type": "boolean", "default": true } } }, "TopupRequest": { "type": "object", "required": [ "amount_usd" ], "properties": { "amount_usd": { "type": "integer", "minimum": 5, "maximum": 1000 } } }, "OverageMethodRequest": { "type": "object", "required": [ "method" ], "properties": { "method": { "type": "string", "enum": [ "credits", "x402" ] } } }, "CheckoutUrlResponse": { "type": "object", "properties": { "checkout_url": { "type": "string", "format": "uri" } } }, "PortalUrlResponse": { "type": "object", "properties": { "portal_url": { "type": "string", "format": "uri" } } }, "SubscriptionResponse": { "type": "object", "properties": { "tier": { "type": "string" }, "interval": { "type": "string" }, "period_end": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "credit_balance_cents": { "type": "integer" }, "credit_balance_usd": { "type": "string" }, "overage_method": { "type": "string" }, "usage": { "type": "object", "properties": { "requests": { "$ref": "#/components/schemas/UsageMeter" }, "secrets": { "$ref": "#/components/schemas/UsageMeter" }, "agents": { "$ref": "#/components/schemas/UsageMeter" }, "vaults": { "$ref": "#/components/schemas/UsageMeter" }, "team_members": { "$ref": "#/components/schemas/UsageMeter" }, "intent_transactions": { "$ref": "#/components/schemas/UsageMeter" }, "wallets": { "$ref": "#/components/schemas/UsageMeter" }, "shares": { "$ref": "#/components/schemas/UsageMeter" } } } } }, "UsageMeter": { "type": "object", "properties": { "used": { "type": "integer" }, "limit": { "type": "integer" } } }, "LlmMeteredInvoiceLine": { "type": "object", "description": "Metered line from Stripe upcoming invoice (usage detail when available).", "properties": { "description": { "type": "string", "nullable": true }, "amount_cents": { "type": "integer", "format": "int64" }, "quantity": { "type": "number", "nullable": true, "description": "Billed usage units when Stripe returns quantity (e.g. tokens)." }, "price_nickname": { "type": "string", "nullable": true } } }, "LlmBillingCycleUsage": { "type": "object", "description": "Accrued LLM charges for the current Stripe subscription period (upcoming invoice).", "properties": { "period_start": { "type": "string", "format": "date-time", "nullable": true }, "period_end": { "type": "string", "format": "date-time", "nullable": true }, "accrued_usage_cents": { "type": "integer", "format": "int64" }, "currency": { "type": "string" }, "metered_lines": { "type": "array", "items": { "$ref": "#/components/schemas/LlmMeteredInvoiceLine" } } } }, "LlmCreditBalance": { "type": "object", "properties": { "available_cents": { "type": "integer", "format": "int64" }, "ledger_cents": { "type": "integer", "format": "int64" }, "used_cents": { "type": "integer", "format": "int64" }, "currency": { "type": "string" } } }, "LlmTokenBillingStatus": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "subscription_status": { "type": "string", "enum": [ "active", "inactive" ] }, "credit_balance": { "$ref": "#/components/schemas/LlmCreditBalance" }, "billing_cycle_usage": { "$ref": "#/components/schemas/LlmBillingCycleUsage" }, "active_subscription_count": { "type": "integer" }, "subscription_ids": { "type": "array", "items": { "type": "string" } }, "warning": { "type": "string" } } }, "LlmCheckoutResponse": { "type": "object", "properties": { "checkout_url": { "type": "string", "format": "uri" }, "already_subscribed": { "type": "boolean" }, "subscription_id": { "type": "string" } } }, "LlmCancelDuplicatesResponse": { "type": "object", "required": [ "cancelled_count", "cancelled_subscription_ids", "remaining_subscription_ids" ], "properties": { "cancelled_count": { "type": "integer" }, "cancelled_subscription_ids": { "type": "array", "items": { "type": "string" } }, "remaining_subscription_ids": { "type": "array", "items": { "type": "string" } } } }, "LlmDisableResponse": { "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "CreditBalanceResponse": { "type": "object", "properties": { "balance_cents": { "type": "integer" }, "balance_usd": { "type": "string" }, "expiring_within_90_days": { "type": "object", "properties": { "amount_cents": { "type": "integer" }, "earliest_expiry": { "type": "string", "format": "date-time" } } } } }, "CreditTransactionsListResponse": { "type": "object", "properties": { "transactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "amount_cents": { "type": "integer" }, "balance_after_cents": { "type": "integer" }, "description": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "page": { "type": "integer" }, "limit": { "type": "integer" } } }, "OverageMethodResponse": { "type": "object", "properties": { "overage_method": { "type": "string" } } }, "AuditEventsResponse": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } }, "count": { "type": "integer" } } }, "AuditVerifyResponse": { "type": "object", "required": [ "chain_valid", "events_verified", "events_checked", "scheme" ], "properties": { "chain_valid": { "type": "boolean", "description": "Whether the integrity hash chain is unbroken" }, "events_verified": { "type": "integer", "format": "int64", "description": "Number of events with valid integrity hashes" }, "events_checked": { "type": "integer", "description": "Total events examined" }, "broken_at_event_id": { "type": "string", "format": "uuid", "nullable": true, "description": "First event where chain integrity broke (null if valid)" }, "scheme": { "type": "object", "properties": { "algorithm": { "type": "string", "example": "HMAC-SHA256" }, "chain_structure": { "type": "string" }, "hash_field": { "type": "string" }, "link_field": { "type": "string" }, "documentation": { "type": "string", "format": "uri" } } } } }, "ShroudAttestationResponse": { "type": "object", "required": [ "attested", "attestation_level", "image_hash", "identity_token", "verification" ], "properties": { "attested": { "type": "boolean", "description": "Whether at least an identity token was obtained (true for identity,\nconfidential, or sev_snp levels). Backward-compatible boolean; prefer\nattestation_level for granularity.\n" }, "attestation_level": { "type": "string", "enum": [ "none", "identity", "confidential", "sev_snp" ], "description": "Granularity of TEE attestation achieved. `none` = dev/non-GCE;\n`identity` = GCE metadata JWT only; `confidential` = CC claims present;\n`sev_snp` = full SEV-SNP measurement verified against image digest.\n" }, "image_hash": { "type": "string", "description": "Confidential VM image hash (compare against published Docker digest)" }, "identity_token": { "type": "string", "description": "GCE metadata identity JWT (verify against Google public keys)" }, "confidential_claims": { "nullable": true, "description": "Confidential Computing claims extracted from the identity JWT", "$ref": "#/components/schemas/ConfidentialClaims" }, "verification": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "string" } }, "google_certs_url": { "type": "string", "format": "uri" }, "expected_audience": { "type": "string" } } } } }, "ConfidentialClaims": { "type": "object", "nullable": true, "properties": { "secboot": { "type": "boolean", "description": "Whether secure boot was enabled" }, "hwmodel": { "type": "string", "description": "Hardware model string (e.g. GCP_AMD_SEV)" }, "instance_confidentiality": { "type": "string", "description": "Instance confidentiality level from google.compute_engine" }, "sw_name": { "type": "string", "description": "Software name claim (swname or sw_name)" } } }, "AuditEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "action": { "type": "string" }, "actor_id": { "type": "string" }, "actor_type": { "type": "string" }, "resource_type": { "type": "string" }, "resource_id": { "type": "string" }, "org_id": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true }, "ip_address": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "CreateIpRuleRequest": { "type": "object", "required": [ "rule_type", "cidr" ], "properties": { "rule_type": { "type": "string", "enum": [ "allow", "deny" ] }, "cidr": { "type": "string" }, "label": { "type": "string" }, "applies_to": { "type": "string" } } }, "IpRuleResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "rule_type": { "type": "string" }, "cidr": { "type": "string" }, "label": { "type": "string" }, "applies_to": { "type": "string" }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "IpRulesListResponse": { "type": "object", "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/IpRuleResponse" } } } }, "SettingResponse": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" }, "updated_by": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SettingsListResponse": { "type": "object", "properties": { "settings": { "type": "array", "items": { "$ref": "#/components/schemas/SettingResponse" } } } }, "UpdateSettingRequest": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string" } } }, "X402ConfigResponse": { "type": "object", "properties": { "pay_to": { "type": "string" }, "network": { "type": "string" }, "scheme": { "type": "string" }, "free_tier_limit": { "type": "integer" }, "facilitator_url": { "type": "string" } } }, "AdminUsersListResponse": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "display_name": { "type": "string" }, "role": { "type": "string" }, "auth_method": { "type": "string" }, "org_id": { "type": "string", "format": "uuid" }, "org_name": { "type": "string" }, "billing_tier": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "free_tier_override": { "type": "integer" }, "is_sponsored": { "type": "boolean" }, "current_month_requests": { "type": "integer" } } } }, "total": { "type": "integer" } } }, "UpdateOrgLimitsRequest": { "type": "object", "properties": { "free_tier_override": { "type": "integer" }, "is_sponsored": { "type": "boolean" } } }, "OrgLimitsResponse": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid" }, "free_tier_override": { "type": "integer" }, "is_sponsored": { "type": "boolean" } } }, "SetBillingTierRequest": { "type": "object", "required": [ "tier" ], "properties": { "tier": { "type": "string", "enum": [ "free", "pro", "business", "enterprise" ] }, "duration_days": { "type": "integer", "description": "How many days the tier lasts (default 365). Use 90 for a 3-month trial.", "minimum": 1, "maximum": 3650 } } }, "CreateTreasuryRequest": { "type": "object", "required": [ "name", "safe_address" ], "properties": { "name": { "type": "string", "description": "Display name (1–128 characters)" }, "safe_address": { "type": "string", "description": "Deployed Safe contract address (0x-prefixed, 42 characters)" }, "chain": { "type": "string", "description": "Chain name (default base)" }, "chain_id": { "type": "integer", "description": "EVM chain ID (default 8453 for Base)" }, "threshold": { "type": "integer", "minimum": 1, "description": "Safe threshold (default 1)" }, "signers": { "type": "array", "items": { "$ref": "#/components/schemas/CreateTreasurySignerEntry" } } } }, "CreateTreasurySignerEntry": { "type": "object", "required": [ "signer_type", "signer_id", "signer_address" ], "properties": { "signer_type": { "type": "string", "enum": [ "user", "agent" ] }, "signer_id": { "type": "string", "format": "uuid" }, "signer_address": { "type": "string", "description": "EVM address (0x-prefixed)" } } }, "UpdateTreasuryRequest": { "type": "object", "properties": { "name": { "type": "string" }, "threshold": { "type": "integer", "minimum": 1 } } }, "TreasuryResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "safe_address": { "type": "string" }, "chain": { "type": "string" }, "chain_id": { "type": "integer" }, "threshold": { "type": "integer" }, "created_by": { "type": "string", "format": "uuid" }, "signers": { "type": "array", "items": { "$ref": "#/components/schemas/TreasurySignerResponse" } }, "created_at": { "type": "string", "format": "date-time" } } }, "TreasurySignerResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "signer_type": { "type": "string", "enum": [ "user", "agent" ] }, "signer_id": { "type": "string", "format": "uuid" }, "signer_address": { "type": "string" }, "added_at": { "type": "string", "format": "date-time" } } }, "AddSignerRequest": { "type": "object", "required": [ "signer_type", "signer_id", "signer_address" ], "properties": { "signer_type": { "type": "string", "enum": [ "user", "agent" ] }, "signer_id": { "type": "string", "format": "uuid" }, "signer_address": { "type": "string" } } }, "AccessRequestResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "treasury_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "approved", "denied" ] }, "reason": { "type": "string" }, "requested_at": { "type": "string", "format": "date-time" }, "resolved_by": { "type": "string", "format": "uuid" }, "resolved_at": { "type": "string", "format": "date-time" } } }, "CreateTreasuryProposalRequest": { "type": "object", "required": [ "to_address", "value_wei", "chain" ], "properties": { "to_address": { "type": "string", "description": "Destination address (0x-prefixed)" }, "value_wei": { "type": "string", "description": "Transaction value in wei" }, "chain": { "type": "string", "description": "Chain name (e.g. ethereum, base)" }, "chain_id": { "type": "integer", "description": "Numeric chain ID (alternative to chain name)" }, "data_hex": { "type": "string", "description": "Hex-encoded calldata (optional)" }, "operation": { "type": "integer", "description": "Safe operation type (0 = Call, 1 = DelegateCall)", "default": 0 } } }, "SignTreasuryProposalRequest": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "approve", "reject" ], "description": "Whether to approve or reject the proposal" }, "signature": { "type": "string", "description": "EIP-712 signature (hex). If omitted, server signs with caller's key." } } }, "TreasuryProposalResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "treasury_id": { "type": "string", "format": "uuid" }, "proposed_by": { "type": "string", "format": "uuid" }, "proposed_by_type": { "type": "string", "enum": [ "user", "agent" ] }, "chain": { "type": "string" }, "chain_id": { "type": "integer" }, "safe_address": { "type": "string" }, "to_address": { "type": "string" }, "value_wei": { "type": "string" }, "data_hex": { "type": "string", "nullable": true }, "operation": { "type": "integer" }, "safe_tx_hash": { "type": "string", "nullable": true }, "nonce": { "type": "integer", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "approved", "executing", "executed", "rejected", "expired" ] }, "threshold": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "executed_tx_hash": { "type": "string", "nullable": true }, "executed_at": { "type": "string", "format": "date-time", "nullable": true }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/ProposalSignatureResponse" } }, "created_at": { "type": "string", "format": "date-time" } } }, "ProposalSignatureResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "signer_id": { "type": "string", "format": "uuid" }, "signer_type": { "type": "string", "enum": [ "user", "agent" ] }, "signer_address": { "type": "string" }, "signature": { "type": "string" }, "decision": { "type": "string", "enum": [ "approve", "reject" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "TreasuryProposalListResponse": { "type": "object", "properties": { "proposals": { "type": "array", "items": { "$ref": "#/components/schemas/TreasuryProposalResponse" } } } }, "GenerateTreasuryWalletsRequest": { "type": "object", "properties": { "chains": { "type": "array", "items": { "type": "string" }, "description": "Chains to generate wallets for (e.g. [\"ethereum\", \"solana\"]). Omit for all supported chains." } } }, "TreasuryWalletResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "chain": { "type": "string" }, "curve": { "type": "string", "description": "Cryptographic curve (e.g. secp256k1, ed25519)" }, "public_key_hex": { "type": "string" }, "address": { "type": "string" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "TreasuryWalletListResponse": { "type": "object", "properties": { "wallets": { "type": "array", "items": { "$ref": "#/components/schemas/TreasuryWalletResponse" } } } }, "TreasuryWalletExportResponse": { "type": "object", "properties": { "chain": { "type": "string" }, "address": { "type": "string" }, "private_key_hex": { "type": "string", "description": "Raw private key in hex encoding. Handle with extreme care." } } }, "TreasuryWalletBalanceResponse": { "type": "object", "required": [ "chain", "address", "native" ], "properties": { "chain": { "type": "string" }, "address": { "type": "string" }, "native": { "type": "object", "required": [ "symbol", "balance_wei", "balance_display" ], "properties": { "symbol": { "type": "string" }, "balance_wei": { "type": "string" }, "balance_display": { "type": "string" } } }, "tokens": { "type": "array", "items": { "type": "object", "required": [ "contract_address", "balance_raw" ], "properties": { "contract_address": { "type": "string" }, "balance_raw": { "type": "string" } } } } } }, "TreasuryWalletSendRequest": { "type": "object", "required": [ "to", "value_wei" ], "properties": { "to": { "type": "string", "description": "Destination address (0x-prefixed)" }, "value_wei": { "type": "string", "description": "Value in wei (or major-unit decimal string for non-EVM)" }, "data": { "type": "string", "description": "Hex-encoded calldata (optional)" }, "gas_limit": { "type": "integer", "description": "Gas limit override" }, "gasless": { "type": "boolean", "description": "When true, submits as a gasless (ERC-4337) transaction via Pimlico paymaster. The paymaster sponsors the gas cost.", "default": false }, "token_mint": { "type": "string", "description": "Token contract address / mint (ERC-20, SPL, TRC-20, Cardano policy_id.asset_name)" }, "memo": { "type": "string", "description": "Transaction memo (Solana Memo Program, XRP Memos, Tron extra_data)" }, "destination_tag": { "type": "integer", "description": "XRP destination tag" }, "fee_rate_sat_per_vbyte": { "type": "integer", "description": "Bitcoin fee rate in sat/vbyte" }, "xrpl_tx_json": { "type": "object", "description": "Raw XRPL transaction JSON for advanced XRP transaction types" }, "fee_limit_sun": { "type": "integer", "description": "Tron fee limit in sun" }, "token_decimals": { "type": "integer", "description": "Token decimals (required for non-EVM token transfers when not in known_tokens)" }, "ttl": { "type": "integer", "description": "Cardano transaction TTL (slot number)" } } }, "TreasuryWalletSendResponse": { "type": "object", "required": [ "tx_hash", "from", "to", "value_wei", "chain", "status" ], "properties": { "tx_hash": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "value_wei": { "type": "string" }, "chain": { "type": "string" }, "status": { "type": "string" }, "user_op_hash": { "type": "string", "description": "UserOperation hash (only present for gasless sends via paymaster)" } } }, "TreasuryWalletSwapRequest": { "type": "object", "required": [ "sell_token", "buy_token", "sell_amount" ], "properties": { "sell_token": { "type": "string", "description": "Address of the token to sell (or \"native\" for ETH)" }, "buy_token": { "type": "string", "description": "Address of the token to buy (or \"native\" for ETH)" }, "sell_amount": { "type": "string", "description": "Amount to sell in token's smallest unit" } } }, "TreasuryWalletSwapResponse": { "type": "object", "required": [ "tx_hash", "sell_token", "buy_token", "sell_amount", "buy_amount", "chain", "status" ], "properties": { "tx_hash": { "type": "string" }, "sell_token": { "type": "string" }, "buy_token": { "type": "string" }, "sell_amount": { "type": "string" }, "buy_amount": { "type": "string" }, "chain": { "type": "string" }, "status": { "type": "string" } } }, "CreateWebhookRequest": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS URL to deliver webhook events to" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event types to subscribe to" }, "description": { "type": "string" } } }, "UpdateWebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "description": { "type": "string" } } }, "WebhookCreatedResponse": { "type": "object", "required": [ "id", "url", "events", "secret", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "secret": { "type": "string", "description": "HMAC signing secret for verifying payloads (shown only once)" }, "created_at": { "type": "string", "format": "date-time" } } }, "WebhookResponse": { "type": "object", "required": [ "id", "url", "events", "is_active", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "description": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "WebhookListResponse": { "type": "object", "required": [ "webhooks" ], "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "SigningKeyBalanceResponse": { "type": "object", "required": [ "chain", "address", "balance_wei", "balance_display" ], "properties": { "chain": { "type": "string" }, "address": { "type": "string" }, "balance_wei": { "type": "string" }, "balance_display": { "type": "string" }, "tokens": { "type": "array", "description": "Token balances when ?tokens= query param is provided", "items": { "type": "object", "properties": { "contract_address": { "type": "string" }, "symbol": { "type": "string", "nullable": true }, "balance": { "type": "string" }, "decimals": { "type": "integer", "nullable": true } } } } } }, "PaymentRequirement": { "type": "object", "properties": { "x402Version": { "type": "integer" }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "payTo": { "type": "string" }, "price": { "type": "string" }, "requiredDeadlineSeconds": { "type": "integer" } } } }, "description": { "type": "string" } } }, "ShroudActivityEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string" }, "provider": { "type": "string" }, "model": { "type": "string" }, "action": { "type": "string", "description": "Action taken (allowed, blocked, warned)" }, "request_tokens": { "type": "integer" }, "response_tokens": { "type": "integer" }, "latency_ms": { "type": "integer" }, "had_secrets_redacted": { "type": "boolean" }, "had_pii_detected": { "type": "boolean" }, "injection_score": { "type": "number" }, "policy_violations": { "type": "array", "items": { "type": "string" } }, "response_injection_score": { "type": "number", "description": "Response-side prompt-injection score (0.0–1.0)." }, "response_context_injection_score": { "type": "number", "description": "Response-side context-injection score (0.0–1.0)." }, "response_injection_categories": { "type": "array", "items": { "type": "string" }, "description": "Category tags emitted by the response-side filters (e.g. `markdown_image_exfil`, `data_uri_blob`, `echoed_instruction`)." }, "external_urls_flagged": { "type": "array", "items": { "type": "string" }, "description": "URLs emitted by the model that were flagged as potential exfil / callback targets." }, "unexpected_code_blocks": { "type": "integer", "description": "Number of code fences in the response that were not expected for the agent's allowed task set." }, "content_filtered": { "type": "boolean", "description": "True when Shroud rewrote or blocked response content before returning it to the agent." }, "metadata": { "type": "object" }, "timestamp": { "type": "string", "format": "date-time" } } }, "IngestShroudActivityRequest": { "type": "object", "required": [ "agent_id", "action" ], "properties": { "agent_id": { "type": "string" }, "provider": { "type": "string" }, "model": { "type": "string" }, "action": { "type": "string" }, "request_tokens": { "type": "integer", "default": 0 }, "response_tokens": { "type": "integer", "default": 0 }, "latency_ms": { "type": "integer" }, "had_secrets_redacted": { "type": "boolean", "default": false }, "had_pii_detected": { "type": "boolean", "default": false }, "injection_score": { "type": "number", "default": 0 }, "policy_violations": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object" }, "response_injection_score": { "type": "number", "default": 0 }, "response_context_injection_score": { "type": "number", "default": 0 }, "response_injection_categories": { "type": "array", "items": { "type": "string" } }, "external_urls_flagged": { "type": "array", "items": { "type": "string" } }, "unexpected_code_blocks": { "type": "integer", "default": 0 }, "content_filtered": { "type": "boolean", "default": false } } }, "ShroudThreatSummary": { "type": "object", "properties": { "total_requests": { "type": "integer", "format": "int64" }, "total_requests_prev": { "type": "integer", "format": "int64" }, "blocked_requests": { "type": "integer", "format": "int64" }, "detectors_triggered": { "type": "integer", "format": "int64" }, "active_agents": { "type": "integer", "format": "int64" }, "detectors": { "type": "array", "items": { "$ref": "#/components/schemas/ShroudDetectorStats" } }, "flagged_requests": { "type": "array", "items": { "$ref": "#/components/schemas/ShroudFlaggedRequest" } } } }, "ShroudDetectorStats": { "type": "object", "properties": { "detector": { "type": "string" }, "detections": { "type": "integer", "format": "int64" }, "blocks": { "type": "integer", "format": "int64" }, "actions": { "type": "object", "properties": { "blocked": { "type": "integer", "format": "int64" }, "warned": { "type": "integer", "format": "int64" }, "logged": { "type": "integer", "format": "int64" } } } } }, "ShroudFlaggedRequest": { "type": "object", "properties": { "id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "agent_id": { "type": "string" }, "agent_name": { "type": "string" }, "score": { "type": "number" }, "reason": { "type": "string" }, "action": { "type": "string", "enum": [ "blocked", "warned", "logged" ] } } }, "HealthResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy", "degraded" ] }, "version": { "type": "string" } } }, "CreatePlatformAppRequest": { "type": "object", "required": [ "name", "slug" ], "properties": { "name": { "type": "string" }, "slug": { "type": "string", "minLength": 3, "maxLength": 64, "pattern": "^[a-zA-Z0-9_-]+$" }, "description": { "type": "string" }, "oidc_jwks_url": { "type": "string", "format": "uri" }, "oidc_issuer": { "type": "string", "format": "uri" }, "oidc_audience": { "type": "string", "description": "Expected audience claim for OIDC token validation" }, "redirect_uris": { "type": "array", "items": { "type": "string", "format": "uri" } }, "billing_model": { "type": "string", "enum": [ "platform_pays", "user_pays", "hybrid" ], "default": "platform_pays" }, "auth_mode": { "type": "string", "enum": [ "silent", "user_signin", "configurable" ], "default": "silent" }, "max_connected_users": { "type": "integer", "nullable": true }, "api_key_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Optional expiration time for the platform API key." } } }, "UpdatePlatformAppRequest": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "logo_url": { "type": "string" }, "oidc_jwks_url": { "type": "string" }, "oidc_issuer": { "type": "string" }, "oidc_audience": { "type": "string", "description": "Expected audience claim for OIDC token validation" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "webhook_url": { "type": "string" }, "billing_model": { "type": "string", "enum": [ "platform_pays", "user_pays", "hybrid" ] }, "auth_mode": { "type": "string", "enum": [ "silent", "user_signin", "configurable" ] }, "max_connected_users": { "type": "integer", "nullable": true }, "is_active": { "type": "boolean" }, "api_key_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Optional expiration time for the platform API key. Set to null to clear." } } }, "PlatformAppDeleteResponse": { "type": "object", "required": [ "deleted", "soft_delete", "slug_released", "former_slug" ], "properties": { "deleted": { "type": "boolean" }, "soft_delete": { "type": "boolean" }, "slug_released": { "type": "boolean" }, "former_slug": { "type": "string" } } }, "TransferPlatformAppOwnershipRequest": { "type": "object", "properties": { "target_org_id": { "type": "string", "format": "uuid" }, "target_user_email": { "type": "string", "format": "email" } }, "description": "Provide `target_org_id` or `target_user_email` (owner/admin in destination org)." }, "TransferPlatformAppOwnershipResponse": { "type": "object", "required": [ "app_id", "former_org_id", "new_org_id", "message" ], "properties": { "app_id": { "type": "string", "format": "uuid" }, "former_org_id": { "type": "string", "format": "uuid" }, "new_org_id": { "type": "string", "format": "uuid" }, "message": { "type": "string" } } }, "PlatformAppResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "logo_url": { "type": "string", "nullable": true }, "api_key_prefix": { "type": "string" }, "oidc_jwks_url": { "type": "string", "nullable": true }, "oidc_issuer": { "type": "string", "nullable": true }, "oidc_audience": { "type": "string", "nullable": true, "description": "Expected audience claim for OIDC token validation" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "webhook_url": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "billing_model": { "type": "string" }, "auth_mode": { "type": "string" }, "max_connected_users": { "type": "integer", "nullable": true }, "connected_users": { "type": "integer" }, "api_key_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the platform API key expires." }, "api_key_rotated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the platform API key was last rotated." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "PlatformAppCreatedResponse": { "allOf": [ { "$ref": "#/components/schemas/PlatformAppResponse" }, { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "The platform API key. Save immediately - it cannot be retrieved again." } } } ] }, "CreateTemplateRequest": { "type": "object", "required": [ "name", "spec" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "spec": { "type": "object", "description": "Template specification defining vault, agents, policies, and signing keys to bootstrap.\nTop-level fields: `vault` (object with name, description), `agents` (array of agent specs\nwith name, description, shroud_enabled, intents, shroud_config), `policies` (array with\nvault_ref, principal_ref, paths, permissions, conditions), and `signing_keys` (array of\n`{ chain }` objects — supported chains: ethereum, bitcoin, solana, xrp, cardano, tron).\nWhen `signing_keys` is present, HSM-backed signing keys are auto-provisioned for the\nbootstrapped agent.\n" } } }, "PlatformTemplateResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "platform_app_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "integer" }, "spec": { "type": "object" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "UpsertPlatformUserRequest": { "type": "object", "properties": { "subject_token": { "type": "string", "description": "OIDC JWT from the platform's IdP (verified against JWKS)" }, "subject_token_type": { "type": "string", "default": "urn:ietf:params:oauth:token-type:jwt", "description": "Token type for subject_token. Use `urn:1claw:params:oauth:token-type:siwe`\nwith `siwe_message` and `siwe_signature` for wallet-based provisioning.\n" }, "email": { "type": "string", "format": "email", "description": "Fallback when subject_token is not provided" }, "display_name": { "type": "string" }, "siwe_message": { "type": "string", "description": "EIP-4361 Sign-In With Ethereum message (required for SIWE upsert)" }, "siwe_signature": { "type": "string", "description": "Hex-encoded SIWE signature (required for SIWE upsert)" }, "return_to": { "type": "string", "format": "uri", "description": "Redirect URL after cross-org link consent" }, "create_sub_org": { "type": "boolean", "default": false, "description": "When true, creates a sub-org under the platform app's org" } } }, "PlatformUserResponse": { "type": "object", "properties": { "user_handle": { "type": "string", "format": "uuid" }, "is_new": { "type": "boolean" }, "connection_id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "link_required": { "$ref": "#/components/schemas/LinkRequiredInfo" } } }, "PlatformUserLinkRequiredResponse": { "type": "object", "required": [ "is_new", "email", "link_required" ], "properties": { "is_new": { "type": "boolean", "example": false }, "email": { "type": "string" }, "link_required": { "$ref": "#/components/schemas/LinkRequiredInfo" } } }, "LinkRequiredInfo": { "type": "object", "required": [ "status", "reason", "authorize_url", "app_slug" ], "properties": { "status": { "type": "string", "enum": [ "link_required" ] }, "reason": { "type": "string", "example": "user_exists_in_other_org" }, "authorize_url": { "type": "string", "format": "uri", "description": "OAuth authorize URL the platform app should redirect the user to for consent." }, "app_slug": { "type": "string" } } }, "PlatformConnectedUserResponse": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "external_subject": { "type": "string" }, "status": { "type": "string" }, "vault_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "agent_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "created_at": { "type": "string", "format": "date-time" }, "claimed_at": { "type": "string", "format": "date-time", "nullable": true } } }, "BootstrapRequest": { "type": "object", "properties": { "template_id": { "type": "string", "format": "uuid", "description": "Template to use. Falls back to the app's default template." }, "return_to": { "type": "string", "format": "uri", "description": "URL to redirect the user to after claiming resources." }, "parameters": { "type": "object", "additionalProperties": true, "description": "Template parameters substituted as `{{params.*}}` during bootstrap.\nCombined with `Idempotency-Key` header for params-aware idempotent replay.\n" } } }, "BootstrapResponse": { "type": "object", "properties": { "claim_url": { "type": "string", "format": "uri" }, "claim_token": { "type": "string" }, "expires_in": { "type": "integer", "description": "Seconds until the claim token expires" }, "connection_id": { "type": "string", "format": "uuid" }, "summary": { "type": "object", "properties": { "vault_id": { "type": "string", "format": "uuid", "nullable": true }, "agent_id": { "type": "string", "format": "uuid", "nullable": true }, "agent_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "All agent IDs provisioned by the template (when multiple agents are defined)" }, "policy_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "signing_key_chains": { "type": "array", "items": { "type": "string" }, "description": "Chains with provisioned signing keys" }, "agent_api_key": { "type": "string", "nullable": true, "description": "One-time agent API key (ocv_ prefix). Store securely — not retrievable later." }, "agent_evm_address": { "type": "string", "nullable": true, "description": "EOA address when provision_eoa is true in the template" }, "signing_keys": { "type": "array", "description": "Provisioned signing key details (chain, address, public key)", "items": { "type": "object", "properties": { "chain": { "type": "string" }, "curve": { "type": "string" }, "public_key": { "type": "string" }, "address": { "type": "string" } } } }, "runtime_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "IDs of runtimes provisioned by the template" }, "automation_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "IDs of automations provisioned by the template" } } } } }, "PlatformAppStatsResponse": { "type": "object", "required": [ "total_connections", "active_connections", "claimed_connections", "total_bootstraps", "total_grants" ], "properties": { "total_connections": { "type": "integer", "description": "Total number of user connections (all statuses)" }, "active_connections": { "type": "integer", "description": "Number of active connections" }, "claimed_connections": { "type": "integer", "description": "Number of claimed connections" }, "total_bootstraps": { "type": "integer", "description": "Total bootstrap operations performed" }, "total_grants": { "type": "integer", "description": "Total resource grants issued" } } }, "MarketplaceResponse": { "type": "object", "properties": { "apps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "logo_url": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "listing_tags": { "type": "array", "items": { "type": "string" } }, "listing_screenshots": { "type": "array", "items": { "type": "string" } }, "pricing_summary": { "type": "string", "nullable": true } } } } } }, "ConnectedAppResponse": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid" }, "app_name": { "type": "string" }, "app_slug": { "type": "string" }, "status": { "type": "string" }, "vault_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "agent_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "created_at": { "type": "string", "format": "date-time" } } }, "GrantResourcesRequest": { "type": "object", "properties": { "vault_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Vault IDs to grant access to" }, "agent_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Agent IDs to grant access to" }, "allowed_paths": { "type": "array", "items": { "type": "string" }, "default": [ "**" ], "description": "Secret path patterns the app can access" }, "permissions": { "type": "array", "items": { "type": "string" }, "default": [ "read" ], "description": "Permissions granted (read, write, rotate)" }, "expires_at": { "type": "string", "format": "date-time", "description": "Optional grant expiration" } } }, "GrantResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "vault_id": { "type": "string", "format": "uuid" }, "allowed_paths": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "GrantResourcesResponse": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid" }, "grants": { "type": "array", "items": { "$ref": "#/components/schemas/GrantResponse" } }, "vault_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "agent_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "GrantListResponse": { "type": "object", "properties": { "grants": { "type": "array", "items": { "$ref": "#/components/schemas/GrantResponse" } } } }, "ClaimPreviewResponse": { "type": "object", "properties": { "app_name": { "type": "string" }, "app_slug": { "type": "string" }, "app_logo_url": { "type": "string", "nullable": true }, "auth_mode": { "type": "string" }, "vault_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "agent_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "policy_count": { "type": "integer" }, "status": { "type": "string" }, "already_claimed": { "type": "boolean" }, "expired": { "type": "boolean" }, "return_to": { "type": "string", "nullable": true } } }, "ClaimRedeemResponse": { "type": "object", "properties": { "status": { "type": "string" }, "connection_id": { "type": "string", "format": "uuid" }, "vault_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "agent_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "return_to": { "type": "string", "nullable": true }, "dashboard_url": { "type": "string" } } }, "RegisterDeviceRequest": { "type": "object", "required": [ "name", "platform", "public_key_pem" ], "properties": { "name": { "type": "string", "description": "Human-readable device name (e.g. \"Kevin's iPhone\")", "example": "My iPhone" }, "platform": { "type": "string", "enum": [ "ios", "android" ] }, "public_key_pem": { "type": "string", "description": "PEM-encoded public key for step-up challenge signing" }, "attestation_blob": { "type": "string", "description": "Optional platform attestation (Apple DeviceCheck / Android SafetyNet)" } } }, "RegisterDeviceResponse": { "type": "object", "required": [ "device_id", "attestation_verified" ], "properties": { "device_id": { "type": "string", "format": "uuid" }, "attestation_verified": { "type": "boolean" } } }, "DeviceListResponse": { "type": "object", "required": [ "devices" ], "properties": { "devices": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceResponse" } } } }, "DeviceResponse": { "type": "object", "required": [ "id", "name", "platform", "attestation_verified", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "platform": { "type": "string" }, "attestation_verified": { "type": "boolean" }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "CreateDeviceChallengeRequest": { "type": "object", "required": [ "action", "target_id" ], "properties": { "action": { "type": "string", "description": "The action this challenge authorizes (e.g. \"approve_transaction\")" }, "target_id": { "type": "string", "description": "ID of the resource the action targets" } } }, "DeviceChallengeResponse": { "type": "object", "required": [ "challenge_nonce", "expires_at", "action_bound_hash" ], "properties": { "challenge_nonce": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "action_bound_hash": { "type": "string", "description": "SHA-256 binding the challenge to the requested action and target" } } }, "AttestDeviceChallengeRequest": { "type": "object", "required": [ "challenge_nonce", "signature" ], "properties": { "challenge_nonce": { "type": "string" }, "signature": { "type": "string", "description": "Signature over the challenge nonce using the device's private key" } } }, "AttestDeviceChallengeResponse": { "type": "object", "required": [ "step_up_token", "expires_at" ], "properties": { "step_up_token": { "type": "string", "description": "Short-lived token authorizing the bound action" }, "expires_at": { "type": "string", "format": "date-time" } } }, "RegisterPushTokenRequest": { "type": "object", "required": [ "token", "platform" ], "properties": { "token": { "type": "string", "description": "Push notification token from APNs or FCM" }, "platform": { "type": "string", "enum": [ "apns", "fcm" ] } } }, "DecideApprovalRequest": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "approve", "reject" ] }, "reason": { "type": "string", "description": "Optional human-readable reason for the decision" } } }, "ApprovalResponse": { "type": "object", "required": [ "id", "org_id", "user_id", "action", "target_type", "target_id", "risk_tier", "status", "summary", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid", "nullable": true }, "action": { "type": "string" }, "target_type": { "type": "string" }, "target_id": { "type": "string" }, "risk_tier": { "type": "integer", "minimum": 1, "maximum": 3 }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired" ] }, "summary": { "type": "object", "description": "Structured summary of the action requiring approval" }, "reason": { "type": "string", "nullable": true }, "decision_reason": { "type": "string", "nullable": true }, "decided_by": { "type": "string", "format": "uuid", "nullable": true }, "decided_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "ApprovalListResponse": { "type": "object", "required": [ "approvals", "total" ], "properties": { "approvals": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalResponse" } }, "total": { "type": "integer" } } }, "ApprovalStatusResponse": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired" ] }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } } }, "GuardrailReasonCode": { "type": "string", "description": "Stable snake_case reason codes for guardrail violations (Convention 1).\nShadow-mode `\"log\"` emits the same codes in `guardrail_shadow.would_deny`\naudit events with `enforced: false`. 202 HITL responses use\n`approval_available: true` instead of a deny reason_code.\n", "enum": [ "binding_rpm_exceeded", "agent_rpm_exceeded", "graphql_mutation_blocked", "graphql_depth_exceeded", "graphql_parse_failed", "graphql_introspection_blocked", "response_too_large", "request_too_large", "method_not_allowed", "header_not_allowed", "dns_private_ip_blocked", "agent_suspended", "outside_time_window", "secret_in_request", "concurrency_exceeded", "org_frozen", "price_unavailable", "gas_fee_exceeded", "unlimited_approval_blocked", "tx_per_recipient_limit_exceeded", "tx_max_value_exceeded", "tx_daily_limit_exceeded", "delegation_signing_blocked", "recipient_screening_failed", "screening_provider_unavailable", "human_factor_auth_required", "register_passkey_required" ] }, "GuardrailViolation": { "type": "object", "description": "Convention 1 machine-readable guardrail denial JSON body.", "required": [ "error", "reason_code", "approval_available" ], "properties": { "error": { "type": "string", "enum": [ "guardrail_violation" ] }, "reason_code": { "$ref": "#/components/schemas/GuardrailReasonCode" }, "limit": { "type": "string", "nullable": true }, "current": { "type": "string", "nullable": true }, "attempted": { "type": "string", "nullable": true }, "approval_available": { "type": "boolean", "default": false }, "retry_after_seconds": { "type": "integer", "nullable": true }, "detail": { "type": "string", "nullable": true } } }, "GuardrailDenial": { "description": "Alias of GuardrailViolation (Convention 1 JSON shape).", "allOf": [ { "$ref": "#/components/schemas/GuardrailViolation" } ] }, "EmailOtpVerifyResponse": { "type": "object", "required": [ "token", "user_id", "org_id", "is_new_user", "email" ], "properties": { "token": { "type": "string", "description": "JWT access token" }, "user_id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "is_new_user": { "type": "boolean" }, "email": { "type": "string", "format": "email" }, "wallet_address": { "type": "string", "nullable": true, "description": "Ethereum address if auto_provision_chains included an EVM chain" } } }, "OAuthConsentResponse": { "type": "object", "required": [ "app_name", "app_slug", "scopes", "redirect_uri", "already_consented" ], "properties": { "app_name": { "type": "string" }, "app_slug": { "type": "string" }, "app_logo_url": { "type": "string", "format": "uri", "nullable": true }, "scopes": { "type": "array", "items": { "type": "string" } }, "redirect_uri": { "type": "string", "format": "uri" }, "already_consented": { "type": "boolean" } } }, "OAuthTokenResponse": { "type": "object", "required": [ "access_token", "token_type", "expires_in", "scope" ], "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "enum": [ "Bearer" ] }, "expires_in": { "type": "integer", "description": "Token lifetime in seconds" }, "refresh_token": { "type": "string", "nullable": true, "description": "Refresh token for obtaining new access tokens (when offline_access scope was granted)" }, "id_token": { "type": "string", "nullable": true, "description": "OIDC ID token (when openid scope was granted)" }, "scope": { "type": "string" } } }, "OAuthUserInfoResponse": { "type": "object", "required": [ "sub", "email" ], "properties": { "sub": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string", "nullable": true }, "wallet_address": { "type": "string", "nullable": true } } }, "CreateSpendPolicyRequest": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid", "description": "Scope to a specific user (app-level policies only)" }, "to_allowlist": { "type": "array", "items": { "type": "string" }, "description": "Permitted destination addresses (empty = unrestricted)" }, "to_denylist": { "type": "array", "items": { "type": "string" }, "description": "Blocked destination addresses" }, "max_value_per_tx_eth": { "type": "string", "description": "Maximum value per transaction in ETH (decimal string)" }, "daily_limit_eth": { "type": "string", "description": "Rolling 24h spend cap in ETH (decimal string)" }, "allowed_chains": { "type": "array", "items": { "type": "string" }, "description": "Chains the user may transact on (empty = all enabled)" }, "allowed_tokens": { "type": "array", "items": { "type": "string" }, "description": "Permitted ERC-20 token contract addresses" }, "max_transactions_per_day": { "type": "integer", "description": "Maximum number of transactions per 24h window" }, "inference_allowance_usd": { "type": "string", "description": "Monthly LLM inference allowance in USD (decimal string)" }, "inference_reserved_pct": { "type": "integer", "minimum": 0, "maximum": 100, "default": 25, "description": "Percent of allowance held in reserve (not spendable)" }, "inference_hard_stop": { "type": "boolean", "default": true, "description": "When true, block inference when allowance is exhausted" }, "inference_allowance_mode": { "type": "string", "enum": [ "policy", "credits" ], "default": "policy" }, "max_request_cost_usd": { "type": "string", "description": "Maximum estimated cost per LLM request in USD" }, "human_factor_auth": { "type": "object", "additionalProperties": true, "description": "Human factor auth requirements for send/swap/export.\nFields: send, swap, export (password_or_passkey | passkey_only | passkey_required | password_only | reauth_token_only),\nconditional.require_passkey_above_usd, conditional.require_passkey_for_new_recipient.\n" } } }, "SiweChallengeRequest": { "type": "object", "properties": { "domain": { "type": "string", "description": "Optional SIWE domain override (defaults to platform app's siwe_domain)" } } }, "SiweChallengeResponse": { "type": "object", "required": [ "nonce", "expires_in", "domain" ], "properties": { "nonce": { "type": "string" }, "expires_in": { "type": "integer", "description": "Seconds until nonce expiry" }, "domain": { "type": "string" } } }, "ConnectionDetailResponse": { "type": "object", "required": [ "connection_id", "user_id", "status", "entitlement_status", "vault_ids", "agent_ids", "claim" ], "properties": { "connection_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "entitlement_status": { "type": "string" }, "wallet_address": { "type": "string", "nullable": true }, "vault_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "agent_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "claimed_at": { "type": "string", "format": "date-time", "nullable": true }, "claim": { "$ref": "#/components/schemas/ClaimStatusResponse" } } }, "ClaimStatusResponse": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "pending", "active", "claimed" ] }, "redeemed_at": { "type": "string", "format": "date-time", "nullable": true } } }, "ConnectionUsageResponse": { "type": "object", "required": [ "connection_id", "period", "inference_spent_usd" ], "properties": { "connection_id": { "type": "string", "format": "uuid" }, "period": { "type": "string", "description": "UTC month (YYYY-MM)" }, "inference_spent_usd": { "type": "string" } } }, "EntitlementsListResponse": { "type": "object", "required": [ "evaluations" ], "properties": { "evaluations": { "type": "array", "items": { "$ref": "#/components/schemas/EntitlementEvaluationResponse" } } } }, "EntitlementEvaluationResponse": { "type": "object", "required": [ "id", "status", "watch_kind", "chain", "holder_address" ], "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "watch_kind": { "type": "string" }, "chain": { "type": "string" }, "holder_address": { "type": "string" }, "last_value_raw": { "type": "string", "nullable": true }, "last_checked_at": { "type": "string", "format": "date-time", "nullable": true } } }, "TemplatePreviewRequest": { "type": "object", "properties": { "parameters": { "type": "object", "additionalProperties": true }, "subject": { "type": "object", "properties": { "user_id": { "type": "string" }, "external_subject": { "type": "string" }, "wallet_address": { "type": "string" }, "email": { "type": "string" } } } } }, "TemplatePreviewResponse": { "type": "object", "required": [ "resolved_spec" ], "properties": { "resolved_spec": { "type": "object", "additionalProperties": true } } }, "InferenceBudgetResponse": { "type": "object", "required": [ "allowance_usd", "spent_usd", "remaining_usd", "reserved_pct", "max_request_cost_usd", "period_end" ], "properties": { "allowance_usd": { "type": "string" }, "spent_usd": { "type": "string" }, "remaining_usd": { "type": "string" }, "reserved_pct": { "type": "integer" }, "max_request_cost_usd": { "type": "string" }, "period_end": { "type": "string", "format": "date-time" }, "connection_id": { "type": "string", "format": "uuid", "nullable": true } } }, "InferenceBudgetUnconfiguredResponse": { "type": "object", "properties": { "allowance_usd": { "type": "string", "nullable": true }, "remaining_usd": { "nullable": true }, "message": { "type": "string" } } }, "SpendPolicyResponse": { "type": "object", "required": [ "id", "platform_app_id", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "platform_app_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid", "nullable": true }, "to_allowlist": { "type": "array", "items": { "type": "string" } }, "to_denylist": { "type": "array", "items": { "type": "string" } }, "max_value_per_tx_eth": { "type": "string", "nullable": true }, "daily_limit_eth": { "type": "string", "nullable": true }, "allowed_chains": { "type": "array", "items": { "type": "string" } }, "allowed_tokens": { "type": "array", "items": { "type": "string" } }, "max_transactions_per_day": { "type": "integer", "nullable": true }, "inference_allowance_usd": { "type": "string", "nullable": true }, "inference_reserved_pct": { "type": "integer", "nullable": true }, "inference_hard_stop": { "type": "boolean", "nullable": true }, "inference_allowance_mode": { "type": "string", "nullable": true }, "max_request_cost_usd": { "type": "string", "nullable": true }, "human_factor_auth": { "type": "object", "additionalProperties": true, "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "HumanFactorAuthPolicy": { "type": "object", "properties": { "send": { "type": "string", "enum": [ "password_or_passkey", "passkey_only", "passkey_required", "password_only", "reauth_token_only" ] }, "swap": { "type": "string", "enum": [ "password_or_passkey", "passkey_only", "passkey_required", "password_only", "reauth_token_only" ] }, "export": { "type": "string", "enum": [ "password_or_passkey", "passkey_only", "passkey_required", "password_only", "reauth_token_only" ] }, "conditional": { "type": "object", "properties": { "require_passkey_above_usd": { "type": "string", "nullable": true }, "require_passkey_for_new_recipient": { "type": "boolean" } } } } }, "UpsertHumanFactorAuthRequest": { "type": "object", "required": [ "policy" ], "properties": { "policy": { "$ref": "#/components/schemas/HumanFactorAuthPolicy" } } }, "HumanFactorAuthResponse": { "type": "object", "required": [ "policy", "source" ], "properties": { "policy": { "$ref": "#/components/schemas/HumanFactorAuthPolicy" }, "source": { "type": "string", "description": "user | platform_app | spend_policy | default" } } }, "TreasuryAuthPolicyResponse": { "type": "object", "required": [ "policy", "source", "registered_passkeys" ], "properties": { "policy": { "$ref": "#/components/schemas/HumanFactorAuthPolicy" }, "source": { "type": "string", "description": "user | platform_app | spend_policy | default" }, "registered_passkeys": { "type": "integer", "minimum": 0, "description": "Number of WebAuthn passkeys registered for the calling user." } } }, "PasskeyTxAssertBeginRequest": { "type": "object", "required": [ "tx_digest" ], "properties": { "tx_digest": { "type": "string", "description": "64-char hex SHA-256 of canonical send or swap params" }, "action": { "type": "string", "enum": [ "send", "swap" ], "default": "send", "description": "Treasury action being authorized. Defaults to `send`." } } }, "PasskeyAssertBeginResponse": { "type": "object", "required": [ "challenge", "rp_id", "timeout", "user_verification", "allow_credentials" ], "properties": { "challenge": { "type": "string" }, "rp_id": { "type": "string" }, "timeout": { "type": "integer" }, "user_verification": { "type": "string" }, "allow_credentials": { "type": "array", "items": { "$ref": "#/components/schemas/AllowCredential" } } } }, "AllowCredential": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "public-key" ] }, "transports": { "type": "array", "items": { "type": "string" } } } }, "MfaPasskeyCompleteRequest": { "type": "object", "required": [ "mfa_token", "credential_id", "authenticator_data", "client_data_json", "signature" ], "properties": { "mfa_token": { "type": "string" }, "credential_id": { "type": "string" }, "authenticator_data": { "type": "string" }, "client_data_json": { "type": "string" }, "signature": { "type": "string" } } }, "GuardrailWideningQueuedResponse": { "type": "object", "required": [ "status", "approval_id", "revision_id", "message" ], "properties": { "status": { "type": "string", "enum": [ "awaiting_approval" ] }, "approval_id": { "type": "string", "format": "uuid" }, "revision_id": { "type": "string", "format": "uuid" }, "message": { "type": "string", "description": "Human-readable explanation of the queued change." } } }, "RiskEvent": { "type": "object", "required": [ "id", "occurred_at", "principal_type", "principal_id", "org_id", "event_type", "payload", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "occurred_at": { "type": "string", "format": "date-time" }, "principal_type": { "type": "string", "enum": [ "user", "agent" ] }, "principal_id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "event_type": { "type": "string", "description": "Risk event type (e.g. first_seen, geo_velocity, honeytoken_access)" }, "ip": { "type": "string", "nullable": true }, "asn": { "type": "integer", "nullable": true }, "asn_org": { "type": "string", "nullable": true }, "country_code": { "type": "string", "nullable": true }, "region": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "latitude": { "type": "number", "nullable": true }, "longitude": { "type": "number", "nullable": true }, "user_agent": { "type": "string", "nullable": true }, "severity": { "type": "string", "nullable": true, "description": "Computed severity at event time (low, medium, high, critical)" }, "payload": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } } }, "RiskEventListResponse": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/RiskEvent" } } } }, "RiskVerdictReason": { "type": "object", "required": [ "detector", "severity", "description" ], "properties": { "detector": { "type": "string" }, "severity": { "type": "string" }, "description": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } }, "RiskVerdict": { "type": "object", "required": [ "principal_type", "principal_id", "org_id", "score", "severity", "reasons", "computed_at", "expires_at" ], "properties": { "principal_type": { "type": "string" }, "principal_id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "score": { "type": "number", "description": "Composite risk score (0.0 – 100.0)" }, "severity": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "reasons": { "type": "array", "items": { "$ref": "#/components/schemas/RiskVerdictReason" } }, "computed_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } } }, "RiskVerdictListResponse": { "type": "object", "required": [ "verdicts" ], "properties": { "verdicts": { "type": "array", "items": { "$ref": "#/components/schemas/RiskVerdict" } } } }, "Honeytoken": { "type": "object", "required": [ "id", "vault_id", "org_id", "secret_path", "created_by", "created_at", "triggered_count" ], "properties": { "id": { "type": "string", "format": "uuid" }, "vault_id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "secret_path": { "type": "string" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "notes": { "type": "string", "nullable": true }, "triggered_count": { "type": "integer" }, "last_triggered_at": { "type": "string", "format": "date-time", "nullable": true } } }, "CreateHoneytokenRequest": { "type": "object", "required": [ "vault_id", "secret_path" ], "properties": { "vault_id": { "type": "string", "format": "uuid" }, "secret_path": { "type": "string", "description": "Vault secret path to monitor as a canary" }, "notes": { "type": "string", "description": "Optional human-readable notes about this honeytoken" } } }, "HoneytokenListResponse": { "type": "object", "required": [ "honeytokens" ], "properties": { "honeytokens": { "type": "array", "items": { "$ref": "#/components/schemas/Honeytoken" } } } }, "CredentialSource": { "type": "object", "required": [ "type" ], "description": "Credential source — inline value (stored in __agent-keys) or live pointer to a vault secret (resolved at execution time).", "discriminator": { "propertyName": "type" }, "properties": { "type": { "type": "string", "enum": [ "inline", "vault_ref" ] }, "value": { "type": "object", "additionalProperties": true, "description": "For inline — the credential value object." }, "vault_id": { "type": "string", "format": "uuid", "description": "For vault_ref — the vault containing the referenced secret." }, "path": { "type": "string", "description": "For vault_ref — the secret path in the vault." } } }, "CreateBindingRequest": { "type": "object", "required": [ "name", "binding_type" ], "properties": { "name": { "type": "string" }, "binding_type": { "type": "string", "enum": [ "http", "graphql", "postgres", "mysql", "redis", "grpc", "smtp", "cloud_sdk", "s3", "custom" ] }, "config": { "type": "object", "additionalProperties": true }, "guardrails": { "$ref": "#/components/schemas/BindingGuardrails" }, "credential": { "type": "object", "additionalProperties": true, "description": "Legacy: inline credential value. Use credential_source for new integrations." }, "credential_source": { "$ref": "#/components/schemas/CredentialSource" } } }, "UpdateBindingRequest": { "type": "object", "properties": { "config": { "type": "object", "additionalProperties": true }, "guardrails": { "$ref": "#/components/schemas/BindingGuardrails" }, "is_active": { "type": "boolean" }, "credential": { "type": "object", "additionalProperties": true, "description": "Legacy: inline credential value." }, "credential_source": { "$ref": "#/components/schemas/CredentialSource" }, "approval_id": { "type": "string", "format": "uuid", "description": "Approved policy_change id when applying a queued binding guardrail widening. Resubmit PATCH with this field after approval via POST /v1/approvals/{approval_id}/decide.\n" } } }, "BindingGuardrails": { "type": "object", "description": "Per-binding execution guardrails enforced at execute time.", "properties": { "allowed_hosts": { "type": "array", "items": { "type": "string" }, "description": "Host allowlist (trailing * wildcard supported). Empty = unrestricted at binding level." }, "allowed_paths": { "type": "array", "items": { "type": "string" }, "description": "Path allowlist for HTTP/GraphQL bindings." }, "max_requests_per_minute": { "type": "integer", "minimum": 1, "description": "Per-binding RPM; strictest of binding and agent limits wins. Denied executions do not count." }, "max_duration_ms": { "type": "integer", "description": "Upstream timeout cap for this binding." }, "max_request_bytes": { "type": "integer", "default": 262144, "description": "Max serialized execute `params` size in bytes (default 256 KiB)." }, "max_response_bytes": { "type": "integer", "description": "Max upstream response body bytes (default 1 MiB, hard cap 4 MiB)." }, "allowed_request_headers": { "type": "array", "items": { "type": "string" }, "description": "Agent-supplied headers permitted in execute params. Defaults to content-type, accept, user-agent, idempotency-key." }, "allow_mutations": { "type": "boolean", "default": true, "description": "GraphQL only — when false, mutation operations return 403 guardrail_violation." }, "allow_introspection": { "type": "boolean", "default": false, "description": "GraphQL only — when false, __schema/__type introspection is blocked." }, "max_query_depth": { "type": "integer", "default": 10, "description": "GraphQL max selection depth." }, "max_aliases": { "type": "integer", "default": 30, "description": "GraphQL max alias count." }, "allowed_operations": { "type": "array", "items": { "type": "string" }, "description": "GraphQL operation kinds allowed (query, mutation, subscription)." } } }, "BindingResponse": { "type": "object", "required": [ "id", "agent_id", "binding_type", "name", "is_active", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "binding_type": { "type": "string", "enum": [ "http", "graphql", "postgres", "mysql", "redis", "grpc", "smtp", "cloud_sdk", "s3", "custom" ] }, "name": { "type": "string" }, "config": { "type": "object", "additionalProperties": true }, "guardrails": { "$ref": "#/components/schemas/BindingGuardrails" }, "is_active": { "type": "boolean" }, "credential_set": { "type": "boolean", "description": "Whether a credential is stored for this binding. The value itself is never returned." }, "credential_source_type": { "type": "string", "enum": [ "inline", "vault_ref" ], "nullable": true, "description": "How the credential is sourced — inline (HSM-encrypted copy) or vault_ref (live pointer)." }, "credential_vault_id": { "type": "string", "format": "uuid", "nullable": true, "description": "For vault_ref credentials — the vault containing the referenced secret." }, "credential_path": { "type": "string", "nullable": true, "description": "For vault_ref credentials — the secret path in the referenced vault." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TestBindingResponse": { "type": "object", "required": [ "success", "latency_ms" ], "properties": { "success": { "type": "boolean" }, "latency_ms": { "type": "integer" }, "error": { "type": "string", "nullable": true } } }, "ExecuteRequest": { "type": "object", "required": [ "binding", "intent_type", "params" ], "properties": { "binding": { "type": "string", "description": "Binding name or ID to execute against" }, "intent_type": { "type": "string", "description": "Type of execution intent (e.g. http_request, graphql_query)" }, "execution_mode": { "type": "string", "enum": [ "vault", "tee" ], "default": "vault", "description": "Where execution runs (vault = server-side, tee = Shroud TEE)" }, "params": { "type": "object", "additionalProperties": true, "description": "Intent-specific parameters" }, "dry_run": { "type": "boolean", "default": false, "description": "When true, validate guardrails and approval policy without executing or persisting side effects." }, "resume_after_approval_id": { "type": "string", "format": "uuid", "description": "Internal — resume execution after human approval (server-injected)." } } }, "ExecutionApprovalRequired": { "type": "object", "required": [ "error", "approval_id", "status" ], "properties": { "error": { "type": "string", "enum": [ "approval_required" ] }, "approval_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending" ] }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } } }, "TxAwaitingApproval": { "type": "object", "required": [ "status", "approval_id" ], "properties": { "status": { "type": "string", "enum": [ "awaiting_approval" ] }, "approval_id": { "type": "string", "format": "uuid" }, "tx_id": { "type": "string", "format": "uuid", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } } }, "ExecuteResponse": { "type": "object", "required": [ "execution_id", "status", "duration_ms", "redactions_applied" ], "properties": { "execution_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "result": { "type": "object", "additionalProperties": true, "nullable": true }, "error": { "type": "string", "nullable": true }, "duration_ms": { "type": "integer" }, "redactions_applied": { "type": "integer" }, "execution_surface": { "type": "string", "enum": [ "vault", "tee" ], "description": "Where the intent actually ran. Reported truthfully — never claims TEE when it ran in the Vault." } } }, "ExecutionEventResponse": { "type": "object", "required": [ "id", "agent_id", "binding_id", "intent_type", "execution_mode", "status", "duration_ms", "redactions_applied", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "binding_id": { "type": "string", "format": "uuid" }, "intent_type": { "type": "string" }, "execution_mode": { "type": "string" }, "status": { "type": "string" }, "request_summary": { "type": "object", "additionalProperties": true, "nullable": true }, "result_summary": { "type": "object", "additionalProperties": true, "nullable": true }, "error_message": { "type": "string", "nullable": true }, "duration_ms": { "type": "integer" }, "cost_cents": { "type": "integer", "nullable": true }, "redactions_applied": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } }, "CreateAutomationRequest": { "type": "object", "required": [ "name", "agent_id", "trigger_type", "workflow_spec" ], "description": "Create an automation. `workflow_spec` is required and must be either\na JSON array of steps or `{ \"steps\": [...] }`. Dashboard `schedule`\ntrigger_type is accepted and normalized to `cron`. For cron triggers,\n`cron_expr` is required.\n", "properties": { "name": { "type": "string" }, "agent_id": { "type": "string", "format": "uuid" }, "trigger_type": { "type": "string", "description": "cron | event | webhook | manual (alias schedule → cron)", "enum": [ "cron", "event", "webhook", "manual", "schedule" ] }, "cron_expr": { "type": "string", "description": "Required when trigger_type is cron (or schedule)", "example": "0 */6 * * *" }, "timezone": { "type": "string", "default": "UTC", "example": "UTC" }, "event_filter": { "type": "object", "additionalProperties": true, "nullable": true }, "workflow_spec": { "description": "Workflow steps. Accepts a bare array `[...]` or\n`{ \"steps\": [...] }` (dashboard / preset shape).\nSupported step types: get_secret, put_secret, http_request,\nrotate_secret, notify_human, ai_generate, memory_get,\nmemory_put, memory_search, notify, approval_request,\ncondition, execute_binding.\n", "oneOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": true } }, { "type": "object", "additionalProperties": true } ] } } }, "UpdateAutomationRequest": { "type": "object", "properties": { "name": { "type": "string" }, "cron_expr": { "type": "string", "nullable": true }, "timezone": { "type": "string" }, "event_filter": { "type": "object", "additionalProperties": true, "nullable": true }, "workflow_spec": { "oneOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": true } }, { "type": "object", "additionalProperties": true } ] }, "is_active": { "type": "boolean" } } }, "AutomationResponse": { "type": "object", "required": [ "id", "agent_id", "name", "trigger_type", "timezone", "workflow_spec", "is_active", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "trigger_type": { "type": "string", "enum": [ "cron", "event", "webhook", "manual" ] }, "cron_expr": { "type": "string", "nullable": true }, "timezone": { "type": "string" }, "event_filter": { "type": "object", "additionalProperties": true, "nullable": true }, "workflow_spec": { "oneOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": true } }, { "type": "object", "additionalProperties": true } ] }, "is_active": { "type": "boolean" }, "last_run_at": { "type": "string", "format": "date-time", "nullable": true }, "next_run_at": { "type": "string", "format": "date-time", "nullable": true }, "last_run_status": { "type": "string", "nullable": true, "description": "Status of the most recent run (enriched list field)" }, "total_runs": { "type": "integer", "nullable": true, "description": "Total runs in the last 30 days (enriched list field)" }, "success_rate": { "type": "number", "nullable": true, "description": "Success rate percentage (enriched list field)" }, "agent_name": { "type": "string", "nullable": true, "description": "Resolved agent display name (enriched list field)" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AutomationCreatedResponse": { "allOf": [ { "$ref": "#/components/schemas/AutomationResponse" }, { "type": "object", "properties": { "webhook_url": { "type": "string", "description": "Full POST URL including token (one-time on create)" }, "webhook_token": { "type": "string", "description": "whk_ token segment (one-time on create)" } } } ] }, "WebhookTokenRotatedResponse": { "type": "object", "required": [ "webhook_url", "webhook_token" ], "properties": { "webhook_url": { "type": "string" }, "webhook_token": { "type": "string" } } }, "AssistDraftResponse": { "type": "object", "required": [ "draft", "reply" ], "properties": { "draft": { "type": "object", "additionalProperties": true }, "reply": { "type": "string" } } }, "AssistSessionResponse": { "type": "object", "required": [ "access_token", "expires_in", "scopes", "cli_hint" ], "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "integer" }, "scopes": { "type": "array", "items": { "type": "string" } }, "runtime_id": { "type": "string", "format": "uuid", "nullable": true }, "runtime_status": { "type": "string", "nullable": true }, "cli_hint": { "type": "string" } } }, "AutomationListResponse": { "type": "object", "required": [ "automations" ], "properties": { "automations": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationResponse" } } } }, "AutomationRunResponse": { "type": "object", "required": [ "id", "automation_id", "agent_id", "status", "started_at", "tokens_used", "cost_cents" ], "properties": { "id": { "type": "string", "format": "uuid" }, "automation_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "running", "success", "failed", "timed_out", "cancelled", "awaiting_approval" ] }, "step_results": { "nullable": true }, "error": { "type": "string", "nullable": true }, "trigger_source": { "type": "string", "nullable": true }, "context": { "type": "object", "additionalProperties": true, "nullable": true, "description": "JSONB context passed between workflow steps" }, "started_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": "string", "format": "date-time", "nullable": true }, "tokens_used": { "type": "integer" }, "cost_cents": { "type": "integer" } } }, "AutomationRunListResponse": { "type": "object", "required": [ "runs" ], "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationRunResponse" } } } }, "AutomationPresetsResponse": { "type": "object", "required": [ "presets" ], "properties": { "presets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "trigger_type": { "type": "string" }, "cron_expr": { "type": "string", "nullable": true }, "workflow_spec": { "type": "object", "additionalProperties": true } } } } } }, "CreateRuntimeRequest": { "type": "object", "required": [ "name", "agent_id" ], "properties": { "name": { "type": "string" }, "agent_id": { "type": "string", "format": "uuid" }, "template": { "type": "string" }, "preset": { "type": "string" }, "image": { "type": "string" }, "environment": { "type": "string", "description": "Vault environment to resolve env vars from (e.g. production, preview, development)" }, "env_public": { "type": "object", "additionalProperties": { "type": "string" } }, "idle_timeout_secs": { "type": "integer" }, "expose_http": { "type": "boolean", "default": false }, "http_port": { "type": "integer" }, "slug": { "type": "string" }, "inbound_auth": { "type": "string", "enum": [ "api_key", "jwt", "public" ] }, "shell_access_enabled": { "type": "boolean", "default": false }, "shell_auth_policy": { "type": "string", "description": "Step-up auth policy for shell (e.g. password, passkey, totp)" }, "shell_max_session_minutes": { "type": "integer" } } }, "UpdateRuntimeRequest": { "type": "object", "properties": { "name": { "type": "string" }, "template": { "type": "string" }, "preset": { "type": "string" }, "image": { "type": "string" }, "environment": { "type": "string", "description": "Vault environment to resolve env vars from" }, "env_public": { "type": "object", "additionalProperties": { "type": "string" } }, "idle_timeout_secs": { "type": "integer" }, "expose_http": { "type": "boolean" }, "http_port": { "type": "integer" }, "slug": { "type": "string" }, "inbound_auth": { "type": "string", "enum": [ "api_key", "jwt", "public" ] }, "shell_access_enabled": { "type": "boolean" }, "shell_auth_policy": { "type": "string" }, "shell_max_session_minutes": { "type": "integer" } } }, "RuntimeResponse": { "type": "object", "required": [ "id", "name", "agent_id", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "agent_id": { "type": "string", "format": "uuid" }, "template": { "type": "string", "nullable": true }, "preset": { "type": "string", "nullable": true }, "provider": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "creating", "running", "stopping", "stopped", "failed", "deleting" ] }, "image": { "type": "string", "nullable": true }, "environment": { "type": "string", "nullable": true, "description": "Vault environment for env var resolution" }, "env_public": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true }, "idle_timeout_secs": { "type": "integer", "nullable": true }, "expose_http": { "type": "boolean", "nullable": true }, "slug": { "type": "string", "nullable": true }, "public_url": { "type": "string", "nullable": true }, "http_port": { "type": "integer", "nullable": true }, "inbound_auth": { "type": "string", "enum": [ "api_key", "jwt", "public" ], "nullable": true }, "shell_access_enabled": { "type": "boolean" }, "shell_auth_policy": { "type": "string" }, "shell_max_session_minutes": { "type": "integer" }, "monthly_hours_used": { "type": "number", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RuntimeListResponse": { "type": "object", "required": [ "runtimes" ], "properties": { "runtimes": { "type": "array", "items": { "$ref": "#/components/schemas/RuntimeResponse" } } } }, "SlugCheckResponse": { "type": "object", "required": [ "available", "slug" ], "properties": { "available": { "type": "boolean" }, "slug": { "type": "string" }, "reason": { "type": "string", "nullable": true } } }, "ShellSessionRequest": { "type": "object", "description": "Step-up credentials for an interactive shell session.\nProvide one of password, totp_code, passkey_credential, or reauth_token.\n", "properties": { "password": { "type": "string" }, "totp_code": { "type": "string" }, "passkey_credential": { "type": "object", "additionalProperties": true }, "reauth_token": { "type": "string", "description": "Single-use `rat_` token from POST /v1/auth/reauth (purpose runtime_shell)" } } }, "ShellSessionResponse": { "type": "object", "required": [ "session_token", "ws_url", "expires_in", "runtime_id", "max_session_minutes" ], "properties": { "session_token": { "type": "string" }, "ws_url": { "type": "string", "description": "WebSocket URL for the PTY terminal" }, "expires_in": { "type": "integer", "format": "int64" }, "runtime_id": { "type": "string", "format": "uuid" }, "max_session_minutes": { "type": "integer" } } }, "RuntimeChatRequest": { "type": "object", "description": "Chat with the agent inside a runtime. Provide `message` and/or\na full OpenAI-style `messages` array (ephemeral history).\n", "properties": { "message": { "type": "string", "description": "Latest user message" }, "messages": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "OpenAI chat messages (optional history)" }, "model": { "type": "string" }, "provider": { "type": "string" }, "stream": { "type": "boolean", "description": "Request SSE streaming (default true when Accept is text/event-stream)" } } }, "MemoryEntry": { "type": "object", "required": [ "id", "agent_id", "namespace", "key", "value", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "namespace": { "type": "string" }, "key": { "type": "string" }, "value": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "ttl_expires_at": { "type": "string", "format": "date-time", "nullable": true } } }, "PutMemoryRequest": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string" }, "ttl_seconds": { "type": "integer", "nullable": true } } }, "MemorySearchRequest": { "type": "object", "required": [ "namespace", "query" ], "properties": { "namespace": { "type": "string" }, "query": { "type": "string" }, "top_k": { "type": "integer", "default": 5 } } }, "MemorySearchResponse": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" }, "score": { "type": "number" }, "namespace": { "type": "string" } } } } } }, "MemoryNamespaceListResponse": { "type": "object", "required": [ "namespaces" ], "properties": { "namespaces": { "type": "array", "items": { "type": "string" } } } }, "MemoryEntryListResponse": { "type": "object", "required": [ "entries" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/MemoryEntry" } } } }, "AgentCardResponse": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "capabilities": { "type": "array", "items": { "type": "string" } }, "a2a_url": { "type": "string", "nullable": true }, "mcp_url": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } } } }, "DirectoryEntry": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "capabilities": { "type": "array", "items": { "type": "string" } }, "a2a_url": { "type": "string", "nullable": true }, "mcp_url": { "type": "string", "nullable": true }, "org_name": { "type": "string", "nullable": true } } }, "DirectoryResponse": { "type": "object", "required": [ "agents", "total", "page", "per_page" ], "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/DirectoryEntry" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "OrgDirectoryAgent": { "type": "object", "required": [ "id", "name", "intents_api_enabled", "execution_intents_enabled", "memory_enabled", "shroud_enabled" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "public_description": { "type": "string", "nullable": true }, "public_tags": { "type": "array", "items": { "type": "string" } }, "a2a_url": { "type": "string", "nullable": true }, "mcp_url": { "type": "string", "nullable": true }, "intents_api_enabled": { "type": "boolean" }, "execution_intents_enabled": { "type": "boolean" }, "memory_enabled": { "type": "boolean" }, "shroud_enabled": { "type": "boolean" } } }, "OrgDirectoryResponse": { "type": "object", "required": [ "agents", "total", "page", "page_size" ], "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/OrgDirectoryAgent" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "page_size": { "type": "integer" } } }, "UpdateDiscoveryRequest": { "type": "object", "properties": { "discoverable": { "type": "boolean" }, "public_description": { "type": "string" }, "public_tags": { "type": "array", "items": { "type": "string" } } } }, "SendChatMessageRequest": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" }, "conversation_id": { "type": "string", "format": "uuid" }, "mode": { "type": "string" }, "model": { "type": "string" }, "provider": { "type": "string" }, "system_prompt": { "type": "string" } } }, "ChatMessageResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "role": { "type": "string" }, "content": { "type": "string" }, "tool_calls": {}, "tool_results": {}, "tokens_prompt": { "type": "integer" }, "tokens_completion": { "type": "integer" }, "model": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "ChatConversationResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "mode": { "type": "string" }, "model": { "type": "string" }, "provider": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ChatConversationListResponse": { "type": "object", "properties": { "conversations": { "type": "array", "items": { "$ref": "#/components/schemas/ChatConversationResponse" } } } }, "ConversationDetailResponse": { "type": "object", "properties": { "conversation": { "$ref": "#/components/schemas/ChatConversationResponse" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChatMessageResponse" } } } }, "SendChatMessageResponse": { "type": "object", "properties": { "conversation_id": { "type": "string", "format": "uuid" }, "message": { "$ref": "#/components/schemas/ChatMessageResponse" } } }, "CreateChannelRequest": { "type": "object", "required": [ "channel_type", "config" ], "properties": { "channel_type": { "type": "string", "enum": [ "telegram", "whatsapp", "discord" ] }, "channel_name": { "type": "string" }, "config": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Platform-specific config.\nTelegram: { bot_token }.\nWhatsApp: { phone_number_id, access_token, verify_token }.\nDiscord: { bot_token, application_id }.\n" }, "slash_commands_enabled": { "type": "boolean", "description": "Enable Hermes-compatible slash commands on this channel. When true,\nmessages starting with `/` are handled before the LLM. Commands:\n/help, /new, /reset, /clear, /model, /mode, /personality, /retry,\n/undo, /compress, /summarize, /stop, /status, /skills, /usage, /sethome.\n" }, "voice_transcription_enabled": { "type": "boolean", "description": "Enable voice message transcription" }, "sender_allowlist": { "type": "array", "items": { "type": "string" }, "description": "List of allowed sender IDs" }, "auto_respond_enabled": { "type": "boolean", "description": "Enable auto-respond" } } }, "UpdateChannelRequest": { "type": "object", "properties": { "channel_name": { "type": "string" }, "is_active": { "type": "boolean" }, "config": { "type": "object", "additionalProperties": { "type": "string" } }, "slash_commands_enabled": { "type": "boolean" }, "voice_transcription_enabled": { "type": "boolean" }, "sender_allowlist": { "type": "array", "items": { "type": "string" } }, "auto_respond_enabled": { "type": "boolean" } } }, "ChannelResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "channel_type": { "type": "string", "enum": [ "telegram", "whatsapp", "discord" ] }, "channel_name": { "type": "string" }, "webhook_path": { "type": "string" }, "webhook_url": { "type": "string" }, "is_active": { "type": "boolean" }, "config": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Channel-specific configuration JSON. May include:\n- sender_allowlist (array of strings): restrict which external senders can trigger the agent\n- auto_respond_enabled (boolean): whether the agent auto-responds to inbound messages\n" }, "slash_commands_enabled": { "type": "boolean", "description": "Whether Hermes-compatible slash commands are enabled for this channel.\nCommands: /help, /new, /reset, /clear, /model, /mode, /personality, /retry,\n/undo, /compress, /summarize, /stop, /status, /skills, /usage, /sethome.\n" }, "voice_transcription_enabled": { "type": "boolean", "description": "Whether voice message transcription is enabled" }, "unified_conversation_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID linking this channel to a unified cross-platform conversation" }, "is_home_platform": { "type": "boolean", "description": "Whether this is the agent's home platform channel" }, "sender_allowlist": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "List of allowed sender IDs for auto-respond" }, "auto_respond_enabled": { "type": "boolean", "description": "Whether auto-respond is enabled for this channel" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ChannelListResponse": { "type": "object", "properties": { "channels": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelResponse" } } } }, "SendChannelMessageRequest": { "type": "object", "required": [ "external_chat_id", "content" ], "properties": { "external_chat_id": { "type": "string", "description": "External platform chat/user ID" }, "content": { "type": "string" }, "reply_to": { "type": "string", "description": "External message ID to reply to" } } }, "ChannelMessageResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "channel_id": { "type": "string", "format": "uuid" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "external_chat_id": { "type": "string" }, "external_message_id": { "type": "string" }, "sender_name": { "type": "string" }, "content": { "type": "string" }, "media_url": { "type": "string" }, "is_voice_message": { "type": "boolean", "description": "Whether this message was a voice message" }, "voice_file_id": { "type": "string", "nullable": true, "description": "Telegram voice file ID" }, "voice_duration_secs": { "type": "integer", "nullable": true, "description": "Duration of voice message in seconds" }, "transcription_status": { "type": "string", "nullable": true, "enum": [ "pending", "completed", "failed" ], "description": "Status of voice transcription" }, "created_at": { "type": "string", "format": "date-time" } } }, "ChannelMessageListResponse": { "type": "object", "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelMessageResponse" } } } }, "OAuthProviderScope": { "type": "object", "properties": { "scope": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" }, "default": { "type": "boolean" } } }, "OAuthProvider": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique provider identifier (e.g. \"github\", \"google\", \"slack\")" }, "display_name": { "type": "string" }, "icon_url": { "type": "string", "format": "uri" }, "authorization_url": { "type": "string", "format": "uri" }, "token_url": { "type": "string", "format": "uri" }, "scopes_available": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthProviderScope" } }, "default_scopes": { "type": "array", "items": { "type": "string" } }, "extra_auth_params": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true }, "requires_app_credentials": { "type": "boolean", "description": "Whether custom app credentials are required (vs. shared 1Claw app)" }, "documentation_url": { "type": "string", "format": "uri", "nullable": true } } }, "OAuthProviderListResponse": { "type": "object", "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthProvider" } } } }, "ConnectOAuthRequest": { "type": "object", "required": [ "provider_slug" ], "properties": { "provider_slug": { "type": "string", "description": "Provider to connect (e.g. \"github\", \"google\", \"slack\")" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Override default scopes for this connection" }, "redirect_after": { "type": "string", "description": "URL to redirect to after the OAuth flow completes" } } }, "ConnectOAuthResponse": { "type": "object", "properties": { "authorization_url": { "type": "string", "format": "uri", "description": "Redirect the user to this URL to authorize the connection" } } }, "OAuthConnectionResponse": { "type": "object", "properties": { "binding_id": { "type": "string", "format": "uuid" }, "provider_slug": { "type": "string" }, "provider_name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] }, "needs_reauth": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "OAuthConnectionListResponse": { "type": "object", "properties": { "connections": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthConnectionResponse" } } } }, "SaveOAuthAppCredentialsRequest": { "type": "object", "required": [ "provider_slug", "client_id", "client_secret" ], "properties": { "provider_slug": { "type": "string", "description": "Provider this credential is for" }, "client_id": { "type": "string" }, "client_secret": { "type": "string", "description": "Write-only; never returned in responses" }, "redirect_uri": { "type": "string", "format": "uri", "description": "Custom redirect URI override" } } }, "OAuthAppCredentialResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "provider_slug": { "type": "string" }, "client_id": { "type": "string" }, "redirect_uri": { "type": "string", "format": "uri", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "OAuthAppCredentialListResponse": { "type": "object", "properties": { "credentials": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthAppCredentialResponse" } } } }, "ImportKeyRequest": { "type": "object", "required": [ "private_key" ], "properties": { "private_key": { "type": "string", "description": "The private key to import" }, "format": { "type": "string", "enum": [ "hex", "base64", "wif" ], "description": "Key format (default hex)" } } }, "CreateCedarPolicyRequest": { "type": "object", "required": [ "name", "cedar_text" ], "properties": { "name": { "type": "string" }, "cedar_text": { "type": "string", "description": "Cedar policy text" } } }, "CedarPolicyResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "cedar_text": { "type": "string" }, "is_active": { "type": "boolean" }, "enforcement_status": { "type": "string", "enum": [ "shadow", "enforce", "inactive" ], "description": "Dynamic status from org policy backend config" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CedarPolicyListResponse": { "type": "object", "properties": { "policies": { "type": "array", "items": { "$ref": "#/components/schemas/CedarPolicyResponse" } } } }, "CedarPolicyTestRequest": { "type": "object", "required": [ "principal_type", "principal_id", "action", "resource_path", "vault_id" ], "properties": { "cedar_text": { "type": "string", "description": "Optional inline Cedar text to test" }, "principal_type": { "type": "string" }, "principal_id": { "type": "string", "format": "uuid" }, "action": { "type": "string" }, "resource_path": { "type": "string" }, "vault_id": { "type": "string", "format": "uuid" }, "context": { "type": "object" } } }, "CedarPolicyTestResponse": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "allow", "deny" ] }, "backend": { "type": "string" }, "enforcement_status": { "type": "string", "enum": [ "shadow", "enforce", "inactive" ] }, "note": { "type": "string" } } }, "CreateOpaPolicyRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "rego_source": { "type": "string", "description": "OPA Rego module source" }, "wasm_bundle_base64": { "type": "string", "description": "Optional WASM bundle (base64)" }, "entrypoint": { "type": "string", "default": "oneclaw/allow" } } }, "OpaPolicyResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "rego_source": { "type": "string" }, "has_wasm_bundle": { "type": "boolean" }, "entrypoint": { "type": "string" }, "is_active": { "type": "boolean" }, "enforcement_status": { "type": "string", "enum": [ "shadow", "enforce", "inactive" ] }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "OpaPolicyListResponse": { "type": "object", "properties": { "policies": { "type": "array", "items": { "$ref": "#/components/schemas/OpaPolicyResponse" } } } }, "OpaPolicyTestRequest": { "type": "object", "required": [ "principal_type", "principal_id", "action", "resource_path", "vault_id" ], "properties": { "principal_type": { "type": "string" }, "principal_id": { "type": "string", "format": "uuid" }, "action": { "type": "string" }, "resource_path": { "type": "string" }, "vault_id": { "type": "string", "format": "uuid" }, "context": { "type": "object" } } }, "OpaPolicyTestResponse": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "allow", "deny" ] }, "backend": { "type": "string" }, "enforcement_status": { "type": "string", "enum": [ "shadow", "enforce", "inactive" ] }, "note": { "type": "string" } } }, "PolicyBackendSettingsResponse": { "type": "object", "properties": { "backend": { "type": "string", "enum": [ "builtin", "cedar", "opa", "builtin+cedar", "builtin+opa" ] }, "mode": { "type": "string", "enum": [ "shadow", "enforce" ] }, "scope": { "type": "array", "items": { "type": "string" } }, "breaker_behavior": { "type": "string", "enum": [ "fail_closed", "fail_open_builtin" ] }, "policy_version": { "type": "integer", "format": "int64" } } }, "UpdatePolicyBackendSettingsRequest": { "type": "object", "properties": { "backend": { "type": "string", "enum": [ "builtin", "cedar", "opa", "builtin+cedar", "builtin+opa" ] }, "mode": { "type": "string", "enum": [ "shadow", "enforce" ] }, "scope": { "type": "array", "items": { "type": "string" } }, "breaker_behavior": { "type": "string", "enum": [ "fail_closed", "fail_open_builtin" ] } } }, "PolicyShadowReportResponse": { "type": "object", "properties": { "total_evaluated": { "type": "integer", "format": "int64" }, "total_divergences": { "type": "integer", "format": "int64" }, "total_errors": { "type": "integer", "format": "int64" }, "concordance_rate": { "type": "number", "format": "double" }, "sample_events": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyShadowEvent" } }, "period_start": { "type": "string", "format": "date-time" }, "period_end": { "type": "string", "format": "date-time" } } }, "PolicyShadowEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "backend": { "type": "string" }, "action": { "type": "string" }, "builtin_decision": { "type": "string" }, "backend_decision": { "type": "string" }, "divergent": { "type": "boolean" }, "sampled": { "type": "boolean" }, "eval_duration_ms": { "type": "integer" }, "error_text": { "type": "string" }, "caller_id": { "type": "string", "format": "uuid" }, "resource_path": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "GuardrailShadowReportResponse": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid" }, "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" }, "total_would_deny": { "type": "integer", "format": "int64" }, "by_reason": { "type": "array", "items": { "$ref": "#/components/schemas/GuardrailShadowReasonRow" } } } }, "GuardrailShadowReasonRow": { "type": "object", "properties": { "reason_code": { "type": "string" }, "would_deny_count": { "type": "integer", "format": "int64" }, "enforced_count": { "type": "integer", "format": "int64" } } }, "GuardrailRevisionListResponse": { "type": "object", "properties": { "revisions": { "type": "array", "items": { "$ref": "#/components/schemas/GuardrailRevisionRow" } } } }, "GuardrailRevisionRow": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "resource_type": { "type": "string", "enum": [ "agent", "binding" ] }, "resource_id": { "type": "string", "format": "uuid" }, "actor_id": { "type": "string", "format": "uuid" }, "before_json": { "type": "object", "additionalProperties": true }, "after_json": { "type": "object", "additionalProperties": true }, "change_kind": { "type": "string", "enum": [ "narrowing", "widening", "neutral" ] }, "approval_id": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "GuardrailReplayRequest": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 90 }, "draft_guardrails": { "type": "object", "additionalProperties": true }, "draft_approval_policy": { "type": "object", "additionalProperties": true } } }, "GuardrailReplayResponse": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid" }, "window_days": { "type": "integer", "format": "int64" }, "allowed": { "type": "integer", "format": "int64" }, "denied": { "type": "integer", "format": "int64" }, "would_require_approval": { "type": "integer", "format": "int64" }, "samples": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "AgentAccountListResponse": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/AgentAccountResponse" } } } }, "AgentAccountResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "chain": { "type": "string" }, "account_type": { "type": "string" }, "address": { "type": "string" }, "safe_version": { "type": "string" }, "modules_enabled": { "type": "array", "items": { "type": "string" } }, "deploy_status": { "type": "string" }, "cosign_enabled": { "type": "boolean" }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "MigrationPlanResponse": { "type": "object", "properties": { "agent_id": { "type": "string", "format": "uuid" }, "chain": { "type": "string" }, "safe_address": { "type": "string" }, "safe_version": { "type": "string" }, "modules": { "type": "array", "items": { "type": "string" } }, "eoa_address": { "type": "string" }, "sweep_instructions": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string" }, "action": { "type": "string" }, "note": { "type": "string" } } } }, "roles_config_hash": { "type": "string" }, "allowance_config_hash": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } }, "deploy_status": { "type": "string" } } }, "ProvisionAgentAccountRequest": { "type": "object", "required": [ "chain" ], "properties": { "chain": { "type": "string" }, "account_type": { "type": "string", "default": "eoa" }, "address": { "type": "string" } } }, "SafeModuleRegistryResponse": { "type": "object", "properties": { "chain": { "type": "string" }, "modules": { "type": "array", "items": { "$ref": "#/components/schemas/SafeModuleInfo" } } } }, "SafeModuleInfo": { "type": "object", "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "version": { "type": "string" } } }, "AllowanceReconcileReport": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid" }, "agents_checked": { "type": "integer" }, "compiled": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "drift_detected": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "onchain_sync": { "type": "string", "description": "counterfactual when on-chain broadcast is stubbed pre-audit" } } }, "NotImplementedResponse": { "type": "object", "required": [ "error", "phase", "message" ], "properties": { "error": { "type": "string" }, "phase": { "type": "string" }, "message": { "type": "string" } } }, "CreateContractAbiRequest": { "type": "object", "required": [ "chain", "contract_address", "abi_json" ], "properties": { "chain": { "type": "string" }, "contract_address": { "type": "string", "description": "Contract address, or Solana program id when interface_kind is solana_idl" }, "abi_json": { "description": "EVM ABI JSON array, or Solana IDL object when interface_kind is solana_idl", "oneOf": [ { "type": "array", "items": { "type": "object" } }, { "type": "object" } ] }, "name": { "type": "string" }, "description": { "type": "string" }, "token_decimals": { "type": "integer" }, "interface_kind": { "type": "string", "enum": [ "evm_abi", "solana_idl" ], "default": "evm_abi" } } }, "ContractAbiResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "chain": { "type": "string" }, "contract_address": { "type": "string" }, "abi_json": { "description": "EVM ABI JSON array, or Solana IDL object", "oneOf": [ { "type": "array", "items": { "type": "object" } }, { "type": "object" } ] }, "name": { "type": "string" }, "description": { "type": "string" }, "token_decimals": { "type": "integer" }, "interface_kind": { "type": "string", "enum": [ "evm_abi", "solana_idl" ], "default": "evm_abi" }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ContractAbiListResponse": { "type": "object", "properties": { "abis": { "type": "array", "items": { "$ref": "#/components/schemas/ContractAbiResponse" } } } }, "TxConditions": { "type": "object", "description": "Signing-time conditions on access policies (all tiers).\nIgnored on secret reads. Evaluated when a TransactionContext is present.\nFields are combined according to `match_mode` (default AND).\n", "additionalProperties": true, "properties": { "match_mode": { "type": "string", "enum": [ "all", "any" ], "default": "all", "description": "How individual condition fields are combined.\n\"all\" (default): every present field must match (AND).\n\"any\": at least one present field must match (OR).\n" }, "function_name_in": { "type": "array", "items": { "type": "string" } }, "function_selector_in": { "type": "array", "items": { "type": "string" } }, "erc20_amount_above": { "type": "string" }, "value_above": { "type": "string", "description": "Native value threshold in wei (arbitrary-precision string)" }, "eip712_primary_type_in": { "type": "array", "items": { "type": "string" }, "description": "Match EIP-712 typed_data primaryType (case-sensitive)" }, "eip712_verifying_contract_in": { "type": "array", "items": { "type": "string" }, "description": "Match EIP-712 domain.verifyingContract (case-insensitive)" }, "eip712_domain_name_in": { "type": "array", "items": { "type": "string" }, "description": "Match EIP-712 domain.name" }, "eip712_domain_chain_id_in": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "Match EIP-712 domain.chainId" }, "eip7702_authorized_addresses_in": { "type": "array", "items": { "type": "string" }, "description": "Match EIP-7702 authorization_list delegate addresses (case-insensitive)" }, "to_address_in": { "type": "array", "items": { "type": "string" } }, "chain_in": { "type": "array", "items": { "type": "string" } }, "intent_type_in": { "type": "array", "items": { "type": "string" } }, "decode_failed": { "type": "boolean" }, "program_id_in": { "type": "array", "items": { "type": "string" } }, "deep_inspect": { "type": "boolean", "default": false, "description": "When true, conditions are also evaluated against inner calls\nextracted from wrapper transactions (multicall, Safe execTransaction,\nERC-4337 handleOps). A match on any inner call counts as an overall match.\n" }, "expression": { "type": "string", "maxLength": 1024, "description": "Mini expression DSL for policy conditions (schema version 2+).\nReferences transaction context fields (chain, value_wei, to_address,\nfunction_selector, etc.) with boolean operators. Fail-closed on parse\nor evaluation errors. Example: `chain == 'ethereum' && value_wei > 1000000000000000000`\n" } } }, "ConsensusTrigger": { "type": "object", "required": [ "conditions", "approval" ], "properties": { "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/ConsensusCondition" } }, "approval": { "$ref": "#/components/schemas/ApprovalRequirement" }, "expiry_secs": { "type": "integer", "format": "int64", "default": 86400 }, "self_approval_allowed": { "type": "boolean", "default": false }, "skip_when": { "type": "array", "description": "When ALL conditions in ANY entry match, consensus is bypassed.\nUseful for exempting known-safe recipients or low-value transfers.\n", "items": { "$ref": "#/components/schemas/FlatConditionSet" } }, "require_when": { "type": "array", "description": "Consensus is ONLY required when at least one entry matches.\nIf set and none match, consensus is skipped entirely.\n", "items": { "$ref": "#/components/schemas/FlatConditionSet" } }, "deep_inspect": { "type": "boolean", "default": false, "description": "When true, also evaluate conditions against inner calls extracted\nfrom wrapper transactions (multicall, Safe execTransaction,\nERC-4337 handleOps).\n" } } }, "FlatConditionSet": { "type": "object", "description": "Flat condition set used by consensus composability. Each present field\nis AND-combined within the set. At least one field must be specified\n(unless `always` is true).\n", "additionalProperties": false, "properties": { "value_above": { "type": "string", "description": "Native value threshold in gwei (numeric string)" }, "chain_in": { "type": "array", "items": { "type": "string" } }, "to_address_in": { "type": "array", "items": { "type": "string" } }, "function_selector_in": { "type": "array", "items": { "type": "string" } }, "erc20_amount_above": { "type": "string", "description": "ERC-20 raw token amount threshold (numeric string)" }, "intent_type_in": { "type": "array", "items": { "type": "string" } }, "always": { "type": "boolean", "description": "When true, this entry always matches regardless of other fields" }, "action_in": { "type": "array", "items": { "type": "string" }, "description": "Control-plane actions to match (e.g. policy.create, signing_key.export)" }, "action_kind_in": { "type": "array", "items": { "type": "string" }, "description": "Version-agnostic action kind groups (e.g. signing_key.*, policy.*, member.*)\n" } } }, "TimeWindow": { "type": "object", "description": "Time window condition for policy evaluation. Used inside the policy\n`conditions` JSON to restrict when the policy is active.\n", "properties": { "start_hour": { "type": "integer", "minimum": 0, "maximum": 23 }, "end_hour": { "type": "integer", "minimum": 0, "maximum": 24 }, "days_of_week": { "type": "array", "description": "Days when policy is active (0=Sunday, 6=Saturday)", "items": { "type": "integer", "minimum": 0, "maximum": 6 } }, "timezone": { "type": "string", "description": "IANA timezone identifier (e.g. \"America/New_York\"). Defaults to UTC." }, "cron_expr": { "type": "string", "description": "Cron expression (6-field with seconds) for fine-grained scheduling." } } }, "ConsensusCondition": { "oneOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "value_above" ] }, "threshold_wei": { "type": "string", "description": "Value threshold in wei (arbitrary-precision string). Preferred over threshold_gwei." }, "threshold_gwei": { "type": "integer", "format": "int64", "deprecated": true, "description": "Deprecated — use threshold_wei for arbitrary precision" } } }, { "type": "object", "required": [ "type", "chains" ], "properties": { "type": { "type": "string", "enum": [ "chain_in" ] }, "chains": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "required": [ "type", "addresses" ], "properties": { "type": { "type": "string", "enum": [ "to_address_in" ] }, "addresses": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "required": [ "type", "selectors" ], "properties": { "type": { "type": "string", "enum": [ "function_selector_in" ] }, "selectors": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "required": [ "type", "threshold_raw" ], "properties": { "type": { "type": "string", "enum": [ "erc20_amount_above" ] }, "threshold_raw": { "type": "string" } } }, { "type": "object", "required": [ "type", "intent_types" ], "properties": { "type": { "type": "string", "enum": [ "intent_type_in" ] }, "intent_types": { "type": "array", "items": { "type": "string" } } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "always" ] } } }, { "type": "object", "required": [ "type", "actions" ], "properties": { "type": { "type": "string", "enum": [ "action_in" ] }, "actions": { "type": "array", "items": { "type": "string" }, "description": "Control-plane actions to match, e.g. policy.create, policy.update,\npolicy.delete, signing_key.export, member.role_change, member.remove\n" } } }, { "type": "object", "required": [ "type", "action_kinds" ], "properties": { "type": { "type": "string", "enum": [ "action_kind_in" ] }, "action_kinds": { "type": "array", "items": { "type": "string" }, "description": "Version-agnostic action kind groups, e.g. signing_key.*, policy.*, member.*\n" } } } ] }, "ApprovalRequirement": { "type": "object", "required": [ "min_approvals" ], "properties": { "min_approvals": { "type": "integer" }, "required_roles": { "type": "array", "items": { "type": "string" } }, "per_role_minimums": { "type": "object", "additionalProperties": { "type": "integer" } }, "require_credential_types": { "type": "array", "items": { "type": "string", "enum": [ "password", "passkey", "totp", "biometric", "api_key" ] }, "description": "At least one approval must use one of these credential types" } } }, "SubmitPendingApprovalRequest": { "type": "object", "required": [ "policy_id", "action", "action_payload" ], "properties": { "policy_id": { "type": "string", "format": "uuid" }, "action": { "type": "string" }, "action_payload": { "type": "object" } } }, "SubmitPendingApprovalResponse": { "type": "object", "properties": { "pending_approval_id": { "type": "string", "format": "uuid" }, "required_approvals": { "type": "integer" }, "current_approvals": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "message": { "type": "string" } } }, "ApprovePendingApprovalRequest": { "type": "object", "required": [ "decision", "payload_hash" ], "properties": { "decision": { "type": "string", "enum": [ "approve", "reject" ] }, "payload_hash": { "type": "string" }, "reason": { "type": "string" }, "credential_type": { "type": "string", "enum": [ "password", "passkey", "totp", "biometric", "api_key" ], "description": "Authentication method used for this approval vote" } } }, "PendingApprovalResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "policy_id": { "type": "string", "format": "uuid" }, "action": { "type": "string" }, "action_payload": { "type": "object" }, "payload_hash": { "type": "string" }, "submitted_by": { "type": "string", "format": "uuid" }, "submitted_by_type": { "type": "string" }, "status": { "type": "string" }, "required_approvals": { "type": "integer" }, "current_approvals": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" }, "executed_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalSignatureResponse" } } } }, "ApprovalSignatureResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "approver_id": { "type": "string", "format": "uuid" }, "approver_type": { "type": "string" }, "decision": { "type": "string" }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "PendingApprovalListResponse": { "type": "object", "properties": { "pending_approvals": { "type": "array", "items": { "$ref": "#/components/schemas/PendingApprovalResponse" } }, "total": { "type": "integer", "format": "int64" } } }, "ExecutePendingApprovalResponse": { "type": "object", "properties": { "pending_approval_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "executed_at": { "type": "string", "format": "date-time" }, "result": { "type": "object" } } }, "CreateSubOrgRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "description": { "type": "string" }, "billing_model": { "type": "string", "enum": [ "inherit", "independent" ], "default": "inherit" } } }, "SubOrgResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "parent_org_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "billing_model": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "SubOrgListResponse": { "type": "object", "properties": { "sub_orgs": { "type": "array", "items": { "$ref": "#/components/schemas/SubOrgResponse" } } } }, "SubOrgPermissionRequest": { "type": "object", "required": [ "permission" ], "properties": { "permission": { "type": "string", "description": "Permission to grant (e.g. vaults:read, agents:write)" }, "resource_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "SubOrgAddUserRequest": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ], "default": "member" } } }, "SubOrgGenerateWalletsRequest": { "type": "object", "properties": { "chains": { "type": "array", "items": { "type": "string" } } } }, "PortfolioResponse": { "type": "object", "properties": { "wallets": { "type": "array", "items": { "$ref": "#/components/schemas/PortfolioWalletEntry" } }, "total_usd_estimate": { "type": "string" } } }, "PortfolioWalletEntry": { "type": "object", "properties": { "wallet_type": { "type": "string", "enum": [ "treasury", "signing_key", "smart_account" ] }, "chain": { "type": "string" }, "address": { "type": "string" }, "native_balance": { "type": "string" }, "native_balance_usd": { "type": "string" }, "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/PortfolioTokenBalance" } } } }, "PortfolioTokenBalance": { "type": "object", "properties": { "contract_address": { "type": "string" }, "symbol": { "type": "string" }, "name": { "type": "string" }, "balance": { "type": "string" }, "balance_usd": { "type": "string" }, "decimals": { "type": "integer" } } }, "ImportSmartAccountRequest": { "type": "object", "required": [ "chain", "chain_id", "safe_address" ], "properties": { "chain": { "type": "string" }, "chain_id": { "type": "integer" }, "safe_address": { "type": "string" }, "verify": { "type": "boolean", "default": true, "description": "Verify on-chain Safe ownership" } } }, "ImportSmartAccountResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agent_id": { "type": "string", "format": "uuid" }, "chain": { "type": "string" }, "chain_id": { "type": "integer" }, "safe_address": { "type": "string" }, "nonce": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "EnvVar": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "environments": { "type": "array", "items": { "type": "string" } }, "git_branch": { "type": "string", "nullable": true }, "sensitive": { "type": "boolean" }, "comment": { "type": "string", "nullable": true }, "value": { "type": "string", "nullable": true, "description": "Null for sensitive vars in list responses" }, "version": { "type": "integer" }, "created_by": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CreateEnvVarRequest": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "description": "Uppercase alphanumeric + underscore, 1-256 chars" }, "value": { "type": "string" }, "environments": { "type": "array", "items": { "type": "string" }, "default": [ "production", "preview", "development" ] }, "git_branch": { "type": "string", "description": "Branch override (preview only)" }, "sensitive": { "type": "boolean", "default": false }, "comment": { "type": "string" } } }, "UpdateEnvVarRequest": { "type": "object", "properties": { "value": { "type": "string" }, "environments": { "type": "array", "items": { "type": "string" } }, "sensitive": { "type": "boolean" }, "comment": { "type": "string" } } }, "ResolveEnvVarsResponse": { "type": "object", "properties": { "vars": { "type": "object", "additionalProperties": { "type": "string" } }, "sources": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "shared", "vault", "branch_override" ] } }, "environment": { "type": "string" }, "git_branch": { "type": "string", "nullable": true }, "resolved_at": { "type": "string", "format": "date-time" } } }, "VaultEnvironment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_builtin": { "type": "boolean" }, "copied_from": { "type": "string", "nullable": true }, "is_detached": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "CreateEnvironmentRequest": { "type": "object", "required": [ "slug" ], "properties": { "slug": { "type": "string", "description": "Lowercase alphanumeric + hyphens, 2-30 chars" }, "description": { "type": "string" }, "copy_from": { "type": "string", "description": "Copy env vars from this environment" } } }, "OrgEnvVar": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "environments": { "type": "array", "items": { "type": "string" } }, "sensitive": { "type": "boolean" }, "comment": { "type": "string", "nullable": true }, "value": { "type": "string", "nullable": true }, "version": { "type": "integer" }, "linked_vaults": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CreateOrgEnvVarRequest": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "type": "string" }, "environments": { "type": "array", "items": { "type": "string" }, "default": [ "production", "preview", "development" ] }, "sensitive": { "type": "boolean", "default": false }, "comment": { "type": "string" } } }, "UpdateOrgEnvVarRequest": { "type": "object", "properties": { "value": { "type": "string" }, "environments": { "type": "array", "items": { "type": "string" } }, "comment": { "type": "string" } } }, "CreateWalletAccessPolicyRequest": { "type": "object", "required": [ "scope_type", "principal_type", "principal_id" ], "properties": { "scope_type": { "type": "string", "enum": [ "wallet", "platform_app", "org" ], "description": "Policy scope — org-wide, platform app, or single wallet" }, "scope_id": { "type": "string", "format": "uuid", "nullable": true, "description": "Wallet or platform app UUID when scope_type is not org" }, "principal_type": { "type": "string", "enum": [ "user", "agent", "role", "platform_app" ], "description": "Who receives the grant" }, "principal_id": { "type": "string", "description": "User/agent UUID, role name, or platform app UUID" }, "can_sign": { "type": "boolean", "default": false }, "can_view_balance": { "type": "boolean", "default": true }, "can_export": { "type": "boolean", "default": false }, "can_send": { "type": "boolean", "default": false }, "can_swap": { "type": "boolean", "default": false }, "allowed_chains": { "type": "array", "items": { "type": "string" }, "description": "Chains this policy applies to (empty = all)" }, "max_value_per_tx_eth": { "type": "string", "description": "Max value per transaction in ETH" }, "daily_limit_eth": { "type": "string", "description": "Daily spend limit in ETH" }, "conditions": { "type": "object", "description": "Additional JSON conditions (reserved for future enforcement)" }, "expires_at": { "type": "string", "format": "date-time" } } }, "WalletAccessPolicyResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "org_id": { "type": "string", "format": "uuid" }, "scope_type": { "type": "string" }, "scope_id": { "type": "string", "format": "uuid", "nullable": true }, "principal_type": { "type": "string" }, "principal_id": { "type": "string" }, "can_sign": { "type": "boolean" }, "can_view_balance": { "type": "boolean" }, "can_export": { "type": "boolean" }, "can_send": { "type": "boolean" }, "can_swap": { "type": "boolean" }, "allowed_chains": { "type": "array", "items": { "type": "string" } }, "max_value_per_tx_eth": { "type": "string", "nullable": true }, "daily_limit_eth": { "type": "string", "nullable": true }, "conditions": { "type": "object" }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_by": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WalletAccessPolicyListResponse": { "type": "object", "properties": { "policies": { "type": "array", "items": { "$ref": "#/components/schemas/WalletAccessPolicyResponse" } } } }, "CredentialRecoveryRequest": { "type": "object", "required": [ "recovery_type" ], "properties": { "recovery_type": { "type": "string", "enum": [ "mfa_reset", "passkey_reset", "password_reset" ] }, "reason": { "type": "string", "description": "Optional justification for the recovery request" } } }, "CredentialRecoveryResponse": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending_approval", "approved", "rejected", "expired" ] }, "recovery_type": { "type": "string", "enum": [ "mfa_reset", "passkey_reset", "password_reset" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "CredentialRecoveryListResponse": { "type": "object", "properties": { "requests": { "type": "array", "items": { "$ref": "#/components/schemas/CredentialRecoveryResponse" } } } }, "CredentialRecoveryApproveResponse": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "approved" ] }, "recovery_code": { "type": "string", "nullable": true, "description": "One-time recovery code (only present for certain recovery types)" } } }, "CredentialRecoveryExecuteResponse": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "executed" ] }, "recovery_type": { "type": "string" }, "executed_at": { "type": "string", "format": "date-time" } } }, "CredentialRecoveryPolicyResponse": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "require_admin_approval": { "type": "boolean" }, "delay_hours": { "type": "integer", "description": "Waiting period before recovery takes effect" }, "allowed_types": { "type": "array", "items": { "type": "string", "enum": [ "mfa_reset", "passkey_reset", "password_reset" ] } } } }, "CredentialRecoveryPolicyRequest": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "require_admin_approval": { "type": "boolean" }, "delay_hours": { "type": "integer" }, "allowed_types": { "type": "array", "items": { "type": "string", "enum": [ "mfa_reset", "passkey_reset", "password_reset" ] } } } }, "ShamirKekSetupRequest": { "type": "object", "required": [ "threshold", "total_shares", "custodian_emails" ], "properties": { "threshold": { "type": "integer", "enum": [ 2, 3 ], "description": "Minimum shares required to reconstruct the KEK" }, "total_shares": { "type": "integer", "enum": [ 3, 5 ], "description": "Total number of shares to generate" }, "custodian_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Email addresses of share custodians" } } }, "ShamirKekSetupResponse": { "type": "object", "properties": { "kek_id": { "type": "string" }, "threshold": { "type": "integer" }, "total_shares": { "type": "integer" }, "shares": { "type": "array", "description": "One-time share distribution (never returned again)", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "custodian_email": { "type": "string", "format": "email" }, "share_b64": { "type": "string", "description": "Base64-encoded share" } } } }, "custody_mode": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "ShamirKekStatusResponse": { "type": "object", "properties": { "configured": { "type": "boolean" }, "kek_id": { "type": "string", "nullable": true }, "threshold": { "type": "integer", "nullable": true }, "total_shares": { "type": "integer", "nullable": true }, "custody_mode": { "type": "string", "nullable": true }, "custodians": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "share_provided": { "type": "boolean" } } } }, "created_at": { "type": "string", "format": "date-time", "nullable": true } } }, "ShamirKekReconstructRequest": { "type": "object", "required": [ "shares" ], "properties": { "shares": { "type": "array", "items": { "type": "object", "required": [ "index", "share_b64" ], "properties": { "index": { "type": "integer" }, "share_b64": { "type": "string", "description": "Base64-encoded share" } } } } } }, "ShamirKekReconstructResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "accepted", "reconstructed" ] }, "message": { "type": "string" } } }, "ShamirKekRecoveryCodesResponse": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "string" } } } }, "ShamirKekVerifyCodeRequest": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } }, "ShamirKekVerifyCodeResponse": { "type": "object", "properties": { "valid": { "type": "boolean" } } } } } }