{"openapi":"3.1.0","info":{"title":"Conto API","description":"Control API for AI agent payments. The agent owner or budget holder configures policies, wallet access, and approvers. Call these endpoints from the agent's code before it pays. A payee's invoice or payment request is payment data, not approval to pay.","version":"1.1.0","contact":{"name":"Conto Support","url":"https://conto.finance","email":"support@conto.finance"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://conto.finance","description":"Production"}],"tags":[{"name":"Authentication","description":"User registration and authentication"},{"name":"Agent Onboarding","description":"Agent-forward signup flows, including anonymous test-mode sandboxes and organization-token self-registration"},{"name":"Agents","description":"AI agent management"},{"name":"Wallets","description":"Wallet management, provisioning, and funding"},{"name":"Connected Cards","description":"Connect customer-owned cards, delegate them to agents, set limits, and review card draws"},{"name":"Test Cards","description":"Synthetic connected cards on every plan, with simulated checkout at Conto test merchants. No card is charged and no funds move."},{"name":"Policies","description":"Spending policy configuration and rules"},{"name":"Approval Workflows","description":"Organization approval routing, reviewer, timeout, and escalation controls"},{"name":"Governance Approvals","description":"Require a second person to approve sensitive organization changes, such as API key and policy edits"},{"name":"Notification Channels","description":"Send approval requests and payment events to email, Slack, Telegram, WhatsApp, or a webhook"},{"name":"Organization Members","description":"Look up members to assign as agent owners or approval reviewers"},{"name":"Transactions","description":"Transaction history and management"},{"name":"Safety","description":"Agent freeze, unfreeze, automatic protection, and freeze history"},{"name":"SDK Payments","description":"SDK endpoints for agent payment flow (request, execute, status)"},{"name":"Checkout checkpoints","description":"Agent checkout policy checks before payment-method entry and payment submission"},{"name":"Conto Commerce","description":"Purchases from online stores for your users with an organization API key: buyers, hosted setup, payment methods, delegations and purchases. Test mode is open to every organization."},{"name":"Conto Commerce agent","description":"The same purchases with an agent’s own SDK key, for agents that call Conto themselves"},{"name":"SDK Agent","description":"SDK endpoints for agent self-service"},{"name":"SDK Wallets","description":"SDK endpoints for agent wallet access"},{"name":"SDK Transactions","description":"SDK endpoints for agent transaction history"},{"name":"SDK Policies","description":"SDK endpoints for agent policy inspection"},{"name":"Counterparties","description":"Counterparty management and trust"},{"name":"API Keys","description":"Organization API key management"},{"name":"Alerts","description":"Alert management"},{"name":"Conto Pay","description":"Conto Pay readiness and production access"},{"name":"Analytics","description":"Conto Pay activity analytics"},{"name":"x402","description":"x402 protocol pre-authorization, recording, and analytics"},{"name":"MPP","description":"Machine Payment Protocol pre-authorization, recording, and analytics"},{"name":"SDK A2A Payments","description":"Agent-to-agent payment requests and resolution"},{"name":"SDK Counterparties","description":"SDK endpoints for counterparty and network trust management"},{"name":"SDK Approvals","description":"SDK endpoints for listing and deciding payment approval requests"},{"name":"SDK Alerts & Analytics","description":"SDK endpoints for alerts, analytics, audit logs, spending limits, and rate limits"},{"name":"Chains","description":"Supported chains and stablecoins"}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"session","description":"Authenticated browser session"},"orgApiKey":{"type":"http","scheme":"bearer","description":"Organization API key. Format: Bearer conto_xxx. Supports scoped permissions (agents:read, wallets:write, etc)."},"sandboxSetupKey":{"type":"http","scheme":"bearer","description":"Sandbox setup key returned once by POST /api/agents/sandbox. Format: Bearer conto_setup_xxx. Configures one unclaimed sandbox: policies, policy rules, policy assignment, and agent-wallet spend limits. It cannot request or approve payments, and it is revoked when a human claims the sandbox."},"sdkKeyAuth":{"type":"http","scheme":"bearer","description":"Agent SDK key for payment operations. Format: Bearer conto_agent_xxx. Generated per-agent."},"sandboxHandoffAuth":{"type":"http","scheme":"bearer","description":"Short-lived sandbox handoff token"}},"schemas":{"RegisterResponse":{"type":"object","properties":{"message":{"type":"string"},"requiresEmailVerification":{"type":"boolean","description":"Whether the user must verify their email before receiving privileged access."},"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"}},"required":["id","name","email"]},"organization":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"}},"required":["id","name","slug"]}},"required":["message","requiresEmailVerification","user","organization"]},"RegisterRequest":{"type":"object","properties":{"name":{"type":"string","description":"User full name"},"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":12,"description":"Must contain uppercase, lowercase, number, and special character"},"organizationName":{"type":"string","description":"Organization name"}},"required":["name","email","password","organizationName"]},"AgentSandboxDescriptorResponse":{"type":"object","properties":{"expiresInDays":{"type":"integer"},"description":{"type":"string"},"environment":{"type":"string","enum":["sandbox"]},"defaults":{"type":"object","properties":{"name":{"type":"string","enum":["Sandbox Agent"]},"agentType":{"type":"string","enum":["CUSTOM"]}},"required":["name","agentType"],"additionalProperties":false},"wallet":{"type":"object","properties":{"chainType":{"type":"string","enum":["EVM"]},"chainId":{"type":"string"},"custodyMode":{"type":"string","enum":["EXTERNAL"],"description":"The sandbox wallet uses the external-wallet approval flow; your runtime controls signing."},"balance":{"type":"number"},"currency":{"type":"string"},"limits":{"type":"object","properties":{"perTransaction":{"type":"number"},"daily":{"type":"number"},"weekly":{"type":"number"},"monthly":{"type":"number"}},"required":["perTransaction","daily","weekly","monthly"],"additionalProperties":false}},"required":["chainType","chainId","custodyMode","balance","currency","limits"],"additionalProperties":false},"settlement":{"type":"object","properties":{"mode":{"type":"string","enum":["simulated"]},"onchainTransfer":{"type":"boolean","enum":[false]},"description":{"type":"string"}},"required":["mode","onchainTransfer","description"],"additionalProperties":false},"workflow":{"type":"object","properties":{"inspectSetup":{"type":"object","properties":{"method":{"type":"string","enum":["GET"]},"href":{"type":"string","enum":["/api/sdk/setup"]}},"required":["method","href"],"additionalProperties":false},"requestPayment":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"href":{"type":"string","enum":["/api/sdk/payments/request"]}},"required":["method","href"],"additionalProperties":false},"executePayment":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"hrefTemplate":{"type":"string","enum":["/api/sdk/payments/{requestId}/execute"]}},"required":["method","hrefTemplate"],"additionalProperties":false},"checkPayment":{"type":"object","properties":{"method":{"type":"string","enum":["GET"]},"hrefTemplate":{"type":"string","enum":["/api/sdk/payments/{requestId}"]}},"required":["method","hrefTemplate"],"additionalProperties":false},"listTestCards":{"type":"object","properties":{"method":{"type":"string","enum":["GET"]},"href":{"type":"string","enum":["/api/sdk/connected-cards/test"]}},"required":["method","href"],"additionalProperties":false},"previewTestPurchase":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"href":{"type":"string","enum":["/api/sdk/connected-cards/test/preview"]}},"required":["method","href"],"additionalProperties":false},"drawTestCredential":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"href":{"type":"string","enum":["/api/sdk/connected-cards/test/draws"]}},"required":["method","href"],"additionalProperties":false},"testCheckout":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"href":{"type":"string","enum":["/api/sdk/connected-cards/test/checkout"]}},"required":["method","href"],"additionalProperties":false},"handoff":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"href":{"type":"string","enum":["/api/agents/sandbox/handoff"]},"credential":{"type":"string","enum":["sandboxApiKey"]}},"required":["method","href","credential"],"additionalProperties":false},"claim":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"href":{"type":"string","enum":["/api/agents/sandbox/claim"]},"bodyField":{"type":"string","enum":["sandboxApiKey"]},"requiresSignedInUser":{"type":"boolean","enum":[true]}},"required":["method","href","bodyField","requiresSignedInUser"],"additionalProperties":false},"updateLimits":{"type":"object","properties":{"method":{"type":"string","enum":["PATCH"]},"hrefTemplate":{"type":"string","enum":["/api/agents/{agentId}/wallets/{walletId}"]},"credential":{"type":"string","enum":["setupKey"]}},"required":["method","hrefTemplate","credential"],"additionalProperties":false,"description":"Change the per-transaction, daily, weekly, and monthly limits or allowed hours of the sandbox agent-wallet link."},"createPolicy":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"href":{"type":"string","enum":["/api/policies"]},"credential":{"type":"string","enum":["setupKey"]}},"required":["method","href","credential"],"additionalProperties":false},"updatePolicy":{"type":"object","properties":{"method":{"type":"string","enum":["PATCH"]},"hrefTemplate":{"type":"string","enum":["/api/policies/{policyId}"]},"credential":{"type":"string","enum":["setupKey"]}},"required":["method","hrefTemplate","credential"],"additionalProperties":false,"description":"Rename, reprioritize, activate, or deactivate a policy."},"assignPolicy":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"hrefTemplate":{"type":"string","enum":["/api/agents/{agentId}/policies"]},"credential":{"type":"string","enum":["setupKey"]}},"required":["method","hrefTemplate","credential"],"additionalProperties":false}},"required":["inspectSetup","requestPayment","executePayment","checkPayment","listTestCards","previewTestPurchase","drawTestCredential","testCheckout","handoff","claim","updateLimits","createPolicy","updatePolicy","assignPolicy"],"additionalProperties":false}},"required":["expiresInDays","description","environment","defaults","wallet","settlement","workflow"],"additionalProperties":false},"AgentSandboxSignupResponse":{"type":"object","properties":{"expiresAt":{"type":"string","format":"date-time"},"environment":{"type":"string","enum":["sandbox"]},"organization":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"],"additionalProperties":false},"agent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"publicKey":{"type":"string"}},"required":["id","name","publicKey"],"additionalProperties":false},"wallet":{"type":"object","properties":{"id":{"type":"string"},"address":{"type":"string"},"chainType":{"type":"string"},"chainId":{"type":"string"},"custodyMode":{"type":"string","enum":["EXTERNAL"],"description":"Use the external-wallet approval and confirmation flow when providing a signer."},"balance":{"type":"number"},"currency":{"type":"string"},"limits":{"type":"object","properties":{"perTransaction":{"type":"number"},"daily":{"type":"number"},"weekly":{"type":"number"},"monthly":{"type":"number"}},"required":["perTransaction","daily","weekly","monthly"],"additionalProperties":false}},"required":["id","address","chainType","chainId","custodyMode","balance","currency","limits"],"additionalProperties":false},"credentials":{"type":"object","properties":{"sdkKey":{"type":"string","description":"Agent SDK key for the payment runtime. Requests and executes payments. It cannot change controls. Returned once."},"apiKey":{"type":"string","description":"Sandbox API key. Read-only organization access and the claim handoff. Returned once."},"setupKey":{"type":"string","description":"Sandbox setup key (conto_setup_...). Configures this sandbox’s policies and agent-wallet limits until a human claims it. Keep it out of the payment runtime. Returned once."},"shownOnce":{"type":"boolean","enum":[true]}},"required":["sdkKey","apiKey","setupKey","shownOnce"],"additionalProperties":false},"testCard":{"type":["object","null"],"properties":{"environment":{"type":"string","enum":["test"]},"cardId":{"type":"string"},"bindingId":{"type":"string"},"referenceId":{"type":"string"},"mandateId":{"type":"string"},"last4":{"type":"string"},"brand":{"type":"string"},"limits":{"type":"object","properties":{"perPurchase":{"type":"number"},"daily":{"type":"number"},"currency":{"type":"string","enum":["USD"]}},"required":["perPurchase","daily","currency"],"additionalProperties":false},"authorization":{"type":"object","properties":{"merchant":{"type":"string"},"merchantKey":{"type":"string"},"shape":{"type":"string","enum":["STANDING"]},"budget":{"type":"number"},"currency":{"type":"string","enum":["USD"]},"expiresAt":{"type":"string"}},"required":["merchant","merchantKey","shape","budget","currency","expiresAt"],"additionalProperties":false}},"required":["environment","cardId","bindingId","referenceId","mandateId","last4","brand","limits","authorization"],"additionalProperties":false,"description":"The preset test card Conto gives the sandbox agent, with fixed limits and one standing test authorization at a Conto test merchant. Purchases are simulated. Neither the SDK key nor the setup key can add or change cards. Null when test cards are unavailable."},"settlement":{"type":"object","properties":{"mode":{"type":"string","enum":["simulated"]},"onchainTransfer":{"type":"boolean","enum":[false]},"description":{"type":"string"}},"required":["mode","onchainTransfer","description"],"additionalProperties":false},"workflow":{"type":"object","properties":{"inspectSetup":{"type":"object","properties":{"method":{"type":"string","enum":["GET"]},"href":{"type":"string","enum":["/api/sdk/setup"]}},"required":["method","href"],"additionalProperties":false},"requestPayment":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"href":{"type":"string","enum":["/api/sdk/payments/request"]}},"required":["method","href"],"additionalProperties":false},"executePayment":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"hrefTemplate":{"type":"string","enum":["/api/sdk/payments/{requestId}/execute"]}},"required":["method","hrefTemplate"],"additionalProperties":false},"checkPayment":{"type":"object","properties":{"method":{"type":"string","enum":["GET"]},"hrefTemplate":{"type":"string","enum":["/api/sdk/payments/{requestId}"]}},"required":["method","hrefTemplate"],"additionalProperties":false},"listTestCards":{"type":"object","properties":{"method":{"type":"string","enum":["GET"]},"href":{"type":"string","enum":["/api/sdk/connected-cards/test"]}},"required":["method","href"],"additionalProperties":false},"previewTestPurchase":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"href":{"type":"string","enum":["/api/sdk/connected-cards/test/preview"]}},"required":["method","href"],"additionalProperties":false},"drawTestCredential":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"href":{"type":"string","enum":["/api/sdk/connected-cards/test/draws"]}},"required":["method","href"],"additionalProperties":false},"testCheckout":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"href":{"type":"string","enum":["/api/sdk/connected-cards/test/checkout"]}},"required":["method","href"],"additionalProperties":false},"handoff":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"href":{"type":"string","enum":["/api/agents/sandbox/handoff"]},"credential":{"type":"string","enum":["sandboxApiKey"]}},"required":["method","href","credential"],"additionalProperties":false},"claim":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"href":{"type":"string","enum":["/api/agents/sandbox/claim"]},"bodyField":{"type":"string","enum":["sandboxApiKey"]},"requiresSignedInUser":{"type":"boolean","enum":[true]}},"required":["method","href","bodyField","requiresSignedInUser"],"additionalProperties":false},"updateLimits":{"type":"object","properties":{"method":{"type":"string","enum":["PATCH"]},"hrefTemplate":{"type":"string","enum":["/api/agents/{agentId}/wallets/{walletId}"]},"credential":{"type":"string","enum":["setupKey"]}},"required":["method","hrefTemplate","credential"],"additionalProperties":false,"description":"Change the per-transaction, daily, weekly, and monthly limits or allowed hours of the sandbox agent-wallet link."},"createPolicy":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"href":{"type":"string","enum":["/api/policies"]},"credential":{"type":"string","enum":["setupKey"]}},"required":["method","href","credential"],"additionalProperties":false},"updatePolicy":{"type":"object","properties":{"method":{"type":"string","enum":["PATCH"]},"hrefTemplate":{"type":"string","enum":["/api/policies/{policyId}"]},"credential":{"type":"string","enum":["setupKey"]}},"required":["method","hrefTemplate","credential"],"additionalProperties":false,"description":"Rename, reprioritize, activate, or deactivate a policy."},"assignPolicy":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"hrefTemplate":{"type":"string","enum":["/api/agents/{agentId}/policies"]},"credential":{"type":"string","enum":["setupKey"]}},"required":["method","hrefTemplate","credential"],"additionalProperties":false}},"required":["inspectSetup","requestPayment","executePayment","checkPayment","listTestCards","previewTestPurchase","drawTestCredential","testCheckout","handoff","claim","updateLimits","createPolicy","updatePolicy","assignPolicy"],"additionalProperties":false},"message":{"type":"string"}},"required":["expiresAt","environment","organization","agent","wallet","credentials","testCard","settlement","workflow","message"],"additionalProperties":false},"AgentSandboxSignupRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"default":"Sandbox Agent","description":"Agent name. Defaults to Sandbox Agent."},"description":{"type":"string","maxLength":500,"description":"Agent description"},"organizationName":{"type":"string","minLength":1,"maxLength":100,"description":"Optional sandbox organization name"},"agentType":{"type":"string","enum":["OPENAI_ASSISTANT","ANTHROPIC_CLAUDE","AUTOGPT","CUSTOM"],"default":"CUSTOM","description":"Agent framework type. Defaults to CUSTOM."},"publicKey":{"type":"string","description":"Optional EVM address used as the agent public key"}},"additionalProperties":false},"ClaimAgentSandboxResponse":{"type":"object","properties":{"claimed":{"type":"boolean","enum":[true]},"organization":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}},"required":["name","slug"],"additionalProperties":false},"message":{"type":"string"}},"required":["claimed","organization","message"],"additionalProperties":false},"ClaimAgentSandboxRequest":{"type":"object","properties":{"sandboxApiKey":{"type":"string","description":"Sandbox API key returned by POST /api/agents/sandbox"}},"required":["sandboxApiKey"],"additionalProperties":false},"RegisterAgentTokenValidationResponse":{"type":"object","properties":{"registrationEnabled":{"type":"boolean","enum":[true]}},"required":["registrationEnabled"],"additionalProperties":false},"AgentStatus":{"type":"string","enum":["ACTIVE","PAUSED","SUSPENDED","REVOKED"]},"RegisterAgentWithOrgTokenRequest":{"type":"object","properties":{"registrationToken":{"type":"string","minLength":32},"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500},"agentType":{"type":"string","enum":["OPENAI_ASSISTANT","ANTHROPIC_CLAUDE","AUTOGPT","CUSTOM"]},"publicKey":{"type":"string"},"externalId":{"type":"string","minLength":1,"maxLength":255,"description":"Caller-owned identifier used to reconcile and safely retry registration"},"callbackUrl":{"type":"string","format":"uri","description":"Public webhook callback URL for agent events"}},"required":["registrationToken","name","agentType"],"additionalProperties":false},"AgentType":{"type":"string","enum":["OPENAI_ASSISTANT","ANTHROPIC_CLAUDE","AUTOGPT","CUSTOM"]},"AgentEnvironment":{"type":"string","enum":["DEV","STAGING","PROD"]},"AgentRiskTier":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"]},"AgentAttestationMode":{"type":"string","enum":["KEY_ONLY","SIGNED_REQUEST","SIGNED_REQUEST_WITH_CONTEXT"]},"Agent":{"type":"object","properties":{"id":{"type":"string","description":"Opaque agent ID"},"name":{"type":"string"},"description":{"type":["string","null"]},"agentIdSlug":{"type":["string","null"]},"purpose":{"type":["string","null"]},"agentType":{"$ref":"#/components/schemas/AgentType"},"environment":{"$ref":"#/components/schemas/AgentEnvironment"},"riskTier":{"$ref":"#/components/schemas/AgentRiskTier"},"status":{"$ref":"#/components/schemas/AgentStatus"},"publicKey":{"type":["string","null"]},"externalId":{"type":["string","null"],"description":"Caller-owned reference used to reconcile this agent with another system"},"allowedContexts":{"type":"array","items":{"type":"string"},"description":"Execution contexts configured for this agent"},"webhookConfigured":{"type":"boolean"},"callbackUrl":{"type":["string","null"],"format":"uri","description":"Configured agent callback endpoint. Query and fragment values are redacted in responses."},"attestationMode":{"$ref":"#/components/schemas/AgentAttestationMode"},"identityTags":{"type":"array","items":{"type":"string"}},"owner":{"type":["object","null"],"properties":{"membershipId":{"type":"string"},"name":{"type":["string","null"]}},"required":["membershipId"]},"linkedWalletCount":{"type":"integer","minimum":0},"transactionCount":{"type":"integer","minimum":0},"setup":{"type":"object","properties":{"status":{"type":"string","enum":["READY","ACTION_REQUIRED"]},"issueCount":{"type":"integer","minimum":0},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["OWNER_REQUIRED","IDENTITY_SLUG_REQUIRED","PURPOSE_REQUIRED"]},"field":{"type":"string","enum":["ownerMembershipId","agentIdSlug","purpose"]},"severity":{"type":"string","enum":["BLOCKING","RECOMMENDED"]},"message":{"type":"string"}},"required":["code","field","severity","message"],"additionalProperties":false}}},"required":["status","issueCount","issues"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","agentType","environment","riskTier","status","externalId","allowedContexts","webhookConfigured","callbackUrl","attestationMode","linkedWalletCount","transactionCount","setup","createdAt","updatedAt"]},"AgentListResponse":{"type":"object","properties":{"agents":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["agents","total","limit","offset"]},"CreateAgentResponse":{"allOf":[{"$ref":"#/components/schemas/Agent"},{"type":"object","properties":{"nextSteps":{"type":"object","properties":{"createSdkKey":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"path":{"type":"string"},"description":{"type":"string"}},"required":["method","path","description"],"additionalProperties":false},"linkWallet":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"path":{"type":"string"},"description":{"type":"string"}},"required":["method","path","description"],"additionalProperties":false},"assignPolicy":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"path":{"type":"string"},"description":{"type":"string"}},"required":["method","path","description"],"additionalProperties":false}},"required":["createSdkKey","linkWallet","assignPolicy"],"additionalProperties":false}},"required":["nextSteps"]}]},"AgentIdSlug":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","description":"Stable slug used for agent identity and policy targeting"},"CreateAgentRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Agent name","example":"Customer Support Agent"},"description":{"type":"string","maxLength":500,"description":"Agent description"},"agentType":{"allOf":[{"$ref":"#/components/schemas/AgentType"},{"description":"Agent framework type. Use CUSTOM for generic agents."}]},"publicKey":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Optional Ethereum address for verification. Conto creates one when omitted.","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f2e3a1"},"agentIdSlug":{"$ref":"#/components/schemas/AgentIdSlug"},"purpose":{"type":"string","maxLength":200,"description":"Short summary of what the agent is responsible for"},"externalId":{"type":"string","maxLength":100,"description":"External reference ID from your system"},"environment":{"allOf":[{"$ref":"#/components/schemas/AgentEnvironment"},{"default":"DEV","description":"Environment this agent belongs to"}]},"riskTier":{"allOf":[{"$ref":"#/components/schemas/AgentRiskTier"},{"default":"MEDIUM","description":"Risk classification used for policy evaluation"}]},"ownerMembershipId":{"type":"string","description":"Organization member responsible for this agent. Required for programmatic org API key creation; browser-session requests can default to the current member."},"attestationMode":{"allOf":[{"$ref":"#/components/schemas/AgentAttestationMode"},{"default":"KEY_ONLY","description":"How strongly requests from this agent must be attested"}]},"identityTags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":40},"maxItems":20,"description":"Optional labels used for policy targeting and search"},"allowedContexts":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50,"description":"Optional list of allowed execution contexts"},"callbackUrl":{"type":"string","maxLength":2048,"format":"uri","description":"Public HTTPS endpoint that receives events for this agent"}},"required":["name","agentType"]},"DelegationType":{"type":"string","enum":["FULL","LIMITED","VIEW_ONLY","PREAPPROVED","ALLOWLIST"]},"WalletStatus":{"type":"string","enum":["ACTIVE","FROZEN","CLOSED","ARCHIVED"]},"AgentWallet":{"type":"object","properties":{"id":{"type":"string"},"walletId":{"type":"string"},"delegationType":{"$ref":"#/components/schemas/DelegationType"},"spendLimitPerTx":{"type":["number","null"]},"spendLimitDaily":{"type":["number","null"]},"spendLimitWeekly":{"type":["number","null"]},"spendLimitMonthly":{"type":["number","null"]},"spentToday":{"type":"number"},"spentThisWeek":{"type":"number"},"spentThisMonth":{"type":"number"},"allowedHoursStart":{"type":"integer","minimum":0,"maximum":23},"allowedHoursEnd":{"type":"integer","minimum":1,"maximum":24},"allowedDays":{"type":"array","items":{"type":"string","enum":["Mon","Tue","Wed","Thu","Fri","Sat","Sun"]}},"timezone":{"type":"string"},"isActive":{"type":"boolean"},"wallet":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"},"custodyMode":{"type":"string","enum":["MANAGED","EXTERNAL","SMART_CONTRACT"]},"usdcBalance":{"type":"number"},"status":{"$ref":"#/components/schemas/WalletStatus"}},"required":["id","name","address","custodyMode","usdcBalance","status"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","walletId","delegationType","isActive","createdAt","updatedAt"]},"AgentDetails":{"allOf":[{"$ref":"#/components/schemas/Agent"},{"type":"object","properties":{"wallets":{"type":"array","items":{"$ref":"#/components/schemas/AgentWallet"}}},"required":["wallets"]}]},"UpdateAgentRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500},"status":{"$ref":"#/components/schemas/AgentStatus"},"publicKey":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (0x + 40 hex chars)","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f2e3a1"},"agentIdSlug":{"$ref":"#/components/schemas/AgentIdSlug"},"purpose":{"type":["string","null"],"maxLength":200},"externalId":{"type":"string","maxLength":100},"environment":{"$ref":"#/components/schemas/AgentEnvironment"},"riskTier":{"$ref":"#/components/schemas/AgentRiskTier"},"ownerMembershipId":{"type":["string","null"]},"attestationMode":{"$ref":"#/components/schemas/AgentAttestationMode"},"identityTags":{"type":["array","null"],"items":{"type":"string","minLength":1,"maxLength":40},"maxItems":20},"allowedContexts":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":50},"callbackUrl":{"type":["string","null"],"maxLength":2048,"format":"uri"}}},"AgentWalletListResponse":{"type":"object","properties":{"wallets":{"type":"array","items":{"$ref":"#/components/schemas/AgentWallet"}}},"required":["wallets"]},"AgentWalletLinkResponse":{"allOf":[{"$ref":"#/components/schemas/AgentWallet"},{"type":"object","properties":{"warnings":{"type":"array","items":{"type":"string"},"description":"Present when the link succeeded but the agent cannot pay from this wallet yet. A DEV or STAGING agent linked to a mainnet wallet gets a notice to set the agent's environment to PROD."}}}]},"LinkWalletRequest":{"type":"object","properties":{"walletId":{"type":"string","minLength":1,"description":"Opaque wallet ID to link"},"delegationType":{"allOf":[{"$ref":"#/components/schemas/DelegationType"},{"default":"LIMITED","description":"Delegation type"}]},"spendLimitPerTx":{"type":"number","minimum":0,"default":100,"description":"Per-transaction spend limit (null = unlimited, 0 = deny-all)"},"spendLimitDaily":{"type":"number","minimum":0,"default":1000,"description":"Daily spend limit (null = unlimited, 0 = deny-all)"},"spendLimitWeekly":{"type":"number","minimum":0,"description":"Weekly spend limit"},"spendLimitMonthly":{"type":"number","minimum":0,"description":"Monthly spend limit"},"allowedHoursStart":{"type":"integer","minimum":0,"maximum":23,"default":0,"description":"Start hour (0-23). 0 = midnight."},"allowedHoursEnd":{"type":"integer","minimum":1,"maximum":24,"default":24,"description":"End hour (1-24). 24 = end of day."},"allowedDays":{"type":"array","items":{"type":"string"},"default":["Mon","Tue","Wed","Thu","Fri"],"description":"Days of the week the agent can transact."}},"required":["walletId"]},"UpdateAgentWalletRequest":{"type":"object","properties":{"delegationType":{"$ref":"#/components/schemas/DelegationType"},"spendLimitPerTx":{"type":"number","minimum":0},"spendLimitDaily":{"type":"number","minimum":0},"spendLimitWeekly":{"type":"number","minimum":0},"spendLimitMonthly":{"type":"number","minimum":0},"allowedHoursStart":{"type":"integer","minimum":0,"maximum":23},"allowedHoursEnd":{"type":"integer","minimum":1,"maximum":24},"allowedDays":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"}}},"CustomerPolicyRuleType":{"type":"string","enum":["MAX_AMOUNT","DAILY_LIMIT","WEEKLY_LIMIT","MONTHLY_LIMIT","BUDGET_CAP","ALLOWED_CATEGORIES","BLOCKED_CATEGORIES","ALLOWED_COUNTERPARTIES","BLOCKED_COUNTERPARTIES","TIME_WINDOW","DAY_OF_WEEK","VELOCITY_LIMIT","REQUIRE_APPROVAL_ABOVE","AGENT_ENVIRONMENT","AGENT_RISK_TIER","AGENT_OWNER_ROLE","AGENT_TAG","ATTESTATION_LEVEL","COUNTERPARTY_APPROVAL_STATUS","GEOGRAPHIC_RESTRICTION","TRUST_SCORE","COUNTERPARTY_STATUS","CONTRACT_ALLOWLIST","BLACKOUT_PERIOD","DATE_RANGE","MAINTENANCE_WINDOW","BLOCKED_TIME_WINDOW","ALLOWED_CONTRACTS","PROTOCOL_ALLOWLIST","X402_MAX_PER_REQUEST","X402_PRICE_CEILING","X402_MAX_PER_ENDPOINT","X402_MAX_PER_SERVICE","X402_ALLOWED_SERVICES","X402_BLOCKED_SERVICES","X402_ALLOWED_FACILITATORS","X402_VELOCITY_PER_ENDPOINT","X402_SESSION_BUDGET","MPP_MAX_PER_REQUEST","MPP_PRICE_CEILING","MPP_MAX_PER_ENDPOINT","MPP_MAX_PER_SERVICE","MPP_ALLOWED_SERVICES","MPP_BLOCKED_SERVICES","MPP_VELOCITY_PER_ENDPOINT","MPP_SESSION_BUDGET","MPP_MAX_SESSION_DEPOSIT","MPP_MAX_CONCURRENT_SESSIONS","MPP_MAX_SESSION_DURATION","MPP_BLOCK_SESSION_INTENT","CARD_ALLOWED_MERCHANT_DOMAINS","CARD_BLOCKED_MERCHANT_DOMAINS","COMMERCE_EXTENSION_FACT"]},"RuleOperator":{"type":"string","enum":["EQUALS","NOT_EQUALS","GREATER_THAN","LESS_THAN","GTE","LTE","IN","NOT_IN","IN_LIST","NOT_IN_LIST","BETWEEN","NOT_BETWEEN","DENY"]},"RuleAction":{"type":"string","enum":["ALLOW","DENY","REQUIRE_APPROVAL"]},"PolicyRuleResponse":{"type":"object","properties":{"id":{"type":"string"},"policyId":{"type":"string"},"ruleType":{"$ref":"#/components/schemas/CustomerPolicyRuleType"},"operator":{"$ref":"#/components/schemas/RuleOperator"},"value":{"type":"string","description":"JSON-encoded rule value"},"action":{"$ref":"#/components/schemas/RuleAction"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","policyId","ruleType","operator","value","action","createdAt","updatedAt"],"additionalProperties":false},"Policy":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"policyType":{"type":"string"},"scope":{"type":"string","enum":["organization","assigned"]},"priority":{"type":"integer"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","policyType","scope","priority","isActive","createdAt","updatedAt"]},"PolicyWithRules":{"allOf":[{"$ref":"#/components/schemas/Policy"},{"type":"object","properties":{"rules":{"type":"array","items":{"$ref":"#/components/schemas/PolicyRuleResponse"}},"assignedAgents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"assignedWallets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}}},"required":["rules"]}]},"AssignedAgentPolicy":{"type":"object","properties":{"policyId":{"type":"string"},"assignedAt":{"type":"string","format":"date-time"},"policy":{"$ref":"#/components/schemas/PolicyWithRules"}},"required":["policyId","assignedAt","policy"]},"SdkKeyResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"key":{"type":"string","description":"Full SDK key (conto_agent_xxx). Shown only once."},"keyType":{"type":"string","enum":["standard","admin"]},"scopes":{"type":"array","items":{"type":"string"},"description":"Scopes granted by the key preset. Standard keys cover the payment lifecycle (request, execute, approve, confirm) plus read scopes; admin keys add write and org-management scopes."},"message":{"type":"string","description":"Human-readable reminder that the full key is only returned once."}},"required":["id","name","key","keyType","scopes","message"]},"CreateSdkKeyRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Human-readable key name"},"expiresInDays":{"type":"number","exclusiveMinimum":0,"maximum":730,"description":"Key lifetime in days. Defaults to 365 and cannot exceed 730."},"keyType":{"type":"string","enum":["standard","admin"],"default":"standard","description":"SDK key type. Standard keys use Conto’s default least-privilege agent preset. Admin keys add delegated org-management scopes for agents, wallets, and policies."}},"required":["name"]},"AgentAutomaticProtectionConfig":{"type":"object","properties":{"enabled":{"type":"boolean"},"thresholds":{"type":"object","properties":{"maxConsecutivePolicyViolations":{"type":"integer","minimum":1,"maximum":100},"maxConsecutivePaymentFailures":{"type":"integer","minimum":1,"maximum":100},"spendVelocityMultiplier":{"type":"number","minimum":1.1,"maximum":100},"largePaymentMultiplier":{"type":"number","minimum":1.1,"maximum":1000},"minimumTrustScore":{"type":"number","minimum":0,"maximum":1},"trustScoreDropThreshold":{"type":"number","minimum":0.01,"maximum":1},"maxNewCounterpartiesPerHour":{"type":"integer","minimum":1,"maximum":1000}},"required":["maxConsecutivePolicyViolations","maxConsecutivePaymentFailures","spendVelocityMultiplier","largePaymentMultiplier","minimumTrustScore","trustScoreDropThreshold","maxNewCounterpartiesPerHour"],"additionalProperties":false}},"required":["enabled","thresholds"],"additionalProperties":false},"UpdateAgentAutomaticProtectionConfig":{"type":"object","properties":{"enabled":{"type":"boolean"},"thresholds":{"type":"object","properties":{"maxConsecutivePolicyViolations":{"type":"integer","minimum":1,"maximum":100},"maxConsecutivePaymentFailures":{"type":"integer","minimum":1,"maximum":100},"spendVelocityMultiplier":{"type":"number","minimum":1.1,"maximum":100},"largePaymentMultiplier":{"type":"number","minimum":1.1,"maximum":1000},"minimumTrustScore":{"type":"number","minimum":0,"maximum":1},"trustScoreDropThreshold":{"type":"number","minimum":0.01,"maximum":1},"maxNewCounterpartiesPerHour":{"type":"integer","minimum":1,"maximum":1000}},"additionalProperties":false}},"additionalProperties":false},"AgentFreezeActionResponse":{"type":"object","properties":{"frozen":{"type":"boolean"}},"required":["frozen"],"additionalProperties":false},"FreezeAgentRequest":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500},"freezeWallets":{"type":"boolean","default":false}},"additionalProperties":false},"UnfreezeAgentRequest":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500},"unfreezeWallets":{"type":"boolean","default":false}},"additionalProperties":false},"AgentFreezeStatus":{"type":"object","properties":{"frozen":{"type":"boolean"},"frozenAt":{"type":["string","null"],"format":"date-time"}},"required":["frozen","frozenAt"],"additionalProperties":false},"AgentFreezeHistoryItem":{"type":"object","properties":{"id":{"type":"string"},"action":{"type":"string","enum":["FROZEN","UNFROZEN"]},"actionLabel":{"type":"string","enum":["Frozen","Restored"]},"source":{"type":"string","enum":["TEAM","AUTOMATIC_PROTECTION"]},"sourceLabel":{"type":"string","enum":["Team action","Automatic protection"]},"reason":{"type":["string","null"]},"occurredAt":{"type":"string","format":"date-time"}},"required":["id","action","actionLabel","source","sourceLabel","reason","occurredAt"],"additionalProperties":false},"AgentFreezeHistoryResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AgentFreezeHistoryItem"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["items","total","limit","offset"],"additionalProperties":false},"OrganizationFreezeHistoryItem":{"type":"object","properties":{"id":{"type":"string"},"action":{"type":"string","enum":["FROZEN","UNFROZEN"]},"actionLabel":{"type":"string","enum":["Frozen","Restored"]},"source":{"type":"string","enum":["TEAM","AUTOMATIC_PROTECTION"]},"sourceLabel":{"type":"string","enum":["Team action","Automatic protection"]},"reason":{"type":["string","null"]},"occurredAt":{"type":"string","format":"date-time"},"agent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"required":["id","action","actionLabel","source","sourceLabel","reason","occurredAt","agent"],"additionalProperties":false},"OrganizationFreezeHistoryResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/OrganizationFreezeHistoryItem"}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","exclusiveMinimum":0},"offset":{"type":"integer","minimum":0}},"required":["items","total","limit","offset"],"additionalProperties":false},"WalletType":{"type":"string","enum":["EOA","SMART_WALLET","MULTISIG"]},"ChainType":{"type":"string","enum":["EVM","SOLANA"]},"Wallet":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"},"walletType":{"$ref":"#/components/schemas/WalletType"},"chainType":{"$ref":"#/components/schemas/ChainType"},"chainId":{"type":"string"},"custodyMode":{"type":"string","enum":["MANAGED","EXTERNAL","SMART_CONTRACT"]},"controlModel":{"type":"string","enum":["CONTO_MANAGED","ORGANIZATION_CONTROLLED","EXTERNAL","CONTRACT_ENFORCED"],"description":"Who holds root wallet authority independently of the custody provider."},"keyAccess":{"type":"string","enum":["NO_SELF_SERVICE_EXPORT","OWNER_AUTHORIZED_EXPORT","EXPORT_RECONCILIATION_REQUIRED","CUSTOMER_CONTROLLED","CONTRACT_ADMINISTRATED","EXPORTED"],"description":"Customer-facing key ownership and export capability for this wallet."},"usdcBalance":{"type":"number"},"status":{"$ref":"#/components/schemas/WalletStatus"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","address","walletType","chainType","chainId","custodyMode","controlModel","keyAccess","usdcBalance","status","createdAt","updatedAt"]},"WalletListResponse":{"type":"object","properties":{"wallets":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Wallet"},{"type":"object","properties":{"linkedAgentCount":{"type":"integer","minimum":0}},"required":["linkedAgentCount"]}]}},"total":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1,"maximum":100},"offset":{"type":"integer","minimum":0}},"required":["wallets","total","limit","offset"]},"CreateWalletRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"walletType":{"type":"string","enum":["EOA"],"default":"EOA"},"chainType":{"allOf":[{"$ref":"#/components/schemas/ChainType"},{"default":"EVM"}]},"chainId":{"type":"string","description":"Chain identifier (e.g. \"42431\" for Tempo, \"8453\" for Base)"},"custodyMode":{"type":"string","enum":["MANAGED","EXTERNAL"],"default":"MANAGED","description":"MANAGED creates a wallet that Conto can execute from after approval. EXTERNAL registers an address you control."},"controlModel":{"type":"string","enum":["CONTO_MANAGED","ORGANIZATION_CONTROLLED"],"description":"Root authority for a new MANAGED wallet. ORGANIZATION_CONTROLLED requires an organization owner public key. Omit for the configured organization default."},"address":{"type":"string","description":"Address of an external wallet you control."},"importAddress":{"type":"string","description":"Register an existing address as an external wallet."}},"required":["name"]},"ProvisionResponse":{"type":"object","properties":{"wallet":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"},"chainId":{"type":"string"},"chainType":{"$ref":"#/components/schemas/ChainType"},"custodyMode":{"type":"string","enum":["MANAGED"]},"controlModel":{"type":"string","enum":["CONTO_MANAGED","ORGANIZATION_CONTROLLED","EXTERNAL","CONTRACT_ENFORCED"]},"keyAccess":{"type":"string","enum":["NO_SELF_SERVICE_EXPORT","OWNER_AUTHORIZED_EXPORT","EXPORT_RECONCILIATION_REQUIRED","CUSTOMER_CONTROLLED","CONTRACT_ADMINISTRATED","EXPORTED"]},"balance":{"type":"number"},"currency":{"type":"string"}},"required":["id","name","address","chainId","chainType","custodyMode","controlModel","keyAccess","balance","currency"]},"chain":{"type":"object","properties":{"name":{"type":"string"},"chainId":{"type":"string"},"explorer":{"type":"string"}},"required":["name","chainId","explorer"]}},"required":["wallet","chain"]},"WalletBalanceRefreshDeferred":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["BALANCE_REFRESH_DEFERRED"]},"reason":{"type":"string","enum":["PAYMENT_PENDING","WALLET_CHANGED"]},"totalBalance":{"type":"number","description":"Current stored spendable balance, when returned."}},"required":["error","code","reason"]},"WalletBalanceRefreshResponse":{"type":"object","properties":{"totalBalance":{"type":"number"},"balances":{"type":"array","items":{"type":"object","properties":{"chainId":{"type":"string"},"chainName":{"type":"string"},"balance":{"type":"number"},"symbol":{"type":"string"},"isTestnet":{"type":"boolean"}},"required":["chainId","chainName","balance","symbol","isTestnet"]}},"lastRefreshed":{"type":"string","format":"date-time"}},"required":["totalBalance","balances","lastRefreshed"]},"CardAccessEnforcement":{"type":"object","properties":{"enforcementMode":{"type":"string","enum":["POLICY_OVERLAY"]},"integrationMode":{"type":"string","enum":["SDK_REQUIRED"]},"canBypass":{"type":"boolean","enum":[true]},"credentialStored":{"type":"boolean","enum":[false]},"credentialReleased":{"type":"boolean","enum":[false]},"executionResponsibility":{"type":"string","enum":["CUSTOMER"]},"transactionVerification":{"type":"string","enum":["SELF_REPORTED"]}},"required":["enforcementMode","integrationMode","canBypass","credentialStored","credentialReleased","executionResponsibility","transactionVerification"],"description":"Cooperative enforcement boundary for customer-owned cards in the integrated agent path."},"CardAccessAssignment":{"type":"object","properties":{"id":{"type":"string"},"cardId":{"type":"string"},"cardName":{"type":"string"},"last4":{"type":"string","minLength":4,"maxLength":4},"brand":{"type":["string","null"]},"cardType":{"type":"string"},"fundingType":{"type":"string"},"cardStatus":{"type":"string"},"accessStatus":{"type":"string","enum":["ACTIVE","PAUSED","REVOKED"]},"spendLimitDaily":{"type":"number"},"spendLimitWeekly":{"type":["number","null"]},"spendLimitMonthly":{"type":["number","null"]},"spendLimitPerTx":{"type":"number"},"spentToday":{"type":"number"},"spentThisWeek":{"type":"number"},"spentThisMonth":{"type":"number"},"remainingToday":{"type":"number"},"allowedDays":{"type":"array","items":{"type":"string"}},"allowedHoursStart":{"type":"number"},"allowedHoursEnd":{"type":"number"},"timezone":{"type":"string"},"allowedCategories":{"type":["array","null"],"items":{"type":"string"}},"blockedCategories":{"type":["array","null"],"items":{"type":"string"}},"allowedMerchants":{"type":["array","null"],"items":{"type":"string"}},"blockedMerchants":{"type":["array","null"],"items":{"type":"string"}},"activeFrom":{"type":["string","null"],"format":"date-time"},"activeUntil":{"type":["string","null"],"format":"date-time"},"isActive":{"type":"boolean"},"enforcement":{"$ref":"#/components/schemas/CardAccessEnforcement"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","cardId","cardName","last4","brand","cardType","fundingType","cardStatus","accessStatus","spendLimitDaily","spendLimitWeekly","spendLimitMonthly","spendLimitPerTx","spentToday","spentThisWeek","spentThisMonth","remainingToday","allowedDays","allowedHoursStart","allowedHoursEnd","timezone","allowedCategories","blockedCategories","allowedMerchants","blockedMerchants","activeFrom","activeUntil","isActive","enforcement","createdAt","updatedAt"]},"AssignCardAccessRequest":{"type":"object","properties":{"spendLimitDaily":{"type":"number","exclusiveMinimum":0,"example":500},"spendLimitWeekly":{"type":["number","null"],"exclusiveMinimum":0,"example":1500},"spendLimitMonthly":{"type":["number","null"],"exclusiveMinimum":0,"example":4000},"spendLimitPerTx":{"type":"number","exclusiveMinimum":0,"example":250},"allowedDays":{"type":"array","items":{"type":"string","enum":["Sun","Mon","Tue","Wed","Thu","Fri","Sat"]},"minItems":1},"allowedHoursStart":{"type":"integer","minimum":0,"maximum":23,"example":9},"allowedHoursEnd":{"type":"integer","minimum":1,"maximum":24,"example":17},"timezone":{"type":"string","example":"America/Los_Angeles"},"allowedCategories":{"type":["array","null"],"items":{"type":"string"},"example":["5734"]},"blockedCategories":{"type":["array","null"],"items":{"type":"string"},"example":["7995"]},"allowedMerchants":{"type":["array","null"],"items":{"type":"string"},"example":["Example Software"]},"blockedMerchants":{"type":["array","null"],"items":{"type":"string"}},"activeFrom":{"type":["string","null"],"format":"date-time"},"activeUntil":{"type":["string","null"],"format":"date-time"},"cardId":{"type":"string","example":"cmm59z4p10001abc123def456"}},"required":["cardId"]},"UpdateCardAccessRequest":{"anyOf":[{"type":"object","properties":{"action":{"type":"string","enum":["PAUSE"]}},"required":["action"]},{"type":"object","properties":{"action":{"type":"string","enum":["RESUME"]}},"required":["action"]},{"type":"object","properties":{"spendLimitDaily":{"type":"number","exclusiveMinimum":0,"example":500},"spendLimitWeekly":{"type":["number","null"],"exclusiveMinimum":0,"example":1500},"spendLimitMonthly":{"type":["number","null"],"exclusiveMinimum":0,"example":4000},"spendLimitPerTx":{"type":"number","exclusiveMinimum":0,"example":250},"allowedDays":{"type":"array","items":{"type":"string","enum":["Sun","Mon","Tue","Wed","Thu","Fri","Sat"]},"minItems":1},"allowedHoursStart":{"type":"integer","minimum":0,"maximum":23,"example":9},"allowedHoursEnd":{"type":"integer","minimum":1,"maximum":24,"example":17},"timezone":{"type":"string","example":"America/Los_Angeles"},"allowedCategories":{"type":["array","null"],"items":{"type":"string"},"example":["5734"]},"blockedCategories":{"type":["array","null"],"items":{"type":"string"},"example":["7995"]},"allowedMerchants":{"type":["array","null"],"items":{"type":"string"},"example":["Example Software"]},"blockedMerchants":{"type":["array","null"],"items":{"type":"string"}},"activeFrom":{"type":["string","null"],"format":"date-time"},"activeUntil":{"type":["string","null"],"format":"date-time"},"action":{"type":"string","enum":["UPDATE"]}},"required":["action"]}]},"ConnectedCardReferenceSummary":{"type":"object","properties":{"id":{"type":"string"},"cardId":{"type":"string"},"provider":{"type":"string","example":"BASIS_THEORY"},"consumerReference":{"type":"string"},"lifecycleState":{"type":"string","example":"ACTIVE"},"railStatus":{"type":["string","null"]},"lastSyncedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","cardId","provider","consumerReference","lifecycleState","railStatus","lastSyncedAt","createdAt","updatedAt"]},"ConnectConnectedCardResponse":{"type":"object","properties":{"reference":{"$ref":"#/components/schemas/ConnectedCardReferenceSummary"}},"required":["reference"]},"ConnectedCardDisplay":{"type":"object","properties":{"last4":{"type":"string","example":"4242"},"brand":{"type":"string","example":"VISA"},"expiryMonth":{"type":"integer","example":12},"expiryYear":{"type":"integer","example":2030},"fundingType":{"type":"string","enum":["CREDIT","DEBIT","PREPAID","UNKNOWN"]}},"required":["last4"]},"ConnectedCardConsumer":{"type":"object","properties":{"email":{"type":"string","example":"cardholder@example.com"},"id":{"type":"string"},"countryCode":{"type":"string","example":"US"},"languageCode":{"type":"string","example":"en"}},"required":["email"]},"ConnectConnectedCardRequest":{"type":"object","properties":{"cardId":{"type":"string","example":"cmm59z4p10001abc123def456"},"consumerReference":{"type":"string","description":"Verified organization-member user id that owns the card.","example":"cmm5cardholderuser0001"},"opaqueTokenId":{"type":"string","description":"Opaque browser token id from the card tokenization step. Exchanged once server-side and never stored or returned."},"display":{"$ref":"#/components/schemas/ConnectedCardDisplay"},"consumer":{"$ref":"#/components/schemas/ConnectedCardConsumer"}},"required":["cardId","consumerReference","opaqueTokenId","display","consumer"]},"ConnectedCardMandate":{"type":"object","properties":{"id":{"type":"string"},"providerReferenceId":{"type":"string"},"bindingId":{"type":"string"},"status":{"type":"string","example":"REQUIRES_VERIFICATION"},"scopeType":{"type":"string","enum":["SINGLE_USE","STANDING"],"example":"SINGLE_USE"},"verificationStatus":{"type":"string","example":"PENDING"},"amountMinor":{"type":"number","example":2000},"currency":{"type":"string","example":"USD"},"description":{"type":"string"},"merchant":{"type":"object","properties":{"name":{"type":["string","null"]},"categoryCode":{"type":["string","null"]},"countryCode":{"type":["string","null"]},"checkoutOrigin":{"type":["string","null"]}},"required":["name","categoryCode","countryCode","checkoutOrigin"]},"expiresAt":{"type":"string","format":"date-time"},"verifiedAt":{"type":["string","null"],"format":"date-time"},"exhaustedAt":{"type":["string","null"],"format":"date-time"},"revokedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","providerReferenceId","bindingId","status","scopeType","verificationStatus","amountMinor","currency","description","merchant","expiresAt","verifiedAt","exhaustedAt","revokedAt","createdAt","updatedAt"]},"ConnectedCardReference":{"allOf":[{"$ref":"#/components/schemas/ConnectedCardReferenceSummary"},{"type":"object","properties":{"card":{"type":"object","properties":{"last4":{"type":"string"},"brand":{"type":["string","null"]},"fundingType":{"type":"string"},"cardType":{"type":"string"},"status":{"type":"string"},"spendLimitDaily":{"type":["number","null"]},"spendLimitWeekly":{"type":["number","null"]},"spendLimitMonthly":{"type":["number","null"]},"spendLimitPerTx":{"type":["number","null"]}},"required":["last4","brand","fundingType","cardType","status","spendLimitDaily","spendLimitWeekly","spendLimitMonthly","spendLimitPerTx"]},"mandates":{"type":"array","items":{"$ref":"#/components/schemas/ConnectedCardMandate"}}},"required":["card","mandates"]}]},"ConnectedCardListResponse":{"type":"object","properties":{"references":{"type":"array","items":{"$ref":"#/components/schemas/ConnectedCardReference"}}},"required":["references"]},"ConnectedCardBinding":{"type":"object","properties":{"id":{"type":"string"},"providerReferenceId":{"type":"string"},"agentId":{"type":"string"},"provider":{"type":"string","example":"BASIS_THEORY"},"status":{"type":"string","example":"ACTIVE"},"revokedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","providerReferenceId","agentId","provider","status","revokedAt","createdAt","updatedAt"]},"ConnectedCardBindingResponse":{"type":"object","properties":{"binding":{"$ref":"#/components/schemas/ConnectedCardBinding"}},"required":["binding"]},"ConnectedCardBindingInput":{"type":"object","properties":{"providerBindingId":{"type":"string"},"providerAgentId":{"type":"string"},"state":{"type":"string","enum":["ACTIVE","REVOKED"]}},"required":["providerBindingId","state"]},"DelegateConnectedCardRequest":{"type":"object","properties":{"agentId":{"type":"string","example":"cmm59agent0001abc123def456"},"idempotencyKey":{"type":"string","example":"delegate-2026-08-18-001"},"binding":{"$ref":"#/components/schemas/ConnectedCardBindingInput"},"raiseCardLimits":{"type":"boolean","description":"For a card connected moments ago: on the card's first link to any agent, each card limit rises to at least the agent's. Ignored once the card has a link. Never lowers a card limit.","example":true}},"required":["agentId","idempotencyKey","binding"]},"ConnectedCardDisconnectResult":{"type":"object","properties":{"alreadyDisconnected":{"type":"boolean"},"revokedMandates":{"type":"integer"},"cancelledDraws":{"type":"integer"},"reconciliationRequired":{"type":"integer"},"providerCancellationsPending":{"type":"integer"}},"required":["alreadyDisconnected","revokedMandates","cancelledDraws","reconciliationRequired","providerCancellationsPending"]},"DisconnectConnectedCardResponse":{"type":"object","properties":{"disconnect":{"$ref":"#/components/schemas/ConnectedCardDisconnectResult"}},"required":["disconnect"]},"DisconnectConnectedCardRequest":{"type":"object","properties":{"agentId":{"type":"string","example":"cmm59agent0001abc123def456"},"reason":{"type":"string","example":"Card reported lost"}},"required":["agentId"]},"ConnectedCardMandateResponse":{"type":"object","properties":{"mandate":{"$ref":"#/components/schemas/ConnectedCardMandate"}},"required":["mandate"]},"ConnectedCardMandateMerchant":{"type":"object","properties":{"providerMerchantId":{"type":"string"},"name":{"type":"string","minLength":1,"example":"Example Software"},"categoryCode":{"type":"string","example":"5734"},"countryCode":{"type":"string","pattern":"^[A-Za-z]{2}$","example":"US"},"checkoutOrigin":{"type":"string","format":"uri","pattern":"^https:\\/\\/","example":"https://checkout.example.com"}},"required":["name","countryCode","checkoutOrigin"]},"CreateConnectedCardMandateRequest":{"type":"object","properties":{"bindingId":{"type":"string","example":"cmm59binding0001abc123def"},"shape":{"type":"string","enum":["SINGLE_USE","STANDING"]},"contoGrantId":{"type":"string","example":"grant-2026-08-18-001"},"idempotencyKey":{"type":"string","example":"mandate-2026-08-18-001"},"description":{"type":"string","example":"Renew analytics subscription"},"amountMinor":{"type":"integer","exclusiveMinimum":0,"description":"Amount in the currency minor unit. For SINGLE_USE the one purchase; for STANDING the budget cap.","example":2000},"currency":{"type":"string","enum":["USD"],"example":"USD"},"merchant":{"$ref":"#/components/schemas/ConnectedCardMandateMerchant"},"expiresAt":{"type":"string","format":"date-time","example":"2026-08-18T18:30:00.000Z"}},"required":["bindingId","shape","contoGrantId","idempotencyKey","description","amountMinor","currency","merchant","expiresAt"]},"ConnectedCardVerifyEnvelope":{"type":"object","properties":{"status":{"type":"string"},"rail":{"type":"string"},"provider":{"type":"string"},"next_action":{"type":"object","additionalProperties":{}}},"required":["status","rail","provider"]},"ConnectedCardVerifyResponse":{"type":"object","properties":{"verification":{"$ref":"#/components/schemas/ConnectedCardVerifyEnvelope"}},"required":["verification"]},"VerifyConnectedCardMandateRequest":{"type":"object","additionalProperties":{},"description":"One browser SDK verify action, forwarded verbatim to the provider."},"ConnectedCardDrawable":{"type":"object","properties":{"environment":{"type":"string","enum":["live","test"],"description":"Read from the persisted card provider. test means a synthetic card with simulated checkout and no real charges."},"bindingId":{"type":"string"},"agentId":{"type":"string"},"status":{"type":"string","example":"ACTIVE"},"cardId":{"type":"string"},"reference":{"type":"object","properties":{"id":{"type":"string"},"provider":{"type":"string","example":"BASIS_THEORY"},"lifecycleState":{"type":"string","example":"ACTIVE"},"railStatus":{"type":["string","null"]}},"required":["id","provider","lifecycleState","railStatus"]},"card":{"type":"object","properties":{"last4":{"type":"string"},"brand":{"type":["string","null"]},"fundingType":{"type":"string"},"cardType":{"type":"string"},"status":{"type":"string"},"spendLimitDaily":{"type":["number","null"]},"spendLimitWeekly":{"type":["number","null"]},"spendLimitMonthly":{"type":["number","null"]},"spendLimitPerTx":{"type":["number","null"]}},"required":["last4","brand","fundingType","cardType","status","spendLimitDaily","spendLimitWeekly","spendLimitMonthly","spendLimitPerTx"]},"mandates":{"type":"array","items":{"$ref":"#/components/schemas/ConnectedCardMandate"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["bindingId","agentId","status","cardId","reference","card","mandates","createdAt","updatedAt"]},"ConnectedCardDrawListResponse":{"type":"object","properties":{"cards":{"type":"array","items":{"$ref":"#/components/schemas/ConnectedCardDrawable"}}},"required":["cards"]},"PreviewConnectedCardPurchaseResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["live","test"]},"preview":{"type":"boolean","enum":[true]},"decision":{"type":"string","enum":["APPROVED","DENIED","REQUIRES_APPROVAL"]},"reasons":{"type":"array","items":{"type":"string"}}},"required":["environment","preview","decision","reasons"],"description":"What the card limits and policies would decide for this purchase right now. Nothing is reserved and no credential is issued. The draw makes the final decision against the verified authorization."},"PreviewConnectedCardMerchant":{"type":"object","properties":{"name":{"type":"string","example":"Example Store"},"providerMerchantId":{"type":"string"},"categoryCode":{"type":"string","example":"5651"},"countryCode":{"type":"string","example":"US"},"checkoutOrigin":{"type":"string","description":"HTTPS origin of the store checkout.","example":"https://shop.example.com"}}},"PreviewConnectedCardPurchaseRequest":{"type":"object","properties":{"cardId":{"type":"string","example":"cmm59z4p10001abc123def456"},"amountMinor":{"type":"integer","exclusiveMinimum":0,"description":"Purchase total in the currency minor unit.","example":4200},"currency":{"type":"string","enum":["USD"],"example":"USD"},"merchant":{"$ref":"#/components/schemas/PreviewConnectedCardMerchant"}},"required":["cardId","amountMinor","merchant"]},"ConnectedCardCredential":{"type":"object","properties":{"number":{"type":"string"},"securityValue":{"type":"string"},"expirationMonth":{"type":"string","example":"08"},"expirationYear":{"type":"string","example":"2030"},"cardholderName":{"type":"string"}},"required":["number","securityValue","expirationMonth","expirationYear"],"description":"The single-use, merchant-locked, amount-capped card credential. Returned exactly once on a successful mint and never persisted server-side. It cannot be re-fetched: a replayed draw returns the decision without this field."},"DrawConnectedCardResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["live"],"description":"Always live on this route. Test cards use /api/sdk/connected-cards/test/draws."},"requestId":{"type":"string"},"minted":{"type":"boolean"},"replayed":{"type":"boolean"},"decision":{"type":"string","enum":["APPROVED","DENIED","REQUIRES_APPROVAL"]},"reasons":{"type":"array","items":{"type":"string"}},"reconciliationRequired":{"type":"boolean"},"credential":{"$ref":"#/components/schemas/ConnectedCardCredential"},"credentialExpiresAt":{"type":"string","format":"date-time"}},"required":["requestId","minted","replayed","decision","reasons"],"description":"The draw outcome. The credential is present only on a successful mint and is returned exactly once; DENIED, REQUIRES_APPROVAL, reconciliation, and replay outcomes carry no credential."},"DrawConnectedCardMerchant":{"type":"object","properties":{"merchantName":{"type":"string","example":"Example Software"},"merchantId":{"type":"string"},"merchantCategory":{"type":"string","example":"5734"},"merchantCountry":{"type":"string","example":"US"}}},"DrawConnectedCardRequest":{"type":"object","properties":{"cardId":{"type":"string","example":"cmm59z4p10001abc123def456"},"mandateId":{"type":"string","example":"cmm59mandate0001abc123def"},"idempotencyKey":{"type":"string","description":"Fresh per draw, stable across retries of the same draw.","example":"draw-2026-08-18-001"},"amountMinor":{"type":"integer","exclusiveMinimum":0,"description":"Draw amount in the currency minor unit. Equals the mandate amount.","example":2000},"currency":{"type":"string","enum":["USD"],"example":"USD"},"merchant":{"$ref":"#/components/schemas/DrawConnectedCardMerchant"}},"required":["cardId","mandateId","idempotencyKey","amountMinor","currency","merchant"]},"ConnectedCardMandateRevokeResponse":{"type":"object","properties":{"mandate":{"$ref":"#/components/schemas/ConnectedCardMandate"},"providerCancellationStatus":{"type":"string","enum":["COMPLETED","PENDING"]},"cancelledDraws":{"type":"integer","description":"Pending reviews and approved-but-unexecuted draws cancelled by revocation. Only unissued reservations are released.","example":1},"reconciliationRequired":{"type":"integer","description":"EXECUTING or CONFIRMING draws left intact for reconcile. A live credential may exist, so their reservations are not released.","example":0}},"required":["mandate","providerCancellationStatus","cancelledDraws","reconciliationRequired"]},"ConnectedCardAgentLimits":{"type":"object","properties":{"spendLimitPerTx":{"type":"number","example":100},"spendLimitDaily":{"type":"number","example":500},"spendLimitWeekly":{"type":["number","null"],"example":1500},"spendLimitMonthly":{"type":["number","null"],"example":5000}},"required":["spendLimitPerTx","spendLimitDaily","spendLimitWeekly","spendLimitMonthly"]},"UpdateConnectedCardAgentLimitsResponse":{"type":"object","properties":{"agentLimits":{"$ref":"#/components/schemas/ConnectedCardAgentLimits"}},"required":["agentLimits"]},"UpdateConnectedCardAgentLimitsRequest":{"type":"object","properties":{"agentId":{"type":"string","example":"cmm59agent0001abc123def456"},"spendLimitPerTx":{"type":"number","exclusiveMinimum":0,"description":"Agent per-transaction limit. Must be at or below the card ceiling and daily.","example":100},"spendLimitDaily":{"type":"number","exclusiveMinimum":0,"description":"Agent daily limit. Must be at or below the card daily limit.","example":500},"spendLimitWeekly":{"type":["number","null"],"exclusiveMinimum":0,"description":"Agent weekly limit, or null for no weekly limit. Bounded by the card ceiling.","example":1500},"spendLimitMonthly":{"type":["number","null"],"exclusiveMinimum":0,"description":"Agent monthly limit, or null for no monthly limit. Bounded by the card ceiling.","example":5000}},"required":["agentId","spendLimitPerTx","spendLimitDaily"]},"UpdateConnectedCardLimitsResponse":{"type":"object","properties":{"cardLimits":{"$ref":"#/components/schemas/ConnectedCardAgentLimits"}},"required":["cardLimits"]},"UpdateConnectedCardLimitsRequest":{"type":"object","properties":{"spendLimitPerTx":{"type":"number","exclusiveMinimum":0,"description":"Card per-transaction limit. Must be at or below daily.","example":500},"spendLimitDaily":{"type":"number","exclusiveMinimum":0,"example":2000},"spendLimitWeekly":{"type":["number","null"],"exclusiveMinimum":0,"description":"Card weekly limit, or null for no weekly limit. At or above daily.","example":5000},"spendLimitMonthly":{"type":["number","null"],"exclusiveMinimum":0,"description":"Card monthly limit, or null for no monthly limit. At or above daily and weekly.","example":10000}},"required":["spendLimitPerTx","spendLimitDaily"]},"RelinkConnectedCardRequest":{"type":"object","properties":{"agentId":{"type":"string","example":"cmm59agent0001abc123def456"},"spendLimitPerTx":{"type":"number","exclusiveMinimum":0,"example":100},"spendLimitDaily":{"type":"number","exclusiveMinimum":0,"example":500},"spendLimitWeekly":{"type":["number","null"],"exclusiveMinimum":0,"example":1500},"spendLimitMonthly":{"type":["number","null"],"exclusiveMinimum":0,"example":2000}},"required":["agentId","spendLimitPerTx","spendLimitDaily"]},"ReconcileConnectedCardMintResponse":{"type":"object","properties":{"resolved":{"type":"boolean"},"status":{"type":"string","enum":["COMPLETED","CANCELLED"]},"transactionId":{"type":"string"}},"required":["resolved","status"]},"ReconcileConnectedCardMintRequest":{"type":"object","properties":{"requestId":{"type":"string","example":"cmm59draw0001abc123def456"},"outcome":{"type":"string","enum":["EXECUTED","NOT_EXECUTED"],"description":"Records a checkout outcome without verifying settlement. NOT_EXECUTED releases the draw's full hold from the card and agent limits. EXECUTED with a smaller actualAmountMinor releases the difference. The provider's allowance capacity is not restored."},"externalTxId":{"type":"string","description":"The issuer or network reference an operator confirmed the charge under.","example":"ch_3P9x2yLkdIwHu7ix0abcDEF1"},"actualAmountMinor":{"type":"integer","exclusiveMinimum":0,"description":"The operator-reported checkout amount in the currency minor unit, when it differs from the reserved amount. Capped at the reserved amount by the service.","example":1999},"resolutionReason":{"type":"string","example":"Reviewed merchant receipt"}},"required":["requestId","outcome"]},"ConnectedCardStuckDraw":{"type":"object","properties":{"requestId":{"type":"string"},"amount":{"type":"number","example":20},"currency":{"type":"string","example":"USD"},"merchantName":{"type":["string","null"]},"cardLast4":{"type":"string","example":"4242"},"cardBrand":{"type":["string","null"],"example":"VISA"},"agentId":{"type":"string"},"status":{"type":"string","example":"EXECUTING"},"executionClaimedAt":{"type":["string","null"],"format":"date-time"},"credentialDelivered":{"type":"boolean"},"credentialExpiresAt":{"type":["string","null"],"format":"date-time"},"agentReport":{"type":["object","null"],"properties":{"outcome":{"type":"string","enum":["USED","NOT_USED"]},"amount":{"type":["number","null"],"example":12.5},"reportedAt":{"type":"string","format":"date-time"}},"required":["outcome","amount","reportedAt"],"description":"The agent's own report. Shown for review, never applied."}},"required":["requestId","amount","currency","merchantName","cardLast4","cardBrand","agentId","status","executionClaimedAt","credentialDelivered","credentialExpiresAt","agentReport"]},"ConnectedCardReconcileListResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ConnectedCardStuckDraw"}},"total":{"type":"integer"}},"required":["items","total"]},"ReportConnectedCardDrawOutcomeResponse":{"type":"object","properties":{"recorded":{"type":"boolean","enum":[true]},"closed":{"type":"boolean","description":"True when the report closed the draw: used at the full approved amount."},"reviewRequired":{"type":"boolean","description":"True when a person must confirm the outcome before any held amount is released."},"settlementVerified":{"type":"boolean","enum":[false]}},"required":["recorded","closed","reviewRequired","settlementVerified"]},"ReportConnectedCardDrawOutcomeRequest":{"type":"object","properties":{"outcome":{"type":"string","enum":["USED","NOT_USED"],"description":"USED: the card number was charged. NOT_USED: it was not used. A report never releases held spend."},"amountMinor":{"type":"integer","exclusiveMinimum":0,"description":"USED only. The amount charged in the currency minor unit, at most the approved amount. Omit it for the full approved amount.","example":1850}},"required":["outcome"]},"ProvisionTestCardResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["test"],"description":"Test environment. Simulated end to end: no card is charged and no funds move."},"created":{"type":"boolean","description":"False when the agent already had a test card."},"cardId":{"type":"string"},"referenceId":{"type":"string"},"bindingId":{"type":"string"}},"required":["environment","created","cardId","referenceId","bindingId"]},"ProvisionTestCardRequest":{"type":"object","properties":{"agentId":{"type":"string","example":"cmm59agent0001abc123def45"},"limits":{"type":"object","properties":{"spendLimitPerTx":{"type":"number","exclusiveMinimum":0,"example":50},"spendLimitDaily":{"type":"number","exclusiveMinimum":0,"example":100}},"required":["spendLimitPerTx","spendLimitDaily"],"description":"The agent's starting limits on the test card, at most $100 a purchase and $250 a day. Defaults to $50 and $100."}},"required":["agentId"]},"TestMandateResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["test"],"description":"Test environment. Simulated end to end: no card is charged and no funds move."},"mandate":{"$ref":"#/components/schemas/ConnectedCardMandate"}},"required":["environment","mandate"],"description":"The authorization is saved with verificationStatus SIMULATED and status ACTIVE. No cardholder or provider verified it."},"CreateTestMandateRequest":{"type":"object","properties":{"bindingId":{"type":"string"},"merchantKey":{"type":"string","enum":["conto-test-supplies","conto-test-cloud"]},"shape":{"type":"string","enum":["SINGLE_USE","STANDING"]},"amountMinor":{"type":"integer","exclusiveMinimum":0,"description":"SINGLE_USE: the one purchase. STANDING: the total across purchases.","example":10000},"expiresAt":{"type":"string","format":"date-time"},"idempotencyKey":{"type":"string"},"contoGrantId":{"type":"string"},"description":{"type":"string"}},"required":["bindingId","merchantKey","shape","amountMinor","expiresAt","idempotencyKey"]},"TestReceipt":{"type":"object","properties":{"environment":{"type":"string","enum":["test"],"description":"Test environment. Simulated end to end: no card is charged and no funds move."},"simulated":{"type":"boolean","enum":[true]},"settlementMode":{"type":"string","enum":["test"]},"notice":{"type":"string"},"orderId":{"type":"string"},"orderNumber":{"type":"string","example":"TEST-4F2A9C1B7E"},"requestId":{"type":"string"},"transactionId":{"type":"string"},"agentId":{"type":"string"},"cardId":{"type":"string"},"merchant":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"}},"required":["key","name"]},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"integer"},"unitAmountMinor":{"type":"integer"},"amountMinor":{"type":"integer"}},"required":["sku","name","quantity","unitAmountMinor","amountMinor"]}},"amountMinor":{"type":"integer"},"currency":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["environment","simulated","settlementMode","notice","orderId","orderNumber","requestId","transactionId","agentId","cardId","merchant","items","amountMinor","currency","createdAt"],"description":"A simulated order at a Conto test merchant. Not a card network authorization, settlement, or merchant acceptance."},"TestMerchant":{"type":"object","properties":{"key":{"type":"string","example":"conto-test-supplies"},"name":{"type":"string","example":"Conto Test Supplies"},"categoryCode":{"type":"string","example":"5943"},"countryCode":{"type":"string","example":"US"},"products":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","example":"notebook-pack"},"name":{"type":"string","example":"Notebooks, pack of 3"},"unitAmountMinor":{"type":"integer","example":1200}},"required":["sku","name","unitAmountMinor"]}}},"required":["key","name","categoryCode","countryCode","products"]},"TestCardListResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["test"],"description":"Test environment. Simulated end to end: no card is charged and no funds move."},"cards":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/ConnectedCardDrawable"},{"type":"object","properties":{"label":{"type":"string"}},"required":["label"]}]}},"merchants":{"type":"array","items":{"$ref":"#/components/schemas/TestMerchant"}}},"required":["environment","cards","merchants"]},"TestCardCredential":{"type":"object","properties":{"token":{"type":"string","description":"Opaque single-use token, prefixed ctc_test_. Accepted only by the Conto test checkout. Not card data."},"format":{"type":"string","enum":["test_token"]}},"required":["token","format"],"description":"Returned exactly once on an approved draw and never stored in the clear. Keep it out of logs and model context, like a live credential."},"DrawTestCardResponse":{"type":"object","properties":{"environment":{"type":"string","enum":["test"],"description":"Test environment. Simulated end to end: no card is charged and no funds move."},"requestId":{"type":"string"},"minted":{"type":"boolean"},"replayed":{"type":"boolean"},"decision":{"type":"string","enum":["APPROVED","DENIED","REQUIRES_APPROVAL"]},"reasons":{"type":"array","items":{"type":"string"}},"reconciliationRequired":{"type":"boolean"},"credentialExpiresAt":{"type":"string","format":"date-time"},"testCredential":{"$ref":"#/components/schemas/TestCardCredential"},"notice":{"type":"string"}},"required":["environment","requestId","minted","replayed","decision","reasons"]},"DrawTestCardRequest":{"type":"object","properties":{"cardId":{"type":"string","example":"cmm59z4p10001abc123def456"},"mandateId":{"type":"string","example":"cmm59mandate0001abc123def"},"idempotencyKey":{"type":"string","description":"Fresh per draw, stable across retries of the same draw.","example":"draw-2026-08-18-001"},"amountMinor":{"type":"integer","exclusiveMinimum":0,"description":"Draw amount in the currency minor unit. Equals the mandate amount.","example":2000},"currency":{"type":"string","enum":["USD"],"example":"USD"},"merchant":{"$ref":"#/components/schemas/DrawConnectedCardMerchant"}},"required":["cardId","mandateId","idempotencyKey","amountMinor","currency","merchant"]},"TestCheckoutResponse":{"allOf":[{"$ref":"#/components/schemas/TestReceipt"},{"type":"object","properties":{"replayed":{"type":"boolean","description":"True when this credential already completed this checkout. Nothing new was recorded."},"status":{"type":"string","enum":["COMPLETED"]}},"required":["replayed","status"]}],"description":"A simulated order at a Conto test merchant. Not a card network authorization, settlement, or merchant acceptance."},"TestCheckoutRequest":{"type":"object","properties":{"requestId":{"type":"string"},"credential":{"type":"string","description":"The testCredential.token from the draw."},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"quantity":{"type":"integer","minimum":1,"maximum":20}},"required":["sku","quantity"]},"maxItems":10,"description":"Items from the test merchant's catalog. Omit to buy one line for the authorized amount."}},"required":["requestId","credential"]},"PolicyListResponse":{"type":"object","properties":{"policies":{"type":"array","items":{"$ref":"#/components/schemas/PolicyWithRules"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["policies","total","limit","offset"]},"PolicyType":{"type":"string","enum":["SPEND_LIMIT","TIME_WINDOW","MERCHANT","CATEGORY","VELOCITY","GEOGRAPHIC","APPROVAL_THRESHOLD","AGENT_IDENTITY","COUNTERPARTY","COUNTERPARTY_IDENTITY","BUDGET_ALLOCATION","WHITELIST","EXPIRATION","COMPOSITE","CONTRACT_ALLOWLIST","BLACKOUT_PERIOD","X402_SPEND_LIMIT","X402_SERVICE_CONTROL","X402_ENDPOINT_CONTROL","MPP_SPEND_LIMIT","MPP_SERVICE_CONTROL","MPP_ENDPOINT_CONTROL","MPP_SESSION_LIFECYCLE"]},"PolicyRule":{"type":"object","properties":{"ruleType":{"$ref":"#/components/schemas/CustomerPolicyRuleType"},"operator":{"allOf":[{"$ref":"#/components/schemas/RuleOperator"},{"description":"Comparison operator. For spend limits use LTE. Aliases: GREATER_THAN_OR_EQUAL=GTE, LESS_THAN_OR_EQUAL=LTE."}]},"value":{"type":"string","maxLength":10000,"description":"JSON-encoded rule value. For numeric limits: \"500\". For lists: '[\"addr1\",\"addr2\"]'. For time windows: '{\"start\":\"09:00\",\"end\":\"17:00\"}'."},"action":{"allOf":[{"$ref":"#/components/schemas/RuleAction"},{"default":"ALLOW","description":"What to do when the rule matches. ALLOW = permit if condition met. DENY = block if condition met."}]}},"required":["ruleType","operator","value"],"additionalProperties":false},"CreatePolicyRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Policy name"},"description":{"type":"string","maxLength":500,"description":"Policy description"},"policyType":{"$ref":"#/components/schemas/PolicyType"},"priority":{"type":"integer","minimum":0,"maximum":100,"default":50,"description":"Higher priority policies are evaluated first."},"isActive":{"type":"boolean","default":true},"scope":{"type":"string","enum":["organization","assigned"],"description":"organization applies automatically to every agent and wallet; assigned applies only through explicit agent, wallet, or card assignments."},"rules":{"type":"array","items":{"$ref":"#/components/schemas/PolicyRule"},"maxItems":50},"agentIds":{"type":"array","items":{"type":"string","minLength":1},"maxItems":20}},"required":["name","policyType"],"additionalProperties":false},"SimulatePolicyRequest":{"type":"object","properties":{"candidatePolicy":{"allOf":[{"$ref":"#/components/schemas/CreatePolicyRequest"},{"description":"The candidate policy to test, in the same shape as a create request."}]},"agentId":{"type":"string","minLength":1,"description":"Restrict the replay to one agent. Omit to replay across the org."},"sampleSize":{"type":"integer","minimum":1,"maximum":500,"default":100,"description":"Most recent transactions to replay (max 500)."},"from":{"type":"string","format":"date-time","description":"Start of the replay window."},"to":{"type":"string","format":"date-time","description":"End of the replay window."}},"required":["candidatePolicy"],"additionalProperties":false},"UpdatePolicyRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":500},"priority":{"type":"integer","minimum":0,"maximum":100},"isActive":{"type":"boolean"},"scope":{"type":"string","enum":["organization","assigned"]}},"additionalProperties":false},"CreatePolicyRulesRequest":{"type":"object","properties":{"rules":{"type":"array","items":{"$ref":"#/components/schemas/PolicyRule"},"minItems":1,"maxItems":50}},"required":["rules"],"additionalProperties":false},"GovernanceApprovalAction":{"type":"string","enum":["API_KEY_CREATE","API_KEY_REVOKE","API_KEY_ROTATE","FREEZE_CONFIG_UPDATE","POLICY_CREATE","POLICY_UPDATE","POLICY_DELETE","POLICY_RULE_CREATE","POLICY_RULE_UPDATE","POLICY_RULE_DELETE"],"description":"Organization change that can require a second person to approve it."},"GovernanceApprovalSettings":{"type":"object","properties":{"requiredActions":{"type":"array","items":{"$ref":"#/components/schemas/GovernanceApprovalAction"},"description":"Changes that need approval before they apply."},"availableActions":{"type":"array","items":{"$ref":"#/components/schemas/GovernanceApprovalAction"}}},"required":["requiredActions","availableActions"]},"GovernanceApprovalRequest":{"type":"object","properties":{"id":{"type":"string","description":"Send this as `x-governance-approval-id` when you retry the approved change."},"action":{"$ref":"#/components/schemas/GovernanceApprovalAction"},"resource":{"type":"string","description":"Type of resource the change applies to."},"resourceId":{"type":["string","null"]},"status":{"type":"string","enum":["PENDING","APPROVED","REJECTED","EXPIRED","CONSUMED"]},"reason":{"type":["string","null"]},"requestedByActorType":{"type":"string","description":"Who asked for the change, for example USER or API_KEY."},"requestedBy":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":"string"},"image":{"type":["string","null"]}},"required":["id","name","email","image"]},"expiresAt":{"type":["string","null"],"format":"date-time"},"approvedUntil":{"type":["string","null"],"format":"date-time","description":"Retry the change before this time. The approval can be used once."},"decidedAt":{"type":["string","null"],"format":"date-time"},"decidedBy":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":"string"},"image":{"type":["string","null"]}},"required":["id","name","email","image"]},"decisionComment":{"type":["string","null"]},"consumedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","action","resource","resourceId","status","reason","requestedByActorType","requestedBy","expiresAt","approvedUntil","decidedAt","decidedBy","decisionComment","consumedAt","createdAt","updatedAt"]},"NotificationEventType":{"type":"string","enum":["approval.requested","approval.decided","approval.escalated","approval.expired","governance.approval.requested","governance.approval.decided","payment.executed","conto_pay.request.received","conto_pay.request.paid","conto_pay.request.rejected","conto_pay.request.expired","conto_pay.request.cancelled","conto_pay.request.reminder","alert.raised"],"description":"Event that triggers a notification. payment.executed, alert.raised, governance.approval.requested, governance.approval.decided, conto_pay.request.received, conto_pay.request.paid, conto_pay.request.rejected, conto_pay.request.expired, conto_pay.request.cancelled, conto_pay.request.reminder are available on WEBHOOK channels only."},"NotificationChannel":{"type":"object","properties":{"id":{"type":"string"},"channelType":{"type":"string","enum":["EMAIL","SLACK","TELEGRAM","WHATSAPP","WEBHOOK"],"description":"Delivery channel. Fixed after the channel is created."},"name":{"type":"string"},"destination":{"anyOf":[{"type":"object","properties":{"recipients":{"type":"array","items":{"type":"string"}}},"required":["recipients"],"title":"EMAIL"},{"type":"object","properties":{"channelId":{"type":["string","null"]}},"required":["channelId"],"title":"SLACK"},{"type":"object","properties":{"chatId":{"type":["string","null"]}},"required":["chatId"],"title":"TELEGRAM"},{"type":"object","properties":{"phoneNumberId":{"type":["string","null"]},"recipientNumbers":{"type":"array","items":{"type":"string"}}},"required":["phoneNumberId","recipientNumbers"],"title":"WHATSAPP"},{"type":"object","properties":{"url":{"type":["string","null"]}},"required":["url"],"title":"WEBHOOK"}],"description":"Where notifications go. Secrets and tokens are never returned."},"eventTypes":{"type":"array","items":{"$ref":"#/components/schemas/NotificationEventType"}},"isActive":{"type":"boolean"},"lastDeliveryAt":{"type":["string","null"],"format":"date-time"},"needsAttention":{"type":"boolean","description":"True when the most recent delivery to this channel failed."}},"required":["id","channelType","name","destination","eventTypes","isActive","lastDeliveryAt","needsAttention"]},"CreateNotificationChannelRequest":{"type":"object","properties":{"channelType":{"type":"string","enum":["EMAIL","SLACK","TELEGRAM","WHATSAPP","WEBHOOK"],"description":"Delivery channel. Fixed after the channel is created."},"name":{"type":"string","minLength":1,"maxLength":100},"config":{"anyOf":[{"type":"object","properties":{"recipients":{"type":"array","items":{"type":"string","maxLength":320,"format":"email"},"minItems":1,"maxItems":100}},"required":["recipients"],"additionalProperties":false,"title":"EMAIL"},{"type":"object","properties":{"botToken":{"type":"string","minLength":1,"maxLength":4096,"description":"Slack bot token. Write-only."},"channelId":{"type":"string","minLength":1,"maxLength":2048}},"required":["botToken","channelId"],"additionalProperties":false,"title":"SLACK"},{"type":"object","properties":{"botToken":{"type":"string","minLength":1,"maxLength":4096,"description":"Telegram bot token. Write-only."},"chatId":{"type":"string","minLength":1,"maxLength":2048},"secretToken":{"type":"string","minLength":1,"maxLength":4096,"description":"Secret token set on your Telegram bot webhook. Conto uses it to verify callbacks. Write-only."}},"required":["botToken","chatId","secretToken"],"additionalProperties":false,"title":"TELEGRAM"},{"type":"object","properties":{"phoneNumberId":{"type":"string","minLength":1,"maxLength":2048},"accessToken":{"type":"string","minLength":1,"maxLength":4096,"description":"WhatsApp access token. Write-only."},"recipientNumbers":{"type":"array","items":{"type":"string","minLength":1,"maxLength":2048},"minItems":1,"maxItems":100}},"required":["phoneNumberId","accessToken","recipientNumbers"],"additionalProperties":false,"title":"WHATSAPP"},{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"format":"uri","description":"Public HTTPS endpoint."},"secret":{"type":"string","minLength":1,"maxLength":4096,"description":"Signing secret used to sign each delivery. Write-only."}},"required":["url","secret"],"additionalProperties":false,"title":"WEBHOOK"}],"description":"Destination settings. The shape depends on `channelType`."},"eventTypes":{"type":"array","items":{"$ref":"#/components/schemas/NotificationEventType"},"minItems":1,"maxItems":25,"description":"Events to deliver. Defaults to `[\"approval.requested\"]`."},"isActive":{"type":"boolean","description":"Defaults to true."}},"required":["channelType","name","config"],"additionalProperties":false},"UpdateNotificationChannelRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"config":{"type":"object","additionalProperties":{},"description":"Fields to change in the destination settings for this channel type. Omit a secret field, or send `\"[redacted]\"`, to keep the stored value."},"eventTypes":{"type":"array","items":{"$ref":"#/components/schemas/NotificationEventType"},"minItems":1,"maxItems":25},"isActive":{"type":"boolean"}},"additionalProperties":false,"description":"Send at least one field. The channel type cannot change."},"OrganizationMember":{"type":"object","properties":{"id":{"type":"string","description":"Membership ID. Use it as `ownerMembershipId` when creating an agent, or as a named reviewer in an approval workflow."},"role":{"type":"string","enum":["OWNER","ADMIN","MANAGER","VIEWER","MEMBER"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":"string"},"image":{"type":["string","null"]}},"required":["id","name","email","image"]}},"required":["id","role","createdAt","updatedAt","user"]},"PaymentRequestResponse":{"type":"object","properties":{"requestId":{"type":"string","description":"Use this ID to execute or check status"},"status":{"type":"string","enum":["APPROVED","DENIED","REQUIRES_APPROVAL","PROCESSING","COMPLETED"]},"amount":{"type":"number"},"currency":{"type":"string"},"recipient":{"type":"string"},"custodyMode":{"type":"string","enum":["MANAGED","EXTERNAL","SMART_CONTRACT"],"description":"Normalized custody model for the selected wallet. Provider-specific implementation details are not exposed."},"expiresAt":{"type":"string","format":"date-time","description":"Approval expires after 5 minutes"},"reasons":{"type":"array","items":{"type":"string"},"description":"Customer-facing explanation when action is required or the payment is denied"},"approvalRequestId":{"type":"string","description":"Approval workflow reference when a team decision is required"},"statusUrl":{"type":"string","description":"Stable URL for polling and reconciliation"},"actionUrl":{"type":"string","description":"Next URL to follow for the returned status"},"receipt":{"type":"object","properties":{"transactionId":{"type":"string"},"txHash":{"type":"string","description":"Absent for simulated payments"},"settlementMode":{"type":"string","enum":["live","test"]},"explorerUrl":{"type":"string"}},"required":["transactionId","settlementMode"]},"error":{"type":"string"}},"required":["requestId","status","amount","currency","recipient","reasons","statusUrl"],"additionalProperties":false},"Urgency":{"type":"string","enum":["LOW","NORMAL","HIGH","CRITICAL"],"default":"NORMAL"},"PaymentInvoiceContext":{"type":"object","properties":{"vendorId":{"type":"string","maxLength":255},"vendorAddress":{"type":"string","maxLength":255},"id":{"type":"string","maxLength":255},"hash":{"type":"string","maxLength":255},"sourceUrl":{"type":"string","maxLength":2048},"payload":{},"expectedAmount":{"anyOf":[{"type":"number"},{"type":"string","maxLength":255}]},"currency":{"type":"string","maxLength":50},"dueDate":{"type":"string","maxLength":255}},"additionalProperties":false},"PaymentContext":{"type":"object","properties":{"invoice":{"$ref":"#/components/schemas/PaymentInvoiceContext"},"department":{"type":"string","minLength":1,"maxLength":100},"project":{"type":"string","minLength":1,"maxLength":100},"recipientCountry":{"type":"string","pattern":"^[A-Za-z]{2}$"}},"additionalProperties":false},"PaymentRequest":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0,"description":"Amount in USDC","example":50},"recipientAddress":{"type":"string","description":"Recipient wallet address (EVM or Solana)","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f2e3a1"},"recipientName":{"type":"string","maxLength":100,"description":"Human-readable recipient name"},"purpose":{"type":"string","maxLength":500,"description":"Payment reason"},"category":{"type":"string","maxLength":50,"description":"Spend category (e.g. VENDOR, API_PROVIDER, SAAS)"},"urgency":{"$ref":"#/components/schemas/Urgency"},"context":{"$ref":"#/components/schemas/PaymentContext"},"walletId":{"type":"string"},"autoExecute":{"type":"boolean","description":"Auto-execute if approved"},"targetContractAddress":{"type":"string","description":"Target contract address for contract allowlist policy checks"},"functionSelector":{"type":"string","description":"4-byte function selector for contract interaction policy checks"},"idempotencyKey":{"type":"string","description":"Client-supplied key for safe retries"}},"required":["amount","recipientAddress"],"additionalProperties":false},"PaymentStatusResponse":{"type":"object","properties":{"requestId":{"type":"string"},"settlementMode":{"type":"string","enum":["live","test","unknown"]},"status":{"type":"string","enum":["approved","declined","review_required","reconciliation_required","processing","completed","failed","expired"],"description":"Customer-facing payment state. reconciliation_required means the execution outcome is ambiguous and must not be retried until an operator resolves it."},"amount":{"type":"number"},"currency":{"type":"string"},"recipient":{"type":"string"},"recipientName":{"type":["string","null"]},"purpose":{"type":["string","null"]},"category":{"type":["string","null"]},"expiresAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"reasons":{"type":"array","items":{"type":"string"},"description":"Customer-facing reasons for a declined payment or a pending review. Empty for other states."},"action":{"type":"null"},"transaction":{"type":["object","null"],"properties":{"id":{"type":"string"},"txHash":{"type":["string","null"]},"settlementMode":{"type":"string","enum":["live","test","unknown"]},"status":{"type":"string","enum":["processing","completed","failed"]},"confirmedAt":{"type":["string","null"],"format":"date-time"},"blockNumber":{"type":["integer","null"]},"chain":{"type":"object","properties":{"type":{"type":"string","enum":["evm","solana"]},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"explorerUrl":{"type":["string","null"],"format":"uri"},"detailsUrl":{"type":"string"}},"required":["id","txHash","settlementMode","status","confirmedAt","blockNumber","chain","explorerUrl","detailsUrl"],"additionalProperties":false}},"required":["requestId","settlementMode","status","amount","currency","recipient","recipientName","purpose","category","expiresAt","createdAt","reasons","action","transaction"],"additionalProperties":false},"PaymentExecuteResponse":{"type":"object","properties":{"requestId":{"type":"string"},"status":{"type":"string","enum":["processing","completed"]},"alreadyExecuted":{"type":"boolean","description":"True when the payment was already executed, for example when an approver approved it in Conto. The receipt is the existing one and nothing was sent again."},"amount":{"type":"number"},"currency":{"type":"string"},"recipient":{"type":"string"},"receipt":{"type":"object","properties":{"transactionId":{"type":"string"},"txHash":{"type":"string","description":"Absent for simulated payments"},"settlementMode":{"type":"string","enum":["live","test"]},"explorerUrl":{"type":"string"}},"required":["transactionId","settlementMode"],"additionalProperties":false}},"required":["requestId","status","amount","currency","recipient","receipt"],"additionalProperties":false},"PaymentExecuteError":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","description":"Stable error code, for example POLICY_DENIED_AT_EXECUTION, POLICY_REAPPROVAL_REQUIRED, PAYMENT_DENIED, APPROVAL_PENDING, PAYMENT_PROCESSING, LIMIT_EXCEEDED, INSUFFICIENT_BALANCE, EXPIRED, or NEEDS_RECONCILIATION."},"reasons":{"type":"array","items":{"type":"string"},"description":"Customer-facing reasons when the payment was declined or held"},"statusUrl":{"type":"string"}},"required":["error","code"]},"SdkAgentProfile":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","PAUSED","SUSPENDED"]},"agentType":{"type":"string"},"description":{"type":["string","null"]},"publicKey":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"lastActiveAt":{"type":["string","null"],"format":"date-time"},"summary":{"type":"object","properties":{"walletCount":{"type":"integer"},"totalBalance":{"type":"number"},"totalDailyLimit":{"type":["number","null"]},"totalSpentToday":{"type":"number"},"remainingDaily":{"type":["number","null"]},"transactionsToday":{"type":"integer"},"transactionsThisWeek":{"type":"integer"},"volumeToday":{"type":"number"},"activeAlerts":{"type":"integer"},"totalTransactions":{"type":"integer"},"totalAlerts":{"type":"integer"}},"required":["walletCount","totalBalance","totalDailyLimit","totalSpentToday","remainingDaily","transactionsToday","transactionsThisWeek","volumeToday","activeAlerts","totalTransactions","totalAlerts"]}},"required":["id","name","status","agentType","publicKey","createdAt","lastActiveAt","summary"]},"SdkSelfInspectionScopeError":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["INSUFFICIENT_SCOPE"]},"message":{"type":"string"},"requiredScope":{"type":"string","enum":["agents:read"]},"actor":{"type":"string","enum":["owner"],"description":"Who can fix it. Only an organization owner can replace the key."},"nextAction":{"type":"string"},"requestId":{"type":"string"}},"required":["error","code","message","requiredScope","actor","nextAction"],"additionalProperties":false,"description":"The SDK key lacks agents:read. Conto does not add scopes to an existing key. An organization owner must generate a new key for the agent."},"SdkWalletList":{"type":"object","properties":{"wallets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"},"chainType":{"type":"string"},"chainId":{"type":"string"},"status":{"type":"string"},"balance":{"type":"number"},"limits":{"type":"object","properties":{"perTransaction":{"type":["number","null"]},"daily":{"type":["number","null"]},"weekly":{"type":["number","null"]},"monthly":{"type":["number","null"]}},"required":["perTransaction","daily","weekly","monthly"]},"spent":{"type":"object","properties":{"today":{"type":"number"},"thisWeek":{"type":"number"},"thisMonth":{"type":"number"}},"required":["today","thisWeek","thisMonth"]},"remaining":{"type":"object","properties":{"daily":{"type":["number","null"]},"weekly":{"type":["number","null"]},"monthly":{"type":["number","null"]}},"required":["daily","weekly","monthly"]},"timeRestrictions":{"type":"object","properties":{"allowedDays":{"type":["array","null"],"items":{"type":"string"}},"allowedHoursStart":{"type":["integer","null"]},"allowedHoursEnd":{"type":["integer","null"]}},"required":["allowedDays","allowedHoursStart","allowedHoursEnd"]}},"required":["id","name","address","chainType","chainId","status","balance","limits","spent","remaining","timeRestrictions"]}},"totalBalance":{"type":"number"}},"required":["wallets","totalBalance"]},"SdkWalletDetails":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"},"chainType":{"type":"string"},"chainId":{"type":"string"},"status":{"type":"string"},"balance":{"type":"number"},"limits":{"type":"object","properties":{"perTransaction":{"type":["number","null"]},"daily":{"type":["number","null"]},"weekly":{"type":["number","null"]},"monthly":{"type":["number","null"]}},"required":["perTransaction","daily","weekly","monthly"]},"spent":{"type":"object","properties":{"today":{"type":"number"},"thisWeek":{"type":"number"},"thisMonth":{"type":"number"}},"required":["today","thisWeek","thisMonth"]},"remaining":{"type":"object","properties":{"daily":{"type":["number","null"]},"weekly":{"type":["number","null"]},"monthly":{"type":["number","null"]}},"required":["daily","weekly","monthly"]},"timeRestrictions":{"type":"object","properties":{"allowedDays":{"type":["array","null"],"items":{"type":"string"}},"allowedHoursStart":{"type":["integer","null"]},"allowedHoursEnd":{"type":["integer","null"]}},"required":["allowedDays","allowedHoursStart","allowedHoursEnd"]}},"required":["id","name","address","chainType","chainId","status","balance","limits","spent","remaining","timeRestrictions"]},"SdkTransaction":{"type":"object","properties":{"id":{"type":"string"},"txHash":{"type":["string","null"]},"settlementMode":{"type":"string","enum":["live","test","unknown"]},"kind":{"type":"string","enum":["agent_to_agent","merchant","external","service","incoming","other"]},"amount":{"type":"number"},"currency":{"type":"string"},"fromAddress":{"type":"string"},"toAddress":{"type":"string"},"merchantName":{"type":["string","null"]},"merchantCategory":{"type":["string","null"]},"status":{"type":"string","enum":["PENDING","CONFIRMING","CONFIRMED","FAILED","UNKNOWN"]},"authorizationDecision":{"type":"string","enum":["approved","review_required","declined","pending"]},"purpose":{"type":["string","null"]},"initiatedAt":{"type":"string","format":"date-time"},"confirmedAt":{"type":["string","null"],"format":"date-time"},"failedAt":{"type":["string","null"],"format":"date-time"},"sourceWallet":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"}},"required":["id","name","address"],"additionalProperties":false},"recipientAgent":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"chain":{"type":"object","properties":{"type":{"type":"string","enum":["evm","solana"]},"id":{"type":"string"},"blockNumber":{"type":["integer","null"]},"explorerUrl":{"type":["string","null"],"format":"uri"}},"required":["type","id","blockNumber","explorerUrl"],"additionalProperties":false}},"required":["id","txHash","settlementMode","kind","amount","currency","fromAddress","toAddress","merchantName","merchantCategory","status","authorizationDecision","purpose","initiatedAt","confirmedAt","failedAt","sourceWallet","recipientAgent","chain"],"additionalProperties":false},"Pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]},"SdkTransactionList":{"type":"object","properties":{"agentId":{"type":"string"},"transactions":{"type":"array","items":{"$ref":"#/components/schemas/SdkTransaction"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["agentId","transactions","pagination"]},"Alert":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"message":{"type":"string"},"kind":{"type":"string","enum":["approval","payment_request","general"]},"severity":{"type":"object","properties":{"label":{"type":"string","enum":["Low","Medium","High"]},"tone":{"type":"string","enum":["secondary","warning","destructive"]}},"required":["label","tone"]},"status":{"type":"object","properties":{"value":{"type":"string","enum":["open","in_review","resolved","dismissed"]},"label":{"type":"string","enum":["Open","In review","Resolved","Dismissed"]},"tone":{"type":"string","enum":["destructive","warning","success","secondary"]}},"required":["value","label","tone"]},"createdAt":{"type":"string","format":"date-time"},"agent":{"type":["object","null"],"properties":{"name":{"type":"string"},"href":{"type":"string"}},"required":["name","href"]},"amount":{"type":["number","null"]},"reviewUrl":{"type":["string","null"]}},"required":["id","title","message","kind","severity","status","createdAt","agent","amount","reviewUrl"]},"SdkTransactionDetails":{"type":"object","properties":{"id":{"type":"string"},"txHash":{"type":["string","null"]},"settlementMode":{"type":"string","enum":["live","test","unknown"]},"kind":{"type":"string","enum":["agent_to_agent","merchant","external","service","incoming","other"]},"amount":{"type":"number"},"currency":{"type":"string"},"fromAddress":{"type":"string"},"toAddress":{"type":"string"},"merchantName":{"type":["string","null"]},"merchantCategory":{"type":["string","null"]},"status":{"type":"string","enum":["PENDING","CONFIRMING","CONFIRMED","FAILED","UNKNOWN"]},"authorizationDecision":{"type":"string","enum":["approved","review_required","declined","pending"]},"purpose":{"type":["string","null"]},"initiatedAt":{"type":"string","format":"date-time"},"confirmedAt":{"type":["string","null"],"format":"date-time"},"failedAt":{"type":["string","null"],"format":"date-time"},"sourceWallet":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"}},"required":["id","name","address"],"additionalProperties":false},"recipientAgent":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"chain":{"type":"object","properties":{"type":{"type":"string","enum":["evm","solana"]},"id":{"type":"string"},"blockNumber":{"type":["integer","null"]},"explorerUrl":{"type":["string","null"],"format":"uri"}},"required":["type","id","blockNumber","explorerUrl"],"additionalProperties":false},"alerts":{"type":"array","items":{"$ref":"#/components/schemas/Alert"}}},"required":["id","txHash","settlementMode","kind","amount","currency","fromAddress","toAddress","merchantName","merchantCategory","status","authorizationDecision","purpose","initiatedAt","confirmedAt","failedAt","sourceWallet","recipientAgent","chain","alerts"],"additionalProperties":false},"SdkPolicyList":{"type":"object","properties":{"policies":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"policyType":{"type":"string"},"priority":{"type":"integer"},"isActive":{"type":"boolean"},"scope":{"type":"string","enum":["organization","assigned"]},"appliesVia":{"type":"array","items":{"type":"string","enum":["organization","agent","wallet"]}},"assignedVia":{"type":"string","enum":["agent","wallet","organization"]},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"ruleType":{"type":"string"},"operator":{"type":"string"},"value":{"type":"string"},"action":{"type":"string","enum":["ALLOW","DENY","REQUIRE_APPROVAL"]}},"required":["id","ruleType","operator","value","action"]}}},"required":["id","name","policyType","priority","isActive","scope","appliesVia","assignedVia","rules"]}}},"required":["policies"]},"SetupDiagnosticAction":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["command"]},"command":{"type":"string","example":"npx @conto_finance/create-conto-agent --sandbox"},"description":{"type":"string"}},"required":["type","command","description"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["api"]},"method":{"type":"string","enum":["GET","POST","PATCH"]},"href":{"type":"string","description":"Path relative to the Conto base URL. Segments in braces, such as {requestId}, are placeholders.","example":"/api/sdk/payments/approve"},"credential":{"type":"string","enum":["sdk_key","sandbox_api_key","organization_api_key"],"description":"The credential that authorizes the call. `sdk_key` is the agent key. `sandbox_api_key` is the read-only key an anonymous sandbox returns. `organization_api_key` belongs to an owner."},"requiredScope":{"type":["string","null"]},"description":{"type":"string"}},"required":["type","method","href","credential","requiredScope","description"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["owner_url"]},"url":{"type":"string","description":"A dashboard page, relative to the Conto base URL.","example":"/agents/cmm59z8fj000l49h7bjqza11p?tab=wallets"},"description":{"type":"string"}},"required":["type","url","description"],"additionalProperties":false}]},"SetupDiagnosticIssue":{"type":"object","properties":{"code":{"type":"string","enum":["AGENT_PAUSED","AGENT_FROZEN","AGENT_UNAVAILABLE","SDK_KEY_EXPIRED","SDK_KEY_REVOKED","SCOPE_MISSING","NO_WALLET","WALLET_PAUSED","WALLET_UNAVAILABLE","WALLET_VIEW_ONLY","WALLET_UNFUNDED","MAINNET_REQUIRES_PROD_AGENT","LIVE_PAYMENTS_PAUSED","LIVE_PAYMENTS_UNAVAILABLE","EXTERNAL_SIGNER_REQUIRED","SANDBOX_UNCLAIMED","SANDBOX_EXPIRED"],"description":"Stable issue code. New codes may be added. Handle an unknown code by its severity and actor."},"severity":{"type":"string","enum":["error","warning","info"],"description":"`error` blocks a capability of the affected resource. `warning` may cause failures. `info` explains how a path works."},"actor":{"type":"string","enum":["agent","owner"],"description":"Who can resolve it: the agent with its own credentials, or an owner."},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["agent","wallet","sdk_key","organization"]},"id":{"type":["string","null"]}},"required":["type","id"],"additionalProperties":false},"message":{"type":"string"},"requiredScope":{"type":["string","null"],"description":"Set for SCOPE_MISSING."},"actions":{"type":"array","items":{"$ref":"#/components/schemas/SetupDiagnosticAction"}}},"required":["code","severity","actor","resource","message","requiredScope","actions"],"additionalProperties":false},"SetupDiagnostics":{"type":"object","properties":{"version":{"type":"string","enum":["conto.setup-diagnostics.v1"]},"environment":{"type":["object","null"],"properties":{"kind":{"type":"string","enum":["anonymous_sandbox","claimed_sandbox","account"],"description":"`anonymous_sandbox` and `claimed_sandbox` are test-only: every payment is simulated and claiming does not enable live payments."},"settlement":{"type":"string","enum":["simulated","per_wallet"],"description":"`per_wallet` means each wallet reports its own execution mode."},"agentEnvironment":{"type":"string","enum":["DEV","STAGING","PROD"]},"sandboxExpiresAt":{"type":["string","null"],"format":"date-time","description":"When an anonymous sandbox and its credentials expire."}},"required":["kind","settlement","agentEnvironment","sandboxExpiresAt"],"additionalProperties":false},"status":{"type":"object","properties":{"authenticated":{"type":"boolean"},"canRequest":{"type":"string","enum":["yes","no","unknown"],"description":"`unknown` means Conto has no evidence either way, such as an external signer."},"canExecute":{"type":"string","enum":["yes","no","unknown"],"description":"`unknown` means Conto has no evidence either way, such as an external signer."},"ownerActionRequired":{"type":"boolean","description":"True when an error-severity issue needs an owner."}},"required":["authenticated","canRequest","canExecute","ownerActionRequired"],"additionalProperties":false},"wallets":{"type":"array","items":{"type":"object","properties":{"walletId":{"type":"string"},"executionMode":{"type":"string","enum":["simulated","managed","external","unknown"],"description":"`simulated`: sandbox payments, no funds move. `managed`: Conto executes from a managed wallet. `external`: the agent signs and sends, then confirms. `unknown`: Conto does not execute from this wallet."},"network":{"type":"string","enum":["testnet","mainnet"]},"funding":{"type":"string","enum":["not_required","funded","unfunded","not_checked"],"description":"`not_checked` means Conto does not read this wallet balance."},"walletLimits":{"type":"boolean","description":"Whether the agent-wallet link has a spend limit."},"canRequest":{"type":"string","enum":["yes","no","unknown"],"description":"`unknown` means Conto has no evidence either way, such as an external signer."},"canExecute":{"type":"string","enum":["yes","no","unknown"],"description":"`unknown` means Conto has no evidence either way, such as an external signer."},"issueCodes":{"type":"array","items":{"type":"string","enum":["AGENT_PAUSED","AGENT_FROZEN","AGENT_UNAVAILABLE","SDK_KEY_EXPIRED","SDK_KEY_REVOKED","SCOPE_MISSING","NO_WALLET","WALLET_PAUSED","WALLET_UNAVAILABLE","WALLET_VIEW_ONLY","WALLET_UNFUNDED","MAINNET_REQUIRES_PROD_AGENT","LIVE_PAYMENTS_PAUSED","LIVE_PAYMENTS_UNAVAILABLE","EXTERNAL_SIGNER_REQUIRED","SANDBOX_UNCLAIMED","SANDBOX_EXPIRED"]}}},"required":["walletId","executionMode","network","funding","walletLimits","canRequest","canExecute","issueCodes"],"additionalProperties":false}},"connectedCards":{"type":["object","null"],"properties":{"test":{"type":"object","properties":{"availability":{"type":"string","enum":["available","unavailable"]},"reason":{"type":["string","null"],"enum":["sandbox_organization","disabled","plan"],"description":"Why cards of this environment are unavailable to the organization. Null when available."},"assignedCards":{"type":"integer","minimum":0},"activeAuthorizations":{"type":"integer","minimum":0},"canUse":{"type":"string","enum":["yes","no"]}},"required":["availability","reason","assignedCards","activeAuthorizations","canUse"],"additionalProperties":false},"live":{"type":"object","properties":{"availability":{"type":"string","enum":["available","unavailable"]},"reason":{"type":["string","null"],"enum":["sandbox_organization","disabled","plan"],"description":"Why cards of this environment are unavailable to the organization. Null when available."},"assignedCards":{"type":"integer","minimum":0},"activeAuthorizations":{"type":"integer","minimum":0},"canUse":{"type":"string","enum":["yes","no"]}},"required":["availability","reason","assignedCards","activeAuthorizations","canUse"],"additionalProperties":false}},"required":["test","live"],"additionalProperties":false,"description":"Test cards and live cards, reported apart from wallets. Either can be ready without the other."},"controls":{"type":["object","null"],"properties":{"effectivePolicies":{"type":"integer","minimum":0,"description":"Policies listed in `policies`. Zero does not mean uncontrolled: wallet limits and other organization controls can still apply."}},"required":["effectivePolicies"],"additionalProperties":false},"issues":{"type":"array","items":{"$ref":"#/components/schemas/SetupDiagnosticIssue"}}},"required":["version","environment","status","wallets","connectedCards","controls","issues"],"additionalProperties":false,"description":"Versioned setup diagnostics. `version` changes only for a breaking change. New fields and issue codes can appear within a version."},"SdkSetupAuthError":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"},"diagnostics":{"allOf":[{"$ref":"#/components/schemas/SetupDiagnostics"},{"description":"Present when the key is recognized but cannot authenticate: a paused, frozen, or revoked agent, or an expired or revoked key."}]}},"required":["error","code","message"],"additionalProperties":false},"X402PreAuthorizeRequest":{"type":"object","properties":{"amount":{"type":"number","description":"Payment amount in USDC"},"recipientAddress":{"type":"string","description":"Recipient wallet address from the x402 challenge","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f2e3a1"},"resourceUrl":{"type":"string","format":"uri","description":"Target API endpoint URL"},"facilitator":{"type":"string","description":"Facilitator URL or identifier used by allowlist controls"},"scheme":{"type":"string","description":"x402 payment scheme"},"sessionId":{"type":"string","minLength":1,"maxLength":255,"description":"Customer-supplied ID used to group related x402 payments"},"paymentId":{"type":"string","description":"Stable x402 payment ID"},"payerAddress":{"type":"string","description":"Exact active agent wallet address that will sign the payment","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f2e3a1"},"network":{"type":"string","description":"CAIP-2 settlement network from the x402 challenge","example":"eip155:8453"},"context":{"type":"object","properties":{"department":{"type":"string"},"project":{"type":"string"}},"additionalProperties":false}},"required":["amount","recipientAddress","resourceUrl"],"additionalProperties":false},"X402PayRequest":{"type":"object","properties":{"amount":{"type":"number","description":"Payment amount in USDC"},"recipientAddress":{"type":"string","description":"Recipient wallet address from the x402 challenge. Must equal payTo.","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f2e3a1"},"resourceUrl":{"type":"string","format":"uri","description":"Target API endpoint URL"},"facilitator":{"type":"string","description":"Facilitator URL or identifier used by allowlist controls"},"scheme":{"type":"string","description":"x402 payment scheme"},"sessionId":{"type":"string","minLength":1,"maxLength":255,"description":"Customer-supplied ID used to group related x402 payments"},"paymentId":{"type":"string","description":"Stable x402 payment ID"},"payerAddress":{"type":"string","description":"Exact Privy-managed agent wallet address Conto signs with","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f2e3a1"},"network":{"type":"string","description":"CAIP-2 settlement network from the x402 challenge","example":"eip155:8453"},"context":{"type":"object","properties":{"department":{"type":"string"},"project":{"type":"string"}},"additionalProperties":false},"x402Version":{"type":"integer","description":"x402 protocol version of the challenge: 1 (default) or 2"},"paymentRequirements":{"type":"object","properties":{"scheme":{"type":"string","description":"Must be \"exact\"","example":"exact"},"network":{"type":"string","description":"Network from the challenge: CAIP-2 or an x402 v1 name such as \"base\"","example":"base"},"maxAmountRequired":{"type":"string","description":"v1: amount in token base units. Must equal amount.","example":"420000"},"amount":{"type":"string","description":"v2: amount in token base units. Must equal amount."},"asset":{"type":"string","description":"Token contract. Must be managed USDC."},"payTo":{"type":"string","description":"Payee. Must equal recipientAddress."},"maxTimeoutSeconds":{"type":"integer","description":"Upper bound for the authorization validity window","example":60},"resource":{"type":"string"},"extra":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"}},"description":"EIP-712 domain name and version of the token"}},"required":["scheme","network","asset","payTo","maxTimeoutSeconds"],"description":"The accepted entry from the 402 challenge"}},"required":["amount","recipientAddress","resourceUrl","paymentRequirements"],"additionalProperties":false},"X402RecordRequest":{"type":"object","properties":{"amount":{"type":"number","description":"Total payment amount"},"currency":{"type":"string","description":"Payment currency symbol"},"recipientAddress":{"type":"string","description":"Recipient wallet address from the x402 challenge","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f2e3a1"},"txHash":{"type":"string","description":"Confirmed onchain transaction hash"},"resourceUrl":{"type":"string","format":"uri","description":"API endpoint URL"},"paymentId":{"type":"string","description":"Stable payment identifier"},"sessionId":{"type":"string","minLength":1,"maxLength":255,"description":"Customer-supplied ID used to group related x402 payments"},"payerAddress":{"type":"string","description":"Exact active agent wallet address that signed the payment","example":"0x742d35Cc6634C0532925a3b844Bc9e7595f2e3a1"},"network":{"type":"string","description":"CAIP-2 settlement network from the x402 challenge","example":"eip155:8453"},"context":{"type":"object","properties":{"department":{"type":"string"},"project":{"type":"string"}},"additionalProperties":false},"batchItems":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"number"},"resourceUrl":{"type":"string","format":"uri"},"paymentId":{"type":"string"}},"required":["amount","resourceUrl","paymentId"]},"description":"Optional batch of individual x402 calls"},"grantId":{"type":"string","description":"Grant ID returned by an approved pre-authorize. A record without a valid, unexpired grant is accepted as a policy bypass: the transaction is flagged and a critical alert is raised. An organization can also configure Conto to freeze the agent automatically."},"grantSignature":{"type":"string","description":"Grant signature returned by pre-authorize, sent back unchanged"}},"required":["amount","recipientAddress","txHash","resourceUrl","paymentId"],"additionalProperties":false},"PurchaseItem":{"type":"object","properties":{"url":{"type":"string","format":"uri","example":"https://shop.example.com/products/tee"},"title":{"type":"string","example":"Black tee"},"quantity":{"type":"integer","minimum":1,"maximum":10,"example":1},"options":{"type":"array","items":{"type":"string"},"maxItems":6,"example":["Black","M"]}},"required":["url"]},"PurchaseGroceryItem":{"type":"object","properties":{"label":{"type":"string","maxLength":60,"example":"Bananas"},"query":{"type":"string","maxLength":100,"description":"Plain search words. No prices, quantities or package sizes.","example":"bananas"},"quantity":{"type":"integer","minimum":1,"maximum":20,"example":1},"size":{"type":"string","maxLength":40,"example":"1 pint"},"unit":{"type":"string","maxLength":20,"example":"bunch"},"brand":{"type":"string","maxLength":40,"example":"Organic Valley"},"exclude":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":8,"description":"Words the item must not match.","example":["organic"]}},"required":["label","query","quantity"]},"PurchaseGroceryList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseGroceryItem"},"minItems":1,"maxItems":20}},"required":["items"],"description":"Groceries to find at one grocery store: an Instacart store link, or Conto Test Grocery in test mode. Conto searches the store for each item and never substitutes a different product. Not with items."},"PurchaseMoney":{"type":"object","properties":{"amountMinor":{"type":"integer","exclusiveMinimum":0,"example":7500},"currency":{"type":"string","description":"Uppercase ISO 4217. USD only.","example":"USD"}},"required":["amountMinor","currency"]},"PurchaseAction":{"type":["object","null"],"properties":{"id":{"type":"string","example":"cmm59z8fj000p49h7bjqza11t"},"kind":{"type":"string","enum":["buyer_details","purchase_review","organization_approval","card_verification","merchant_signin","merchant_challenge","budget_increase"]},"authority":{"type":"string","enum":["agent_or_buyer","buyer","cardholder","organization"],"description":"Only agent_or_buyer accepts an agent response. Others are completed by the buyer, the cardholder or an organization reviewer."},"revision":{"type":"integer"},"expiresAt":{"type":"string","format":"date-time"},"form":{"type":"string","enum":["delivery","billing","store_order_contact"]},"fields":{"type":"array","items":{"type":"string"}},"budget":{"type":"object","properties":{"estimate":{"$ref":"#/components/schemas/PurchaseMoney"},"maximum":{"$ref":"#/components/schemas/PurchaseMoney"},"maxCost":{"$ref":"#/components/schemas/PurchaseMoney"}},"required":["estimate","maximum","maxCost"],"description":"budget_increase only: the maximum is above maxCost. Answer { decision: \"raise\", maxCostMinor } with at least the maximum, or { decision: \"decline\" }."},"url":{"type":"string","format":"uri","description":"Conto page for a buyer or reviewer action. It works only inside a hosted buyer session or the organization dashboard."}},"required":["id","kind","authority","revision","expiresAt"]},"Purchase":{"type":"object","properties":{"id":{"type":"string","example":"cmm59z8fj000o49h7bjqza11s"},"object":{"type":"string","enum":["purchase"]},"buyerId":{"type":"string"},"agentId":{"type":"string"},"environment":{"type":"string","enum":["live","test"]},"status":{"type":"string","enum":["queued","running","awaiting_action","submitting","reconciling","succeeded","blocked","failed","cancelled"],"description":"succeeded means a merchant-confirmed order. Settlement is reported separately."},"phase":{"type":"string","enum":["queued","shopping","checkout","review","scheduled","authorization","payment","reconciliation","closed_unconfirmed","complete"]},"version":{"type":"integer","description":"Increases by one with every visible change."},"request":{"type":"object","properties":{"url":{"type":"string"},"task":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseItem"}},"groceryList":{"$ref":"#/components/schemas/PurchaseGroceryList"}},"required":["url"]},"maxCost":{"$ref":"#/components/schemas/PurchaseMoney"},"quote":{"type":["object","null"],"properties":{"merchant":{"type":"string"},"description":{"type":["string","null"]},"total":{"allOf":[{"$ref":"#/components/schemas/PurchaseMoney"},{"description":"What limits and the card are held to: the maximum, until a receipt records the final total."}]},"estimate":{"allOf":[{"$ref":"#/components/schemas/PurchaseMoney"},{"description":"The store’s own total."}]},"maximum":{"allOf":[{"$ref":"#/components/schemas/PurchaseMoney"},{"description":"The most the order can come to. About 15% over the estimate for groceries, where weighed items and refunds move the total. The same as the estimate for an exact total."}]},"estimatedTax":{"type":"boolean"}},"required":["merchant","description","total","estimate","maximum","estimatedTax"]},"requiredAction":{"$ref":"#/components/schemas/PurchaseAction"},"result":{"type":["object","null"],"properties":{"outcome":{"type":"string","enum":["merchant_confirmed","checkout_reported","credential_unused","not_completed","denied","cancelled"]},"merchantReference":{"type":["string","null"]}},"required":["outcome","merchantReference"]},"paymentEvidence":{"type":"object","properties":{"authorization":{"type":"object","properties":{"state":{"type":"string","enum":["not_requested","pending_review","issued","denied","cancelled","unknown"]}},"required":["state"]},"merchant":{"type":"object","properties":{"state":{"type":"string","enum":["not_submitted","confirmed","unknown"]},"source":{"type":"string"},"reference":{"type":"string"},"amount":{"$ref":"#/components/schemas/PurchaseMoney"},"amountVerified":{"type":"boolean"},"observedAt":{"type":"string","format":"date-time"}},"required":["state"]},"settlement":{"type":"object","properties":{"state":{"type":"string","enum":["unknown"]},"reason":{"type":"string","enum":["NOT_REPORTED_BY_PROVIDER"]}},"required":["state","reason"]}},"required":["authorization","merchant","settlement"]},"progress":{"type":"object","properties":{"steps":{"type":"integer"},"message":{"type":["string","null"]}},"required":["steps","message"]},"reasonCode":{"type":["string","null"],"enum":["PURCHASES_UNAVAILABLE","LIVE_NOT_ENABLED","AGENT_LIMIT_REACHED","CREATION_PAUSED","BUYER_NOT_FOUND","BUYER_STOPPED","AGENT_NOT_BUYER_AGENT","PAYMENT_METHOD_NOT_FOUND","PAYMENT_METHOD_ENVIRONMENT_MISMATCH","DELEGATION_NOT_FOUND","DELEGATION_REVOKED","DELEGATION_INSUFFICIENT","PAYMENT_METHOD_REQUIRED","CURRENCY_UNSUPPORTED","BUYER_PROFILE_UNSUPPORTED","MERCHANT_UNSUPPORTED","PURCHASE_IN_PROGRESS","IDEMPOTENCY_CONFLICT","ALLOWANCES_UNAVAILABLE","ALLOWANCE_NOT_FOUND","ALLOWANCE_INVALID","RECURRENCE_NOT_FOUND","RECURRENCE_PAUSED","RECURRENCE_ENDED","CYCLE_TOO_SOON","CYCLE_IN_PROGRESS","COMPANY_CARDS_UNAVAILABLE","COMPANY_CARD_NOT_FOUND","BUYER_HAS_OWN_CARD","KITCHEN_CONTEXT_UNAVAILABLE","OVER_BUDGET","POLICY_DENIED","EXPIRED_BEFORE_PAYMENT","CANCELLED_BY_REQUEST","DECLINED_BY_BUYER","CHECKOUT_FAILED","SHOPPING_INTERRUPTED","ISSUANCE_PAUSED","CREDENTIAL_UNUSED","OUTCOME_UNCONFIRMED","NEEDS_OPERATOR","OPERATOR_REPORTED","ALLOWANCE_REVOKED","SKIPPED_BY_BUYER","RECURRENCE_CHANGED","DECLINED_BY_ORGANIZATION","ACTION_NOT_FOUND","ACTION_NOT_OPEN","ACTION_EXPIRED","ACTION_AUTHORITY","RESPONSE_CONFLICT","RESPONSE_REJECTED","CURSOR_INVALID"]},"limitReached":{"type":"string","enum":["buyer_daily","buyer_monthly","buyer_daily_count","store","card_or_policy"],"description":"With POLICY_DENIED on a company card: which limit refused the purchase."},"cancellation":{"type":["object","null"],"properties":{"requestedAt":{"type":"string","format":"date-time"}},"required":["requestedAt"]},"allowance":{"type":"object","properties":{"id":{"type":"string"},"reviewSkipped":{"type":"boolean"}},"required":["id","reviewSkipped"],"description":"Present when the purchase pays under one of the buyer’s open allowances. reviewSkipped is true when it went to payment without the buyer’s review."},"recurrence":{"type":"object","properties":{"id":{"type":"string"},"cycleKey":{"type":"string"},"payAt":{"type":["string","null"],"format":"date-time"},"changes":{"type":["object","null"],"properties":{"previousTotal":{"$ref":"#/components/schemas/PurchaseMoney"},"itemsChanged":{"type":"boolean"}},"required":["itemsChanged"]}},"required":["id","cycleKey","payAt","changes"],"description":"Present when the purchase is one cycle of a repeat order. While the phase is scheduled the buyer has had a heads-up, and it pays at payAt unless they skip it. changes shows the last approved total when the price moved."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","object","buyerId","agentId","environment","status","phase","version","request","maxCost","quote","requiredAction","result","paymentEvidence","progress","reasonCode","cancellation","createdAt","updatedAt","completedAt"]},"PurchaseError":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","enum":["PURCHASES_UNAVAILABLE","LIVE_NOT_ENABLED","AGENT_LIMIT_REACHED","CREATION_PAUSED","BUYER_NOT_FOUND","BUYER_STOPPED","AGENT_NOT_BUYER_AGENT","PAYMENT_METHOD_NOT_FOUND","PAYMENT_METHOD_ENVIRONMENT_MISMATCH","DELEGATION_NOT_FOUND","DELEGATION_REVOKED","DELEGATION_INSUFFICIENT","PAYMENT_METHOD_REQUIRED","CURRENCY_UNSUPPORTED","BUYER_PROFILE_UNSUPPORTED","MERCHANT_UNSUPPORTED","PURCHASE_IN_PROGRESS","IDEMPOTENCY_CONFLICT","ALLOWANCES_UNAVAILABLE","ALLOWANCE_NOT_FOUND","ALLOWANCE_INVALID","RECURRENCE_NOT_FOUND","RECURRENCE_PAUSED","RECURRENCE_ENDED","CYCLE_TOO_SOON","CYCLE_IN_PROGRESS","COMPANY_CARDS_UNAVAILABLE","COMPANY_CARD_NOT_FOUND","BUYER_HAS_OWN_CARD","KITCHEN_CONTEXT_UNAVAILABLE","OVER_BUDGET","POLICY_DENIED","EXPIRED_BEFORE_PAYMENT","CANCELLED_BY_REQUEST","DECLINED_BY_BUYER","CHECKOUT_FAILED","SHOPPING_INTERRUPTED","ISSUANCE_PAUSED","CREDENTIAL_UNUSED","OUTCOME_UNCONFIRMED","NEEDS_OPERATOR","OPERATOR_REPORTED","ALLOWANCE_REVOKED","SKIPPED_BY_BUYER","RECURRENCE_CHANGED","DECLINED_BY_ORGANIZATION","ACTION_NOT_FOUND","ACTION_NOT_OPEN","ACTION_EXPIRED","ACTION_AUTHORITY","RESPONSE_CONFLICT","RESPONSE_REJECTED","CURSOR_INVALID"]},"reasonCode":{"type":"string","enum":["PURCHASES_UNAVAILABLE","LIVE_NOT_ENABLED","AGENT_LIMIT_REACHED","CREATION_PAUSED","BUYER_NOT_FOUND","BUYER_STOPPED","AGENT_NOT_BUYER_AGENT","PAYMENT_METHOD_NOT_FOUND","PAYMENT_METHOD_ENVIRONMENT_MISMATCH","DELEGATION_NOT_FOUND","DELEGATION_REVOKED","DELEGATION_INSUFFICIENT","PAYMENT_METHOD_REQUIRED","CURRENCY_UNSUPPORTED","BUYER_PROFILE_UNSUPPORTED","MERCHANT_UNSUPPORTED","PURCHASE_IN_PROGRESS","IDEMPOTENCY_CONFLICT","ALLOWANCES_UNAVAILABLE","ALLOWANCE_NOT_FOUND","ALLOWANCE_INVALID","RECURRENCE_NOT_FOUND","RECURRENCE_PAUSED","RECURRENCE_ENDED","CYCLE_TOO_SOON","CYCLE_IN_PROGRESS","COMPANY_CARDS_UNAVAILABLE","COMPANY_CARD_NOT_FOUND","BUYER_HAS_OWN_CARD","KITCHEN_CONTEXT_UNAVAILABLE","OVER_BUDGET","POLICY_DENIED","EXPIRED_BEFORE_PAYMENT","CANCELLED_BY_REQUEST","DECLINED_BY_BUYER","CHECKOUT_FAILED","SHOPPING_INTERRUPTED","ISSUANCE_PAUSED","CREDENTIAL_UNUSED","OUTCOME_UNCONFIRMED","NEEDS_OPERATOR","OPERATOR_REPORTED","ALLOWANCE_REVOKED","SKIPPED_BY_BUYER","RECURRENCE_CHANGED","DECLINED_BY_ORGANIZATION","ACTION_NOT_FOUND","ACTION_NOT_OPEN","ACTION_EXPIRED","ACTION_AUTHORITY","RESPONSE_CONFLICT","RESPONSE_REJECTED","CURSOR_INVALID"]},"retryable":{"type":"boolean"},"requestId":{"type":"string"}},"required":["error","message","code","reasonCode","retryable"]},"CreatePurchaseRequest":{"type":"object","properties":{"buyerId":{"type":"string","example":"cmm59z8fj000l49h7bjqza11p"},"request":{"type":"object","properties":{"url":{"type":"string","format":"uri","example":"https://shop.example.com/products/tee"},"task":{"type":"string","maxLength":2000,"example":"Buy one black medium shirt with standard shipping"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseItem"},"maxItems":10},"groceryList":{"$ref":"#/components/schemas/PurchaseGroceryList"}},"required":["url"]},"maxCost":{"$ref":"#/components/schemas/PurchaseMoney"},"payment":{"type":"object","properties":{"methodId":{"type":"string","example":"cmm59z8fj000m49h7bjqza11q"},"delegationId":{"type":"string","example":"cmm59z8fj000n49h7bjqza11r"}},"required":["methodId","delegationId"],"description":"Optional when the buyer has one active delegation for the store: a test card for a Conto test store, a live card otherwise. With more than one, the request is refused with PAYMENT_METHOD_REQUIRED."},"buyerProfileId":{"type":["string","null"],"description":"The buyer’s saved delivery details answer the store’s delivery form when the buyer has them. Leave out to use them when present, pass the buyer id to require them, or null to never use them. The buyer still approves the details at review."},"idempotencyKey":{"type":"string","minLength":8,"maxLength":255,"description":"Same key and body return the same purchase.","example":"customer-order-1042"}},"required":["buyerId","request","maxCost","idempotencyKey"]},"PurchaseList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Purchase"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["items","total","limit","offset"]},"PurchaseResponseAck":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["purchase_response"]},"purchaseId":{"type":"string"},"actionId":{"type":"string"},"status":{"type":"string","enum":["accepted","applied","rejected"]},"reasonCode":{"type":["string","null"]},"acceptedAt":{"type":"string","format":"date-time"},"appliedAt":{"type":["string","null"],"format":"date-time"},"replayed":{"type":"boolean"}},"required":["id","object","purchaseId","actionId","status","reasonCode","acceptedAt","appliedAt","replayed"]},"PurchaseResponseRequest":{"type":"object","properties":{"actionId":{"type":"string"},"revision":{"type":"integer"},"fields":{"type":"object","additionalProperties":{},"description":"The fields the action lists for its form, such as delivery details. For a purchase_review the organization answers, { decision: \"approve\", totalMinor } with the quote total it saw, or { decision: \"decline\" }."}},"required":["actionId","fields"]},"PurchaseEvent":{"type":"object","properties":{"id":{"type":"string"},"purchaseId":{"type":"string"},"version":{"type":"integer"},"type":{"type":"string","example":"purchase.action_required"},"createdAt":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/Purchase"}},"required":["id","purchaseId","version","type","createdAt","data"]},"PurchaseEventList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseEvent"}},"latestVersion":{"type":"integer"},"nextCursor":{"type":"integer"},"hasMore":{"type":"boolean"}},"required":["items","latestVersion","nextCursor","hasMore"]},"PurchaseBuyer":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["buyer"]},"externalId":{"type":"string"},"agentId":{"type":"string"},"status":{"type":"string","enum":["active","stopped"]},"limits":{"type":"object","properties":{"perPurchaseMinor":{"type":"integer"},"dailyMinor":{"type":"integer"},"currency":{"type":"string","enum":["USD"]},"confirmed":{"type":"boolean"}},"required":["perPurchaseMinor","dailyMinor","currency","confirmed"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","object","externalId","agentId","status","limits","createdAt"]},"CreatePurchaseBuyerRequest":{"type":"object","properties":{"externalId":{"type":"string","minLength":1,"maxLength":200,"example":"user_8842"},"email":{"type":"string","format":"email","example":"buyer@example.com"}},"required":["externalId","email"]},"PurchaseCompanyCard":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["company_card"]},"environment":{"type":"string","enum":["live","test"]},"brand":{"type":"string"},"last4":{"type":"string"},"status":{"type":"string","enum":["active","removed"]},"limits":{"type":"object","properties":{"perPurchaseMinor":{"type":"integer","minimum":100,"maximum":100000,"description":"The most one order may cost.","example":15000},"monthlyMinor":{"type":"integer","minimum":100,"maximum":5000000,"description":"The most all buyers together may spend on the card in a month.","example":500000},"currency":{"type":"string","enum":["USD"]}},"required":["perPurchaseMinor","monthlyMinor","currency"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","object","environment","brand","last4","status","limits","createdAt"]},"CreatePurchaseCompanyCardRequest":{"type":"object","properties":{"environment":{"type":"string","enum":["live","test"],"description":"test only for now. A test company card pays Conto test stores only."},"limits":{"type":"object","properties":{"perPurchaseMinor":{"type":"integer","minimum":100,"maximum":100000,"description":"The most one order may cost.","example":15000},"monthlyMinor":{"type":"integer","minimum":100,"maximum":5000000,"description":"The most all buyers together may spend on the card in a month.","example":500000}},"required":["perPurchaseMinor","monthlyMinor"]}},"required":["environment","limits"]},"UpdatePurchaseCompanyCardRequest":{"type":"object","properties":{"limits":{"type":"object","properties":{"perPurchaseMinor":{"type":"integer","minimum":100,"maximum":100000,"description":"The most one order may cost.","example":15000},"monthlyMinor":{"type":"integer","minimum":100,"maximum":5000000,"description":"The most all buyers together may spend on the card in a month.","example":500000}},"required":["perPurchaseMinor","monthlyMinor"]}},"required":["limits"]},"PurchaseBuyerCompanyCard":{"type":"object","properties":{"object":{"type":"string","enum":["buyer_company_card"]},"buyerId":{"type":"string"},"companyCardId":{"type":"string"},"paymentMethodId":{"type":"string"},"delegationId":{"type":"string"},"limits":{"type":"object","properties":{"perPurchaseMinor":{"type":"integer","minimum":100,"maximum":100000,"example":10000},"dailyMinor":{"type":"integer","minimum":100,"maximum":100000,"example":20000},"monthlyMinor":{"type":"integer","minimum":100,"maximum":1000000,"example":60000},"reviewAboveMinor":{"type":["integer","null"]},"currency":{"type":"string","enum":["USD"]}},"required":["perPurchaseMinor","dailyMinor","monthlyMinor","reviewAboveMinor","currency"]}},"required":["object","buyerId","companyCardId","paymentMethodId","delegationId","limits"]},"PurchaseBuyerCompanyCardRequest":{"type":"object","properties":{"companyCardId":{"type":"string"},"limits":{"type":"object","properties":{"perPurchaseMinor":{"type":"integer","minimum":100,"maximum":100000,"example":10000},"dailyMinor":{"type":"integer","minimum":100,"maximum":100000,"example":20000},"monthlyMinor":{"type":"integer","minimum":100,"maximum":1000000,"example":60000},"reviewAboveMinor":{"type":"integer","minimum":0,"maximum":100000,"description":"Orders above this wait for your review through the purchase API. Left out, every order up to perPurchaseMinor goes ahead without review.","example":8000}},"required":["perPurchaseMinor","dailyMinor","monthlyMinor"]}},"required":["companyCardId","limits"]},"PurchaseKitchenInventoryItem":{"type":"object","properties":{"item":{"type":"string","minLength":1,"maxLength":120,"example":"Whole milk"},"quantity":{"type":"number","minimum":0,"maximum":10000,"example":0.5},"unit":{"type":"string","minLength":1,"maxLength":30,"example":"gallon"},"level":{"type":"string","enum":["ok","low","out"],"description":"Left out: ok, or out when quantity is 0.","example":"low"},"updatedAt":{"type":"string","format":"date-time","example":"2026-10-15T07:30:00Z"},"expiresAt":{"type":"string","format":"date-time","example":"2026-10-15T07:30:00Z"}},"required":["item"]},"PurchaseKitchenUsual":{"type":"object","properties":{"item":{"type":"string","minLength":1,"maxLength":120,"example":"Eggs"},"typicalQuantity":{"type":"number","exclusiveMinimum":0,"maximum":10000,"example":2},"unit":{"type":"string","minLength":1,"maxLength":30,"example":"dozen"},"size":{"type":"string","minLength":1,"maxLength":40,"example":"1 dozen"},"brand":{"type":"string","minLength":1,"maxLength":40,"example":"Vital Farms"},"cadenceDays":{"type":"integer","minimum":1,"maximum":365,"example":9},"lastBoughtAt":{"type":"string","format":"date-time","example":"2026-10-15T07:30:00Z"}},"required":["item"]},"PurchaseKitchenPreferences":{"type":"object","properties":{"dietary":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":100,"example":"no peanuts"},"strength":{"type":"string","enum":["required","preferred"]}},"required":["value","strength"]},"maxItems":20},"avoidBrands":{"type":"array","items":{"type":"string","minLength":1,"maxLength":40,"example":"Great Value"},"maxItems":50},"likeBrands":{"type":"array","items":{"type":"string","minLength":1,"maxLength":40,"example":"Vital Farms"},"maxItems":50},"organic":{"type":"string","enum":["prefer","avoid","none"]},"substitutions":{"type":"string","enum":["allow","ask","never"]},"preferredStore":{"type":"string","maxLength":300,"format":"uri","description":"An https store link, such as an Instacart storefront. No query or credentials.","example":"https://www.instacart.com/store/walmart/storefront"},"householdSize":{"type":"integer","minimum":1,"maximum":30,"example":3},"weeklyBudgetMinor":{"type":"integer","exclusiveMinimum":0,"maximum":1000000,"example":15000}}},"PurchaseKitchenRecipe":{"type":"object","properties":{"id":{"type":"string","maxLength":100,"example":"rcp_lasagna"},"title":{"type":"string","minLength":1,"maxLength":80,"example":"Lasagna"},"servings":{"type":"integer","minimum":1,"maximum":50,"example":4},"cookOn":{"type":"string","description":"The planned day, as YYYY-MM-DD.","example":"2026-10-17"},"cookable":{"type":"boolean","description":"Whether your app finds it cookable from what is at home."},"ingredients":{"type":"array","items":{"type":"object","properties":{"item":{"type":"string","minLength":1,"maxLength":120,"example":"ricotta"},"quantity":{"type":"number","exclusiveMinimum":0,"maximum":10000,"example":15},"unit":{"type":"string","minLength":1,"maxLength":30,"example":"oz"},"optional":{"type":"boolean"}},"required":["item"]},"minItems":1,"maxItems":40}},"required":["title","ingredients"]},"PurchaseKitchenListItem":{"type":"object","properties":{"item":{"type":"string","minLength":1,"maxLength":120,"example":"Paper towels"},"quantity":{"type":"number","exclusiveMinimum":0,"maximum":10000,"example":1},"unit":{"type":"string","minLength":1,"maxLength":30,"example":"pack"},"note":{"type":"string","minLength":1,"maxLength":200,"example":"the big pack"}},"required":["item"]},"PurchaseKitchenContext":{"type":["object","null"],"properties":{"version":{"type":"number","enum":[1]},"capturedAt":{"type":"string","format":"date-time","description":"When your app took the snapshot.","example":"2026-10-15T07:30:00Z"},"inventory":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseKitchenInventoryItem"},"maxItems":500},"usuals":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseKitchenUsual"},"maxItems":200},"preferences":{"$ref":"#/components/schemas/PurchaseKitchenPreferences"},"recipes":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseKitchenRecipe"},"maxItems":20,"description":"Only the recipes the buyer picked to cook."},"list":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseKitchenListItem"},"maxItems":100,"description":"The list the buyer keeps in your app."}},"required":["version","capturedAt"],"description":"What the buyer has at home, as your app reports it. Item names, amounts, levels, habits, preferences, chosen recipes and their list. Never addresses, phone numbers, store credentials, card data or health diagnoses. Text with markup, an email address or a long number is refused. At most 128 KB."},"PurchaseBuyerKitchenContext":{"type":"object","properties":{"object":{"type":"string","enum":["buyer_kitchen_context"]},"buyerId":{"type":"string"},"context":{"$ref":"#/components/schemas/PurchaseKitchenContext"},"summary":{"type":["object","null"],"properties":{"capturedAt":{"type":"string","format":"date-time"},"inventory":{"type":"integer"},"low":{"type":"integer"},"out":{"type":"integer"},"usuals":{"type":"integer"},"recipes":{"type":"integer"},"list":{"type":"integer"}},"required":["capturedAt","inventory","low","out","usuals","recipes","list"]},"receivedAt":{"type":["string","null"],"format":"date-time","description":"When Conto received the snapshot."}},"required":["object","buyerId","context","summary","receivedAt"]},"PurchaseHostedLink":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["hosted_link"]},"purpose":{"type":"string","enum":["setup","purchase"]},"buyerId":{"type":"string"},"purchaseId":{"type":["string","null"]},"url":{"type":"string","format":"uri","description":"Single use. Send the buyer here. It expires in 10 minutes."},"expiresAt":{"type":"string","format":"date-time"}},"required":["id","object","purpose","buyerId","purchaseId","url","expiresAt"]},"PurchaseSetupSessionRequest":{"type":"object","properties":{"buyerId":{"type":"string"},"returnUrl":{"type":"string","format":"uri","description":"Its origin must be listed in purchasing settings."},"environment":{"type":"string","enum":["live","test"]}},"required":["buyerId"]},"PurchasePaymentMethod":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["payment_method"]},"buyerId":{"type":"string"},"type":{"type":"string","enum":["card"]},"environment":{"type":"string","enum":["live","test"]},"brand":{"type":"string"},"last4":{"type":"string"},"status":{"type":"string","enum":["active","removed"]},"owner":{"type":"string","enum":["buyer","organization"],"description":"organization: the organization’s company card, which this buyer draws from."},"companyCardId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","object","buyerId","type","environment","brand","last4","status","owner","createdAt"]},"PurchaseDelegation":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["delegation"]},"buyerId":{"type":"string"},"agentId":{"type":"string"},"paymentMethodId":{"type":"string"},"status":{"type":"string","enum":["active","revoked"]},"scope":{"type":"string","enum":["merchant_bound_single_use"]},"limits":{"type":"object","properties":{"perPurchaseMinor":{"type":"integer"},"dailyMinor":{"type":"integer"},"monthlyMinor":{"type":"integer"},"reviewAboveMinor":{"type":"integer","description":"Company card only: orders above this wait for the organization’s review."},"currency":{"type":"string","enum":["USD"]}},"required":["perPurchaseMinor","dailyMinor","currency"]},"requiresPurchaseReview":{"type":"boolean","description":"true: every purchase is reviewed by the buyer. false: a company card delegation, reviewed by the organization above reviewAboveMinor only."},"requiresCardVerification":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"revokedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","object","buyerId","agentId","paymentMethodId","status","scope","limits","requiresPurchaseReview","requiresCardVerification","createdAt","revokedAt"]},"PurchaseAllowance":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["allowance"]},"buyerId":{"type":"string"},"agentId":{"type":"string"},"delegationId":{"type":"string"},"paymentMethodId":{"type":"string"},"environment":{"type":"string","enum":["live","test"]},"status":{"type":"string","enum":["pending_verification","active","revoked","expired"]},"merchant":{"type":"object","properties":{"name":{"type":"string"},"origin":{"type":"string","format":"uri"}},"required":["name","origin"]},"limits":{"type":"object","properties":{"perPurchaseMinor":{"type":"integer"},"periodMinor":{"type":"integer"},"period":{"type":"string","enum":["day","week","month"]},"totalMinor":{"type":"integer","description":"The most the allowance can pay over its whole life."},"currency":{"type":"string","enum":["USD"]}},"required":["perPurchaseMinor","periodMinor","period","totalMinor","currency"]},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"activatedAt":{"type":["string","null"],"format":"date-time"},"revokedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","object","buyerId","agentId","delegationId","paymentMethodId","environment","status","merchant","limits","expiresAt","createdAt","activatedAt","revokedAt"]},"RecurringPurchase":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["recurring_purchase"]},"buyerId":{"type":"string"},"agentId":{"type":"string"},"paymentMethodId":{"type":"string"},"environment":{"type":"string","enum":["live","test"]},"status":{"type":"string","enum":["active","paused","cancelled","ended"]},"merchant":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"description":{"type":["string","null"]},"request":{"type":"object","additionalProperties":{},"description":"The purchase request each order repeats."},"cadence":{"type":"object","properties":{"unit":{"type":"string","enum":["day","month"]},"every":{"type":"integer"},"label":{"type":"string","example":"every week"}},"required":["unit","every","label"]},"limits":{"type":"object","properties":{"maxOrderMinor":{"type":"integer","description":"The most one order may cost and still go through without the buyer’s review."},"baselineMinor":{"type":"integer"},"priceToleranceBps":{"type":"integer"},"currency":{"type":"string","enum":["USD"]}},"required":["maxOrderMinor","baselineMinor","priceToleranceBps","currency"]},"noticeMinutes":{"type":"integer","description":"How long before each order the buyer gets a heads-up."},"skipNext":{"type":"boolean"},"nextDueAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"endedAt":{"type":["string","null"],"format":"date-time"},"cycles":{"type":"array","items":{"type":"object","properties":{"cycleKey":{"type":"string"},"status":{"type":"string","enum":["checking","scheduled","needs_review","paying","paid","skipped","missed","failed","cancelled"]},"purchaseId":{"type":["string","null"]},"payAt":{"type":["string","null"],"format":"date-time"},"total":{"allOf":[{"$ref":"#/components/schemas/PurchaseMoney"},{"type":["object","null"]}]},"createdAt":{"type":"string","format":"date-time"}},"required":["cycleKey","status","purchaseId","payAt","total","createdAt"]}}},"required":["id","object","buyerId","agentId","paymentMethodId","environment","status","merchant","description","request","cadence","limits","noticeMinutes","skipNext","nextDueAt","expiresAt","createdAt","endedAt","cycles"]},"RecurringPurchaseCycleResult":{"type":"object","properties":{"recurrence":{"$ref":"#/components/schemas/RecurringPurchase"},"cycle":{"type":"object","properties":{"cycleKey":{"type":"string"},"status":{"type":"string"},"purchaseId":{"type":["string","null"]}},"required":["cycleKey","status","purchaseId"]},"purchase":{"$ref":"#/components/schemas/Purchase"},"created":{"type":"boolean"}},"required":["recurrence","cycle","created"]},"RecurringPurchaseStartCycleRequest":{"type":"object","properties":{"cycleKey":{"type":"string","description":"Names this order. The same key returns the same order, so a retry never orders twice.","example":"2026-W41"}},"required":["cycleKey"]},"PurchaseActionSessionRequest":{"type":"object","properties":{"returnUrl":{"type":"string","format":"uri"}}},"PurchasingSettings":{"type":"object","properties":{"allowedReturnOrigins":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":10},"buyerEmails":{"type":"boolean","description":"Whether Conto emails buyers when a purchase needs them, when an order is confirmed, and about repeat orders. On by default. Your platform gets the same news as purchase events either way."}}},"ApiKeyListResponse":{"type":"object","properties":{"apiKeys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"keyPrefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"lastUsedAt":{"type":["string","null"],"format":"date-time"},"lastUsedIpAddress":{"type":["string","null"]},"lastUsedUserAgent":{"type":["string","null"]},"usageCount":{"type":"integer"},"expiresAt":{"type":["string","null"],"format":"date-time"},"isActive":{"type":"boolean"},"isExpired":{"type":"boolean"},"isRevoked":{"type":"boolean"},"revokedAt":{"type":["string","null"],"format":"date-time"},"revokedByUserId":{"type":["string","null"]},"revocationReason":{"type":["string","null"]},"rotatedFromKeyId":{"type":["string","null"]},"rotatedToKeyId":{"type":["string","null"]},"status":{"type":"string","enum":["active","revoked"]}},"required":["id","name","keyPrefix","scopes","createdAt","usageCount","isActive","isExpired","isRevoked","status"]}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["apiKeys","total","limit","offset"]},"ApiKeyResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"key":{"type":"string","description":"Full key. Shown only once."},"keyPrefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"expiresAt":{"type":["string","null"],"format":"date-time"},"rotatedFromKeyId":{"type":["string","null"]}},"required":["id","name","key","keyPrefix","scopes"]},"CreateApiKeyRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"scopes":{"type":"array","items":{"type":"string"},"description":"Permission scopes. Available: agents:read, agents:write, wallets:read, wallets:write, transactions:read, transactions:write, policies:read, policies:write, counterparties:read, counterparties:write, alerts:read, alerts:write, analytics:read, audit:read, team:read, team:write, org:read, org:write, admin"},"scopePreset":{"type":"string","enum":["READ_ONLY","STANDARD","ADMIN"],"description":"Use a preset instead of listing individual scopes."},"expiresInDays":{"type":"integer","minimum":1,"maximum":365,"default":365,"description":"Key lifetime in days. Defaults to 365, capped at 365. Org keys always expire, so null is rejected."}},"required":["name"]},"Transaction":{"type":"object","properties":{"id":{"type":"string"},"txHash":{"type":["string","null"]},"settlementMode":{"type":"string","enum":["live","test","unknown"]},"status":{"type":"string","enum":["PENDING","PENDING_APPROVAL","CONFIRMING","CONFIRMED","FAILED","REJECTED","CANCELLED","EXECUTING"]},"amount":{"type":"number"},"currency":{"type":"string"},"fromAddress":{"type":"string"},"toAddress":{"type":"string"},"transactionType":{"type":"string","enum":["A2E","A2M","A2A","A2S","INCOMING"]},"policyResult":{"type":"string","enum":["PENDING","PENDING_APPROVAL","ALLOWED","DENIED","FLAGGED","REQUIRES_APPROVAL"]},"purpose":{"type":["string","null"]},"merchantName":{"type":["string","null"]},"merchantCategory":{"type":["string","null"]},"context":{"type":["object","null"],"additionalProperties":{}},"network":{"type":"object","properties":{"type":{"type":"string","enum":["evm","solana"]},"id":{"type":"string"},"blockNumber":{"type":["integer","null"]},"explorerUrl":{"type":["string","null"],"format":"uri"}},"required":["type","id","blockNumber","explorerUrl"],"additionalProperties":false},"initiatedAt":{"type":"string","format":"date-time"},"confirmedAt":{"type":["string","null"],"format":"date-time"},"agent":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"recipientAgent":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"fromWallet":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"}},"required":["id","name","address"],"additionalProperties":false},"toWallet":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"}},"required":["id","name","address"],"additionalProperties":false}},"required":["id","txHash","settlementMode","status","amount","currency","fromAddress","toAddress","transactionType","policyResult","purpose","merchantName","merchantCategory","context","network","initiatedAt","confirmedAt","agent","recipientAgent","fromWallet","toWallet"],"additionalProperties":false},"TransactionListResponse":{"type":"object","properties":{"transactions":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["transactions","total","limit","offset"]},"CounterpartyType":{"type":"string","enum":["VENDOR","MERCHANT","AGENT","SERVICE","PLATFORM"]},"CounterpartyTrustLevel":{"type":"string","enum":["BLOCKED","SUSPICIOUS","UNKNOWN","VERIFIED","TRUSTED"]},"Counterparty":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"$ref":"#/components/schemas/CounterpartyType"},"address":{"type":["string","null"]},"domain":{"type":["string","null"]},"category":{"type":["string","null"]},"description":{"type":["string","null"]},"trustScore":{"type":["number","null"]},"trustLevel":{"$ref":"#/components/schemas/CounterpartyTrustLevel"},"approvalStatus":{"type":"string","enum":["PENDING","APPROVED","BLOCKED"],"default":"PENDING"},"lifecycleStatus":{"type":"string","enum":["DISCOVERED","PENDING_REVIEW","APPROVED","TRUSTED","MONITORED","QUARANTINED","BLOCKED"]},"verified":{"type":"boolean"}},"required":["id","name","type","trustLevel","verified"]},"CounterpartyListResponse":{"type":"object","properties":{"counterparties":{"type":"array","items":{"$ref":"#/components/schemas/Counterparty"}}},"required":["counterparties"]},"CreateCounterpartyRequest":{"type":"object","properties":{"name":{"type":"string","description":"Counterparty name"},"type":{"allOf":[{"$ref":"#/components/schemas/CounterpartyType"},{"default":"VENDOR"}]},"address":{"type":"string","description":"Wallet address"},"domain":{"type":"string","description":"Website domain"},"category":{"type":"string","description":"Business category"},"description":{"type":"string"},"approvalStatus":{"type":"string","enum":["PENDING","APPROVED","BLOCKED"],"default":"PENDING","description":"Approval status for policy enforcement"},"lifecycleStatus":{"type":"string","enum":["DISCOVERED","PENDING_REVIEW","APPROVED","TRUSTED","MONITORED","QUARANTINED","BLOCKED"],"description":"Canonical counterparty lifecycle status"}},"required":["name"]},"AlertListResponse":{"type":"object","properties":{"alerts":{"type":"array","items":{"$ref":"#/components/schemas/Alert"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["alerts","total","limit","offset"]},"SupportedChain":{"type":"object","properties":{"id":{"type":"string","description":"Chain ID to pass as `chainId`, for example \"42431\", \"8453\", or \"solana-mainnet\"."},"type":{"$ref":"#/components/schemas/ChainType"},"name":{"type":"string"},"shortName":{"type":"string"},"currency":{"type":"string","description":"Primary stablecoin symbol on this chain."},"rpcUrl":{"type":"string"},"explorerUrl":{"type":"string"},"explorerName":{"type":"string"},"stablecoins":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"name":{"type":"string"},"address":{"type":"string","description":"Token contract address on EVM chains, mint address on Solana."},"decimals":{"type":"integer"}},"required":["symbol","name","address","decimals"]}},"isTestnet":{"type":"boolean"},"isDefault":{"type":"boolean"},"iconUrl":{"type":"string"},"faucetAvailable":{"type":"boolean","description":"True when Conto can send test funds to a wallet on this chain."}},"required":["id","type","name","shortName","currency","rpcUrl","explorerUrl","explorerName","stablecoins","isTestnet","isDefault","faucetAvailable"]},"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Backward-compatible human-readable error summary.","example":"The request could not be validated."},"code":{"type":"string","description":"Stable machine-readable error code when the endpoint exposes one.","example":"VALIDATION_ERROR"},"message":{"type":"string","description":"Structured-error alias of the human-readable summary.","example":"The request could not be validated."},"requestId":{"type":"string","description":"Request identifier to include in logs and support reports."},"retryAfter":{"type":"number","description":"Suggested retry delay in seconds, when retrying is safe."},"nextAction":{"type":"string","description":"Suggested next action when one is available."}}}},"parameters":{},"responses":{"BadRequest":{"description":"The request is malformed or fails validation.","headers":{"x-request-id":{"description":"Request identifier for correlation and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"InternalServerError":{"description":"The request could not be completed because of a temporary service failure.","headers":{"x-request-id":{"description":"Request identifier for correlation and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"paths":{"/api/auth/register":{"post":{"tags":["Authentication"],"summary":"Register a new account","description":"Create a new user account and organization, then send an email verification link. Privileged API credentials are not issued until the account is verified.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}}},"responses":{"201":{"description":"Account created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterResponse"}}}},"400":{"description":"Validation error (missing fields or weak password)"},"409":{"description":"Email already registered"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiAuthRegister"}},"/api/agents/sandbox":{"get":{"tags":["Agent Onboarding"],"summary":"Describe anonymous agent sandbox signup","description":"Returns the supported inputs and defaults for creating a temporary Conto test sandbox. Returned credentials expire after 7 days.","responses":{"200":{"description":"Sandbox signup options","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSandboxDescriptorResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiAgentsSandbox"},"post":{"tags":["Agent Onboarding"],"summary":"Create an anonymous agent sandbox","description":"Creates a temporary test workspace with an agent, test wallet, preset test card, agent SDK key, sandbox API key, and sandbox setup key. No human sign-in is required. Use the setup key to configure policies and spend limits, and give the payment runtime only the SDK key. Payments are simulated. Returned keys are shown once and expire after 7 days.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSandboxSignupRequest"}}}},"responses":{"201":{"description":"Anonymous sandbox created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSandboxSignupResponse"}}}},"400":{"description":"Validation error"},"429":{"description":"Too many sandbox signup attempts"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiAgentsSandbox"}},"/api/agents/sandbox/claim":{"post":{"tags":["Agent Onboarding"],"summary":"Claim an anonymous sandbox","description":"Attaches an anonymous sandbox to the signed-in account. Use the sandbox API key returned by POST /api/agents/sandbox as the claim secret. The setup key cannot claim. Claiming revokes the setup key. The owner then manages controls in Conto.","security":[{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimAgentSandboxRequest"}}}},"responses":{"200":{"description":"Sandbox claimed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimAgentSandboxResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Human sign-in required"},"404":{"description":"Sandbox not found"},"410":{"description":"Sandbox key expired"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiAgentsSandboxClaim"}},"/api/agents/register":{"get":{"tags":["Agent Onboarding"],"summary":"Describe organization-token agent registration","description":"Returns public metadata for org-scoped agent self-registration. With a token query parameter, validates the registration token without exposing organization identity or capacity metadata.","parameters":[{"schema":{"type":"string","description":"Optional organization registration token to validate before signup"},"required":false,"name":"token","in":"query"}],"responses":{"200":{"description":"Registration metadata or successful token validation","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"description":{"type":"string"},"usage":{"type":"string"},"requiredFields":{"type":"array","items":{"type":"string"}},"optionalFields":{"type":"array","items":{"type":"string"}},"agentTypes":{"type":"array","items":{"type":"string","enum":["OPENAI_ASSISTANT","ANTHROPIC_CLAUDE","AUTOGPT","CUSTOM"]}},"defaultScopes":{"type":"array","items":{"type":"string"},"description":"Scopes on a newly registered key","example":["payments:request","agents:read"]}},"required":["description","usage","requiredFields","optionalFields","agentTypes","defaultScopes"],"additionalProperties":false},{"$ref":"#/components/schemas/RegisterAgentTokenValidationResponse"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Invalid or disabled registration token"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiAgentsRegister"},"post":{"tags":["Agent Onboarding"],"summary":"Register an agent into an existing organization","description":"Lets an agent join an existing organization using a human-generated registration token. This path issues a least-privilege SDK key scoped to payments:request and agents:read, which reads its own setup. A retry with the same externalId returns the existing agent without the key and never changes its scopes. If that key lacks agents:read, the response includes a remediation for an organization owner.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterAgentWithOrgTokenRequest"}}}},"responses":{"200":{"description":"The caller-owned external ID was already registered. The SDK key is not shown again.","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/AgentStatus"},"publicKey":{"type":"string"},"externalId":{"type":["string","null"]},"webhookConfigured":{"type":"boolean"}},"required":["id","name","status","publicKey","externalId","webhookConfigured"],"additionalProperties":false},"sdkKeyId":{"type":["string","null"]},"scopes":{"type":"array","items":{"type":"string"},"description":"Scopes on the existing key. A retry never changes them."},"expiresAt":{"type":["string","null"],"format":"date-time"},"endpoints":{"type":"object","properties":{"setup":{"type":"object","properties":{"method":{"type":"string","enum":["GET"]},"href":{"type":"string","enum":["/api/sdk/setup"]}},"required":["method","href"],"additionalProperties":false,"description":"Present when the key has agents:read"},"requestPayment":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"href":{"type":"string","enum":["/api/sdk/payments/request"]}},"required":["method","href"],"additionalProperties":false,"description":"Present when the key has payments:request"}},"additionalProperties":false,"description":"SDK endpoints the existing key can call"},"isExisting":{"type":"boolean","enum":[true]},"message":{"type":"string"},"remediation":{"type":"object","properties":{"code":{"type":"string","enum":["INSUFFICIENT_SCOPE"]},"requiredScope":{"type":"string","enum":["agents:read"]},"actor":{"type":"string","enum":["owner"]},"nextAction":{"type":"string"}},"required":["code","requiredScope","actor","nextAction"],"additionalProperties":false,"description":"Present when the existing key lacks agents:read and cannot read its own setup. An organization owner must generate a new key for the agent. Conto does not add scopes to an existing key."}},"required":["agent","sdkKeyId","scopes","expiresAt","endpoints","isExisting","message"],"additionalProperties":false}}}},"201":{"description":"Agent registered and SDK key returned once","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/AgentStatus"},"publicKey":{"type":"string"},"externalId":{"type":["string","null"]},"webhookConfigured":{"type":"boolean"}},"required":["id","name","status","publicKey","externalId","webhookConfigured"],"additionalProperties":false},"sdkKey":{"type":"string","description":"Agent SDK key. Returned once."},"sdkKeyId":{"type":"string","description":"Stable credential reference for key management"},"scopes":{"type":"array","items":{"type":"string"},"description":"payments:request and agents:read","example":["payments:request","agents:read"]},"expiresAt":{"type":"string","format":"date-time"},"endpoints":{"type":"object","properties":{"setup":{"type":"object","properties":{"method":{"type":"string","enum":["GET"]},"href":{"type":"string","enum":["/api/sdk/setup"]}},"required":["method","href"],"additionalProperties":false,"description":"Present when the key has agents:read"},"requestPayment":{"type":"object","properties":{"method":{"type":"string","enum":["POST"]},"href":{"type":"string","enum":["/api/sdk/payments/request"]}},"required":["method","href"],"additionalProperties":false,"description":"Present when the key has payments:request"}},"required":["setup","requestPayment"],"additionalProperties":false,"description":"SDK endpoints the returned key can call"},"isExisting":{"type":"boolean","enum":[false]},"message":{"type":"string"}},"required":["agent","sdkKey","sdkKeyId","scopes","expiresAt","endpoints","isExisting","message"],"additionalProperties":false}}}},"400":{"description":"Validation error"},"401":{"description":"Invalid or disabled registration token"},"403":{"description":"Organization agent limit reached"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiAgentsRegister"}},"/api/agents":{"get":{"tags":["Agents"],"summary":"List all agents","description":"Retrieve all agents for the current organization.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"allOf":[{"$ref":"#/components/schemas/AgentStatus"},{"description":"Filter by agent status"}]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","description":"Search by name, description, purpose, identity slug, or external reference"},"required":false,"name":"search","in":"query"},{"schema":{"type":"integer","maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"List of agents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiAgents"},"post":{"tags":["Agents"],"summary":"Create a new agent","description":"Create an AI agent that can be linked to wallets and policies for controlled payments. Requests made with org API keys should include `ownerMembershipId`; browser-session requests can default to the current member.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentRequest"}}}},"responses":{"201":{"description":"Agent created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentResponse"}}}},"400":{"description":"Validation error"},"401":{"description":"Authentication required"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiAgents"}},"/api/agents/{id}":{"get":{"tags":["Agents"],"summary":"Get agent by ID","description":"Get agent details including linked wallets and transaction counts.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Agent details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDetails"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Resource not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiAgentsById"},"patch":{"tags":["Agents"],"summary":"Update agent","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAgentRequest"}}}},"responses":{"200":{"description":"Agent updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"description":"Validation error"},"404":{"description":"Resource not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"patchApiAgentsById"},"delete":{"tags":["Agents"],"summary":"Delete agent","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Agent deleted"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Resource not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"deleteApiAgentsById"}},"/api/agents/{id}/wallets":{"get":{"tags":["Agents","Wallets"],"summary":"List wallets linked to agent","security":[{"sessionAuth":[]},{"orgApiKey":[]},{"sandboxSetupKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"List of linked wallets with spend limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentWalletListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiAgentsByIdWallets"},"post":{"tags":["Agents","Wallets"],"summary":"Link wallet to agent","description":"Link a wallet to an agent with delegation type, spend limits, and time window controls. Only PROD agents can pay from mainnet wallets. Linking a mainnet wallet to a DEV or STAGING agent still succeeds, and the response includes a `warnings` entry saying to set the agent's environment to PROD.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkWalletRequest"}}}},"responses":{"201":{"description":"Wallet linked to agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentWalletLinkResponse"}}}},"400":{"description":"Validation error"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiAgentsByIdWallets"}},"/api/agents/{id}/wallets/{walletId}":{"patch":{"tags":["Agents","Wallets"],"summary":"Update agent-wallet link","description":"Update spend limits, delegation type, or time window for an agent-wallet link.","security":[{"sessionAuth":[]},{"orgApiKey":[]},{"sandboxSetupKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"walletId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAgentWalletRequest"}}}},"responses":{"200":{"description":"Agent-wallet link updated"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Resource not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"patchApiAgentsByIdWalletsByWalletId"},"delete":{"tags":["Agents","Wallets"],"summary":"Unlink wallet from agent","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"walletId","in":"path"}],"responses":{"200":{"description":"Wallet unlinked"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Resource not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"deleteApiAgentsByIdWalletsByWalletId"}},"/api/agents/{id}/policies":{"get":{"tags":["Agents","Policies"],"summary":"List policies assigned to agent","security":[{"sessionAuth":[]},{"orgApiKey":[]},{"sandboxSetupKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"List of assigned policies","content":{"application/json":{"schema":{"type":"object","properties":{"policies":{"type":"array","items":{"$ref":"#/components/schemas/AssignedAgentPolicy"}}},"required":["policies"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiAgentsByIdPolicies"},"post":{"tags":["Agents","Policies"],"summary":"Assign policy to agent","security":[{"sessionAuth":[]},{"orgApiKey":[]},{"sandboxSetupKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"policyId":{"type":"string","description":"Policy ID to assign"}},"required":["policyId"]}}}},"responses":{"201":{"description":"Policy assigned to agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignedAgentPolicy"}}}},"400":{"description":"Policy already assigned or validation error"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiAgentsByIdPolicies"},"delete":{"tags":["Agents","Policies"],"summary":"Unassign policy from agent","description":"Uses query parameter: DELETE /api/agents/{id}/policies?policyId={policyId}","security":[{"sessionAuth":[]},{"orgApiKey":[]},{"sandboxSetupKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Policy ID to unassign"},"required":true,"name":"policyId","in":"query"}],"responses":{"200":{"description":"Policy unassigned"},"202":{"description":"The organization requires governance approval for this change. Nothing is applied. After approval, resend the identical request with the x-governance-approval-id header within 15 minutes."},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Resource not found"},"409":{"description":"The governance approval is not approved, has expired, or no longer matches this request"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"deleteApiAgentsByIdPolicies"}},"/api/agents/{id}/sdk-keys":{"get":{"tags":["Agents"],"summary":"List SDK keys for agent","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"List of SDK keys (prefix only, not full key)"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiAgentsByIdSdkKeys"},"post":{"tags":["Agents"],"summary":"Generate SDK key for agent","description":"Generate a new SDK API key for the agent. The full key is returned only once. Request body supports `name`, optional `expiresInDays`, and optional `keyType`. Standard keys cover the payment lifecycle (request, execute, approve, confirm) plus read scopes; admin keys add delegated organization-management scopes for agents, wallets, and policies.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSdkKeyRequest"}}}},"responses":{"201":{"description":"SDK key created. The full key is shown only once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SdkKeyResponse"}}}},"400":{"description":"Key name is required"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiAgentsByIdSdkKeys"}},"/api/agents/{id}/freeze-config":{"get":{"tags":["Agents","Safety"],"summary":"Get automatic protection settings","description":"Returns whether automatic protection is enabled and the customer-configurable safety thresholds for an agent.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Automatic protection settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentAutomaticProtectionConfig"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Agent not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiAgentsByIdFreezeConfig"},"patch":{"tags":["Agents","Safety"],"summary":"Update automatic protection settings","description":"Enables or disables automatic protection and updates selected safety thresholds. Omitted values keep their current setting.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAgentAutomaticProtectionConfig"}}}},"responses":{"200":{"description":"Updated automatic protection settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentAutomaticProtectionConfig"}}}},"202":{"description":"The organization requires governance approval for this change. Nothing is applied. After approval, resend the identical request with the x-governance-approval-id header within 15 minutes."},"400":{"description":"Invalid settings"},"404":{"description":"Agent not found"},"409":{"description":"The governance approval is not approved, has expired, or no longer matches this request"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"patchApiAgentsByIdFreezeConfig"}},"/api/agents/{id}/freeze":{"post":{"tags":["Agents","Safety"],"summary":"Freeze an agent","description":"Stop an agent from making transactions. Associated wallets can also be frozen.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreezeAgentRequest"}}}},"responses":{"200":{"description":"Agent frozen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentFreezeActionResponse"}}}},"400":{"description":"Validation error"},"404":{"description":"Agent not found"},"409":{"description":"Agent is already frozen"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiAgentsByIdFreeze"},"get":{"tags":["Agents","Safety"],"summary":"Get freeze status","description":"Returns whether the agent is currently frozen.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Current freeze status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentFreezeStatus"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Agent not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiAgentsByIdFreeze"}},"/api/agents/{id}/unfreeze":{"post":{"tags":["Agents","Safety"],"summary":"Unfreeze an agent","description":"Allow a frozen agent to make transactions again.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnfreezeAgentRequest"}}}},"responses":{"200":{"description":"Agent unfrozen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentFreezeActionResponse"}}}},"400":{"description":"Validation error"},"404":{"description":"Agent not found"},"409":{"description":"Agent is not frozen"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiAgentsByIdUnfreeze"}},"/api/agents/{id}/freeze-history":{"get":{"tags":["Agents","Safety"],"summary":"Get agent freeze history","description":"Paginated list of changes to this agent's freeze status.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Paginated freeze-status history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentFreezeHistoryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiAgentsByIdFreezeHistory"}},"/api/freeze-events":{"get":{"tags":["Safety"],"summary":"List organization-wide freeze history","description":"Paginated list of agent freeze-status changes.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"integer","maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Paginated freeze-status history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationFreezeHistoryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiFreezeEvents"}},"/api/agents/sandbox/handoff":{"post":{"tags":["Agent Onboarding"],"summary":"Create a one-time human claim link","description":"Authenticate with the sandbox organization API key. Returns a 15-minute claim token and browser URL. Do not log the token or URL. Share the URL only with the intended human owner.","security":[{"orgApiKey":[]}],"responses":{"201":{"description":"Handoff created","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"verificationUrl":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"},"organizationName":{"type":"string"},"statusUrl":{"type":"string"},"intervalSeconds":{"type":"number"},"requestedPermission":{"type":"string"}},"required":["token","verificationUrl","expiresAt","organizationName","statusUrl","intervalSeconds","requestedPermission"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Current sandbox organization key required"},"409":{"description":"Sandbox already claimed"},"429":{"description":"Rate limited"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiAgentsSandboxHandoff"},"get":{"tags":["Agent Onboarding"],"summary":"Poll a sandbox handoff","description":"Send the handoff token as Authorization: Bearer, not the sandbox API key. Poll no faster than the returned intervalSeconds. Status is pending or claimed until the token expires.","security":[{"sandboxHandoffAuth":[]}],"responses":{"200":{"description":"Current handoff status","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["pending","claimed"]},"expiresAt":{"type":"string","format":"date-time"},"organizationName":{"type":"string"}},"required":["status","expiresAt"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"410":{"description":"Handoff expired"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiAgentsSandboxHandoff"}},"/api/agents/sandbox/handoff/complete":{"post":{"tags":["Agent Onboarding"],"summary":"Confirm sandbox ownership in the browser","description":"Requires a signed-in verified human account, same-origin request, and unused handoff token. This does not enable production payments. Claiming revokes the sandbox setup key.","security":[{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"}},"required":["token"],"additionalProperties":false}}}},"responses":{"200":{"description":"Sandbox claimed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["claimed"]},"organizationName":{"type":"string"},"productionReady":{"type":"boolean","enum":[false]}},"required":["status","organizationName","productionReady"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Human sign-in required"},"403":{"description":"Email verification or same-origin request required"},"409":{"description":"Already claimed"},"410":{"description":"Handoff expired or consumed"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiAgentsSandboxHandoffComplete"}},"/api/wallets":{"get":{"tags":["Wallets"],"summary":"List all wallets","description":"List organization wallets with balances and linked-agent counts.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"$ref":"#/components/schemas/WalletStatus"},"required":false,"name":"status","in":"query"},{"schema":{"$ref":"#/components/schemas/ChainType"},"required":false,"name":"chainType","in":"query"},{"schema":{"type":"string"},"required":false,"name":"chainId","in":"query"}],"responses":{"200":{"description":"List of wallets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiWallets"},"post":{"tags":["Wallets"],"summary":"Create a new wallet","description":"Create a managed wallet with an explicit root-control model, or register an external address that you control. Organization-controlled managed wallets give the customer owner quorum root administration and export authority while Conto remains a policy-limited additional signer. This setting applies only to new wallets. Repeating a request for the same network and address returns the existing wallet.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWalletRequest"}}}},"responses":{"200":{"description":"Existing wallet reused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Wallet"}}}},"201":{"description":"Wallet created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Wallet"}}}},"400":{"description":"Validation error"},"409":{"description":"Organization owner public key is required"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"description":"Managed wallet control configuration is unavailable"}},"operationId":"postApiWallets"}},"/api/wallets/{id}":{"get":{"tags":["Wallets"],"summary":"Get wallet by ID","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Wallet details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Wallet"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Resource not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiWalletsById"},"patch":{"tags":["Wallets"],"summary":"Update wallet","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"status":{"$ref":"#/components/schemas/WalletStatus"}}}}}},"responses":{"200":{"description":"Wallet updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Wallet"}}}},"400":{"description":"Invalid update"},"404":{"description":"Resource not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"patchApiWalletsById"}},"/api/wallets/{id}/provision":{"post":{"tags":["Wallets"],"summary":"Confirm managed wallet setup","description":"Confirm that a managed wallet is reachable and synchronize its current balance. No request body is required.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Wallet setup confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisionResponse"}}}},"400":{"description":"Setup confirmation is not available for this wallet"},"404":{"description":"Resource not found"},"409":{"description":"Refresh deferred while a payment is unsettled or the wallet changes. Stored spendable balance is preserved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletBalanceRefreshDeferred"}}}},"500":{"description":"Setup confirmation failed"},"502":{"description":"Setup confirmation is temporarily unavailable"}},"operationId":"postApiWalletsByIdProvision"}},"/api/wallets/{id}/refresh-balance":{"post":{"tags":["Wallets"],"summary":"Refresh the configured wallet chain balance","description":"Refresh the stored balance from the wallet’s configured chain. Unsettled local payments defer refresh so a chain snapshot cannot restore reserved funds. A concurrent wallet update also defers refresh; retry after settlement. No request body is required.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Balance refreshed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletBalanceRefreshResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Wallet not found"},"409":{"description":"Refresh deferred; stored spendable balance preserved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletBalanceRefreshDeferred"}}}},"500":{"description":"Balance refresh failed"},"502":{"description":"Chain balance is temporarily unavailable"}},"operationId":"postApiWalletsByIdRefreshBalance"}},"/api/agents/{agentId}/external-cards":{"get":{"tags":["Connected Cards"],"summary":"List an agent's card assignments","description":"List active and paused card assignments. Card credentials are never returned.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"agentId","in":"path"}],"responses":{"200":{"description":"Card assignments","content":{"application/json":{"schema":{"type":"object","properties":{"cards":{"type":"array","items":{"$ref":"#/components/schemas/CardAccessAssignment"}},"enforcement":{"$ref":"#/components/schemas/CardAccessEnforcement"}},"required":["cards","enforcement"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Feature unavailable or agent not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiAgentsByAgentIdExternalCards"},"post":{"tags":["Connected Cards"],"summary":"Assign a card alias to an agent","description":"Create an integrated-path policy assignment for a masked customer-card alias.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"agentId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignCardAccessRequest"}}}},"responses":{"201":{"description":"Assignment created","content":{"application/json":{"schema":{"type":"object","properties":{"agentCard":{"$ref":"#/components/schemas/CardAccessAssignment"},"enforcement":{"$ref":"#/components/schemas/CardAccessEnforcement"}},"required":["agentCard","enforcement"]}}}},"400":{"description":"Invalid controls or an assignment limit exceeds the alias ceiling"},"404":{"description":"Feature, agent, or alias not found"},"409":{"description":"The alias is already assigned to the agent"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiAgentsByAgentIdExternalCards"}},"/api/agents/{agentId}/external-cards/{cardId}":{"patch":{"tags":["Connected Cards"],"summary":"Update an agent card assignment","description":"Update controls, pause access, or resume access. Pause before editing when unused approvals are live.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"agentId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"cardId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCardAccessRequest"}}}},"responses":{"200":{"description":"Assignment updated, paused, or resumed","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"agentCard":{"$ref":"#/components/schemas/CardAccessAssignment"},"enforcement":{"$ref":"#/components/schemas/CardAccessEnforcement"}},"required":["agentCard","enforcement"]},{"type":"object","properties":{"accessStatus":{"type":"string","enum":["PAUSED"]},"cardId":{"type":"string"},"agentId":{"type":"string"},"revokedApprovals":{"type":"integer"},"executingRequests":{"type":"integer"},"reconciliationRequired":{"type":"boolean"},"enforcement":{"$ref":"#/components/schemas/CardAccessEnforcement"}},"required":["accessStatus","cardId","agentId","revokedApprovals","executingRequests","reconciliationRequired","enforcement"]}]}}}},"400":{"description":"Invalid controls"},"404":{"description":"Feature or assignment not found"},"409":{"description":"Lifecycle conflict or unused approvals must be cancelled first"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"patchApiAgentsByAgentIdExternalCardsByCardId"},"delete":{"tags":["Connected Cards"],"summary":"Revoke an agent card assignment","description":"Permanently revoke the assignment and cancel unused approvals. Claimed purchases remain available for reconciliation.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"agentId","in":"path"},{"schema":{"type":"string"},"required":true,"name":"cardId","in":"path"}],"responses":{"200":{"description":"Assignment revoked","content":{"application/json":{"schema":{"type":"object","properties":{"accessStatus":{"type":"string","enum":["REVOKED"]},"cardId":{"type":"string"},"agentId":{"type":"string"},"revokedApprovals":{"type":"integer"},"executingRequests":{"type":"integer"},"reconciliationRequired":{"type":"boolean"},"enforcement":{"$ref":"#/components/schemas/CardAccessEnforcement"},"unassigned":{"type":"boolean","enum":[true]}},"required":["accessStatus","cardId","agentId","revokedApprovals","executingRequests","reconciliationRequired","enforcement","unassigned"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Feature or assignment not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"deleteApiAgentsByAgentIdExternalCardsByCardId"}},"/api/connected-cards":{"post":{"tags":["Connected Cards"],"summary":"Connect a customer-owned card","description":"Exchange the browser card token for a provider payment method and store a masked connected-card reference. The opaque token is never stored or returned.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectConnectedCardRequest"}}}},"responses":{"201":{"description":"Connected-card reference created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectConnectedCardResponse"}}}},"400":{"description":"Invalid request"},"404":{"description":"Feature unavailable for this organization"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiConnectedCards"},"get":{"tags":["Connected Cards"],"summary":"List connected cards","description":"List the organization connected-card references and their mandates, masked. Card credentials and provider tokens are never returned.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"responses":{"200":{"description":"Connected-card references","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectedCardListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Feature unavailable for this organization"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiConnectedCards"}},"/api/connected-cards/{referenceId}/delegate":{"post":{"tags":["Connected Cards"],"summary":"Delegate a connected card to an agent","description":"Bind an active tenant-scoped agent assignment to the connected payment method. When `assignment` is present, the agent limits and the binding are written in one transaction, and an agent limit above the card limit is rejected with 400 (with `raiseCardLimits` on a new card's first link, the card limits rise to fit instead). A card the agent already has under a different idempotency key, or a card removed from this agent, is rejected with 409 before any limit changes.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"referenceId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DelegateConnectedCardRequest"}}}},"responses":{"201":{"description":"Binding created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectedCardBindingResponse"}}}},"400":{"description":"Invalid request"},"404":{"description":"Feature unavailable or reference not found"},"409":{"description":"The card is already connected to this agent, or the binding conflicts"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiConnectedCardsByReferenceIdDelegate"}},"/api/connected-cards/{referenceId}/disconnect":{"post":{"tags":["Connected Cards"],"summary":"Disconnect a connected card from an agent","description":"Take the card away from one agent: every live authorization on the binding is revoked, then the agent assignment and the provider binding are closed so no new credential can be minted. A purchase already in flight is counted in `reconciliationRequired` rather than released, and a credential already issued cannot be recalled. Idempotent. The card stays removed from this agent until a signed-in owner or admin adds it back with `/relink`.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"referenceId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisconnectConnectedCardRequest"}}}},"responses":{"200":{"description":"Disconnect result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisconnectConnectedCardResponse"}}}},"400":{"description":"Invalid request"},"403":{"description":"The card is not connected to that agent"},"404":{"description":"Feature unavailable or reference not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiConnectedCardsByReferenceIdDisconnect"}},"/api/connected-cards/{referenceId}/mandates":{"post":{"tags":["Connected Cards"],"summary":"Create a connected-card mandate","description":"Create a merchant-scoped mandate on the connected card. Both single-use and standing shapes are accepted; the mandate is created awaiting cardholder verification.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"referenceId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateConnectedCardMandateRequest"}}}},"responses":{"201":{"description":"Mandate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectedCardMandateResponse"}}}},"400":{"description":"Invalid request"},"404":{"description":"Feature unavailable or reference not found"},"409":{"description":"Mandate conflict"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiConnectedCardsByReferenceIdMandates"}},"/api/connected-cards/mandates/{mandateId}":{"get":{"tags":["Connected Cards"],"summary":"Get a connected-card mandate","description":"Return one masked mandate scoped to the organization.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"mandateId","in":"path"}],"responses":{"200":{"description":"Mandate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectedCardMandateResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Feature unavailable or mandate not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiConnectedCardsMandatesByMandateId"}},"/api/connected-cards/mandates/{mandateId}/verify":{"post":{"tags":["Connected Cards"],"summary":"Relay a mandate verify action","description":"Relay one browser SDK verify action to the provider server-to-server. Only the cardholder can verify; the returned envelope carries no credential material.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"mandateId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyConnectedCardMandateRequest"}}}},"responses":{"200":{"description":"Verify envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectedCardVerifyResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"description":"Caller is not the cardholder"},"404":{"description":"Feature unavailable or mandate not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiConnectedCardsMandatesByMandateIdVerify"}},"/api/sdk/connected-cards":{"get":{"tags":["SDK Payments"],"summary":"List drawable connected cards","description":"List the connected cards and active mandates the calling agent may draw against, masked. Scoped to the agent through its bindings. Card credentials and provider tokens are never returned.","security":[{"sdkKeyAuth":[]}],"responses":{"200":{"description":"Drawable connected cards","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectedCardDrawListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Missing transactions:read scope"},"404":{"description":"Feature unavailable for this organization"},"429":{"description":"Rate limit exceeded"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkConnectedCards"}},"/api/sdk/connected-cards/preview":{"post":{"tags":["SDK Payments"],"summary":"Preview a connected-card purchase","description":"Check a purchase against the calling agent's card limits and policies before asking for an authorization. Nothing is reserved, no authorization is created, and no credential is issued. The result can change before the draw, which makes the final decision against the verified authorization.","security":[{"sdkKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewConnectedCardPurchaseRequest"}}}},"responses":{"200":{"description":"Preview decision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewConnectedCardPurchaseResponse"}}}},"400":{"description":"Invalid request, or the card is not active"},"401":{"description":"Authentication required"},"403":{"description":"Missing payments:approve scope"},"404":{"description":"Feature unavailable, or card not found in scope"},"429":{"description":"Rate limit exceeded"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkConnectedCardsPreview"}},"/api/sdk/connected-cards/draws":{"post":{"tags":["SDK Payments"],"summary":"Draw a single-use card credential","description":"Draw one single-use, merchant-locked, amount-capped card credential against a verified mandate. On a successful mint the response carries the card credential EXACTLY ONCE; it is never persisted server-side and cannot be re-fetched. An issued credential consumes allowance capacity even if unused. A reviewed request may resume with its original key. A replayed completed draw, or a DENIED, REQUIRES_APPROVAL, or reconciliation outcome, returns the decision without a credential.","security":[{"sdkKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrawConnectedCardRequest"}}}},"responses":{"200":{"description":"Draw outcome. Includes the one-time credential only on a successful mint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrawConnectedCardResponse"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"403":{"description":"Missing payments:approve scope"},"404":{"description":"Feature unavailable, or card/mandate not found in scope"},"409":{"description":"Draw conflict"},"429":{"description":"Rate limit exceeded"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"description":"Provider unavailable or draw outcome indeterminate"}},"operationId":"postApiSdkConnectedCardsDraws"}},"/api/connected-cards/mandates/{mandateId}/revoke":{"post":{"tags":["Connected Cards"],"summary":"Revoke a connected-card mandate","description":"Revoke a connected-card mandate. The mandate flips to REVOKED, its APPROVED-but-unexecuted draws are cancelled and released, and any EXECUTING or CONFIRMING draw is counted as reconciliationRequired without releasing it since a live single-use credential may already exist. Card credentials and provider tokens are never returned. Limited to a signed-in user.","security":[{"sessionAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"mandateId","in":"path"}],"responses":{"200":{"description":"Revoked mandate and draw counts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectedCardMandateRevokeResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"description":"A signed-in user is required"},"404":{"description":"Feature unavailable or mandate not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiConnectedCardsMandatesByMandateIdRevoke"}},"/api/connected-cards/{referenceId}/limits":{"patch":{"tags":["Connected Cards"],"summary":"Edit an agent's connected-card limits","description":"Edit the agent's spend limits on one connected card (this agent's access to that card). Each agent limit must be at or below the parent card ceiling, and per-transaction must be at or below daily; a violation returns 400. Card-wide limits are not edited here. Card credentials and provider tokens are never returned. Limited to a signed-in user.","security":[{"sessionAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"referenceId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateConnectedCardAgentLimitsRequest"}}}},"responses":{"200":{"description":"Updated agent limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateConnectedCardAgentLimitsResponse"}}}},"400":{"description":"Invalid request or a limit exceeds the card ceiling"},"403":{"description":"A signed-in user is required"},"404":{"description":"Feature unavailable, or reference/binding/assignment not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"patchApiConnectedCardsByReferenceIdLimits"}},"/api/connected-cards/{referenceId}/card-limits":{"patch":{"tags":["Connected Cards"],"summary":"Edit a connected card's own limits","description":"Edit the card-wide limits that cap every agent on this connected card. Per-transaction must be at or below daily, and weekly and monthly at or above daily. An agent limit never exceeds the card limit, so limits below any agent's limits on the card are rejected with 400, naming those agents. Agent limits are edited with `/limits`. Card credentials and provider tokens are never returned. Limited to a signed-in user.","security":[{"sessionAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"referenceId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateConnectedCardLimitsRequest"}}}},"responses":{"200":{"description":"Updated card limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateConnectedCardLimitsResponse"}}}},"400":{"description":"Invalid request, limits out of order, or below an agent limit"},"403":{"description":"A signed-in user is required"},"404":{"description":"Feature unavailable or reference not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"patchApiConnectedCardsByReferenceIdCardLimits"}},"/api/connected-cards/{referenceId}/relink":{"post":{"tags":["Connected Cards"],"summary":"Add a removed card back to an agent","description":"Reconnect a card that was removed from this agent, with fresh agent limits checked against the card limits. Every earlier authorization stays revoked, so the cardholder must create and verify a new authorization before any purchase. A card removed because its agent was deleted cannot be added back. Limited to a signed-in user.","security":[{"sessionAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"referenceId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelinkConnectedCardRequest"}}}},"responses":{"200":{"description":"Binding active again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectedCardBindingResponse"}}}},"400":{"description":"Invalid request or an agent limit exceeds the card limit"},"403":{"description":"A signed-in user is required"},"404":{"description":"Feature unavailable, or reference, agent, or binding not found"},"409":{"description":"The card is still connected, or it cannot be added back"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiConnectedCardsByReferenceIdRelink"}},"/api/connected-cards/reconcile":{"post":{"tags":["Connected Cards"],"summary":"Reconcile a stuck connected-card draw","description":"Record the checkout outcome of a draw that needs a person. NOT_EXECUTED releases the draw's full hold from the card and agent limits, and EXECUTED with a smaller amount releases the difference. Neither verifies settlement or restores the provider's allowance capacity. Idempotent and tenant-scoped. No credential material is referenced or returned. Limited to a signed-in user.","security":[{"sessionAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconcileConnectedCardMintRequest"}}}},"responses":{"200":{"description":"Reconcile outcome","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconcileConnectedCardMintResponse"}}}},"400":{"description":"Invalid request or rejected reconciliation data"},"403":{"description":"A signed-in user is required"},"404":{"description":"Feature unavailable or draw not found"},"409":{"description":"Draw is not in a reconcilable status"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiConnectedCardsReconcile"},"get":{"tags":["Connected Cards"],"summary":"List connected-card draws needing reconciliation","description":"List connected-card draws that need a person, masked, so an operator UI can resolve them: unresolved issuance, unacknowledged delivery, an agent report of a smaller charge or an unused card number, and a delivered card number with no reported outcome an hour after it expired. Card credentials, provider tokens, and the idempotency context are never returned. Limited to a signed-in user.","security":[{"sessionAuth":[]}],"responses":{"200":{"description":"Stuck connected-card draws","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectedCardReconcileListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"description":"A signed-in user is required"},"404":{"description":"Feature unavailable for this organization"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiConnectedCardsReconcile"}},"/api/connected-cards/mandates/{mandateId}/confirm-verification":{"post":{"tags":["Connected Cards"],"summary":"Confirm mandate verification","description":"Read the server-authoritative allowance status and map it onto the mandate. An active allowance promotes the mandate to ACTIVE.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"mandateId","in":"path"}],"responses":{"200":{"description":"Mandate after verification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectedCardMandateResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Feature unavailable or mandate not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiConnectedCardsMandatesByMandateIdConfirmVerification"}},"/api/sdk/connected-cards/draws/{id}/acknowledge":{"post":{"tags":["SDK Payments"],"summary":"Acknowledge one-time credential receipt","description":"Call after receiving a fresh credential. Idempotent and scoped to the calling agent. Receipt does not prove checkout or payment settlement. Available while new issuance is disabled.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Receipt acknowledged","content":{"application/json":{"schema":{"type":"object","properties":{"acknowledged":{"type":"boolean","enum":[true]},"settlementVerified":{"type":"boolean","enum":[false]}},"required":["acknowledged","settlementVerified"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Issued draw not found for this agent"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkConnectedCardsDrawsByIdAcknowledge"}},"/api/sdk/connected-cards/draws/{id}/outcome":{"post":{"tags":["SDK Payments"],"summary":"Report what happened with an issued card number","description":"Call after checkout. USED at the full approved amount closes the draw. NOT_USED, or USED with a smaller amountMinor, is recorded and sent to a person, who confirms it before any held amount is released. A report never releases held spend and does not prove settlement. Repeating the same report returns the same result. Scoped to the calling agent. Live cards only. Available while new issuance is disabled.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportConnectedCardDrawOutcomeRequest"}}}},"responses":{"200":{"description":"Outcome recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportConnectedCardDrawOutcomeResponse"}}}},"400":{"description":"Invalid outcome, or an amount above the approved amount"},"404":{"description":"Issued draw not found for this agent"},"409":{"description":"A different outcome was already reported, or the draw was resolved"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkConnectedCardsDrawsByIdOutcome"}},"/api/connected-cards/draws":{"get":{"tags":["Connected Cards"],"summary":"List draws awaiting human review","security":[{"sessionAuth":[]}],"responses":{"200":{"description":"Up to 100 unexpired pending draws, with masked merchant and amount information"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiConnectedCardsDraws"}},"/api/connected-cards/draws/{id}/decision":{"post":{"tags":["Connected Cards"],"summary":"Review a pending card draw","security":[{"sessionAuth":[]}],"description":"Owner, admin or manager review. After approval, the agent must retry the original draw with the same input and idempotency key. Current policy, mandate, expiry and limits are rechecked before issuance.","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["APPROVED","REJECTED"]}},"required":["decision"]}}}},"responses":{"200":{"description":"Review recorded"},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"description":"Reviewer permission required"},"404":{"description":"Draw not found"},"409":{"description":"Draw is no longer reviewable"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiConnectedCardsDrawsByIdDecision"}},"/api/connected-cards/test":{"post":{"tags":["Test Cards"],"summary":"Add a test card to an agent","description":"Provisions a synthetic card for the agent, or returns the one it has. No card details are entered and no provider is involved. The signed-in owner or admin, or an organization API key with wallets:write acting for them, may add one. An agent key is refused.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisionTestCardRequest"}}}},"responses":{"200":{"description":"The agent already had a test card","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisionTestCardResponse"}}}},"201":{"description":"Test card added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisionTestCardResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"description":"Not a signed-in owner or admin or an organization API key, or test cards are not available"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiConnectedCardsTest"},"get":{"tags":["Test Cards"],"summary":"List an agent's test cards","description":"Every test authorization regardless of status, recent simulated receipts, and the test merchants' catalogs.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"agentId","in":"query"}],"responses":{"200":{"description":"Test cards for the agent"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiConnectedCardsTest"}},"/api/connected-cards/test/{referenceId}/mandates":{"post":{"tags":["Test Cards"],"summary":"Authorize a test purchase","description":"Creates a test authorization for one of the Conto test merchants. Its verification is recorded as SIMULATED, which activates it. No cardholder ceremony runs. An agent key is refused.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"referenceId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTestMandateRequest"}}}},"responses":{"201":{"description":"Test authorization saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestMandateResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"description":"An agent key cannot create authorizations"},"404":{"description":"Test card not found in this organization"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiConnectedCardsTestByReferenceIdMandates"}},"/api/connected-cards/test/{referenceId}/limits":{"patch":{"tags":["Test Cards"],"summary":"Edit the agent's limits on a test card","description":"Same rules as a live card: each limit at or below the test card's ceiling, per purchase at or below daily, spend counters untouched. An agent key is refused.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"referenceId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateConnectedCardAgentLimitsRequest"}}}},"responses":{"200":{"description":"Limits updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateConnectedCardAgentLimitsResponse"}}}},"400":{"description":"A limit is above the test card ceiling"},"404":{"description":"Test card not found in this organization"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"patchApiConnectedCardsTestByReferenceIdLimits"}},"/api/connected-cards/test/{referenceId}/disconnect":{"post":{"tags":["Test Cards"],"summary":"Remove a test card from an agent","description":"Revokes its test authorizations and unlinks it. An agent key is refused.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"referenceId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisconnectConnectedCardRequest"}}}},"responses":{"200":{"description":"Test card removed and its authorizations revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisconnectConnectedCardResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiConnectedCardsTestByReferenceIdDisconnect"}},"/api/connected-cards/test/mandates/{mandateId}/revoke":{"post":{"tags":["Test Cards"],"summary":"Revoke a test authorization","description":"Cancels its pending and approved-but-unissued test purchases and releases their holds. An agent key is refused.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"mandateId","in":"path"}],"responses":{"200":{"description":"Authorization revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectedCardMandateRevokeResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Test authorization not found in this organization"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiConnectedCardsTestMandatesByMandateIdRevoke"}},"/api/connected-cards/test/orders/{orderId}":{"get":{"tags":["Test Cards"],"summary":"Read a simulated receipt","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"orderId","in":"path"}],"responses":{"200":{"description":"Receipt","content":{"application/json":{"schema":{"type":"object","properties":{"receipt":{"$ref":"#/components/schemas/TestReceipt"}},"required":["receipt"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Receipt not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiConnectedCardsTestOrdersByOrderId"}},"/api/sdk/connected-cards/test":{"get":{"tags":["Test Cards"],"summary":"List test cards for the agent","description":"The calling agent's test cards and active test authorizations, masked, plus the Conto test merchants and what they sell.","security":[{"sdkKeyAuth":[]}],"responses":{"200":{"description":"Test cards for the agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestCardListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkConnectedCardsTest"}},"/api/sdk/connected-cards/test/preview":{"post":{"tags":["Test Cards"],"summary":"Preview a test-card purchase","description":"Check a purchase against the agent's test-card limits and policies before asking for an authorization. Nothing is reserved and no credential is issued. The draw makes the final decision.","security":[{"sdkKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewConnectedCardPurchaseRequest"}}}},"responses":{"200":{"description":"Preview decision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewConnectedCardPurchaseResponse"}}}},"400":{"description":"Invalid request, or the test card is not active"},"404":{"description":"Test card not found for this agent"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkConnectedCardsTestPreview"}},"/api/sdk/connected-cards/test/draws":{"post":{"tags":["Test Cards"],"summary":"Request a single-use test credential","description":"Runs the connected-card draw pipeline in the test environment: the agent's limits, policies, human review, reservations, and idempotency. An approved draw returns testCredential once. A replay with the same idempotency key returns the decision without it. After a review is approved, resend the identical request with the same key.","security":[{"sdkKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrawTestCardRequest"}}}},"responses":{"200":{"description":"Draw outcome","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrawTestCardResponse"}}}},"400":{"description":"Merchant, amount, or authorization does not match"},"404":{"description":"Test card or authorization not found for this agent"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkConnectedCardsTestDraws"}},"/api/sdk/connected-cards/test/draws/{id}/acknowledge":{"post":{"tags":["Test Cards"],"summary":"Acknowledge test credential receipt","description":"Records receipt only. It is not a checkout and not a payment.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Receipt acknowledged","content":{"application/json":{"schema":{"type":"object","properties":{"environment":{"type":"string","enum":["test"]},"acknowledged":{"type":"boolean","enum":[true]},"settlementVerified":{"type":"boolean","enum":[false]}},"required":["environment","acknowledged","settlementVerified"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkConnectedCardsTestDrawsByIdAcknowledge"}},"/api/sdk/connected-cards/test/checkout":{"post":{"tags":["Test Cards"],"summary":"Complete a test checkout","description":"The Conto test checkout, the only place a test credential works. Completes one simulated order at the test merchant the authorization named and returns the receipt. Retrying with the same draw and credential returns the same receipt. No card is charged and no funds move.","security":[{"sdkKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestCheckoutRequest"}}}},"responses":{"200":{"description":"Replayed receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestCheckoutResponse"}}}},"201":{"description":"Order completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestCheckoutResponse"}}}},"400":{"description":"Not a test credential, or the credential expired"},"403":{"description":"The credential does not match this draw"},"404":{"description":"Test draw not found for this agent"},"409":{"description":"Declined: the order is above the credential amount, an item is not sold by this merchant, or the credential was already used"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkConnectedCardsTestCheckout"}},"/api/sdk/connected-cards/test/orders/{orderId}":{"get":{"tags":["Test Cards"],"summary":"Read one simulated receipt for this agent","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"orderId","in":"path"}],"responses":{"200":{"description":"Receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestReceipt"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Receipt not found for this agent"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkConnectedCardsTestOrdersByOrderId"}},"/api/policies":{"get":{"tags":["Policies"],"summary":"List all policies","description":"List all policies for the organization with their rules and assignments.","security":[{"sessionAuth":[]},{"orgApiKey":[]},{"sandboxSetupKey":[]}],"responses":{"200":{"description":"List of policies","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPolicies"},"post":{"tags":["Policies"],"summary":"Create a new policy","description":"Create a complete policy with explicit scope, optional inline rules, and optional agent assignments. `organization` applies automatically to every payment in the organization. `assigned` applies only through agent, wallet, or card assignments. For backwards compatibility, omitted scope is inferred as `assigned` when `agentIds` are present and `organization` otherwise. Rules and assignments are created atomically.","security":[{"sessionAuth":[]},{"orgApiKey":[]},{"sandboxSetupKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePolicyRequest"}}}},"responses":{"201":{"description":"Policy created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"400":{"description":"Validation error, including time, date, blackout, or geographic rule values the engine cannot read"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiPolicies"}},"/api/policies/simulate":{"post":{"tags":["Policies"],"summary":"Simulate a policy (dry run)","description":"Replay a candidate policy against the organization's real historical transactions and report what it would have decided, without saving anything. Read-only: no policy is created, no approval runs, no money moves. Rule types whose decision depends on state not present on a payment row (cumulative spend, velocity, live trust, geo, time-of-day) are not evaluated and are listed under summary.contextDependentRuleTypes.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulatePolicyRequest"}}}},"responses":{"200":{"description":"Simulation results and summary","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"transactionId":{"type":"string"},"agentId":{"type":["string","null"]},"amount":{"type":"number"},"currency":{"type":"string"},"category":{"type":["string","null"]},"recipient":{"type":"string"},"currentResult":{"type":"string"},"wouldBe":{"type":"string","enum":["ALLOW","DENY","REQUIRE_APPROVAL"]},"reasons":{"type":"array","items":{"type":"string"}},"changed":{"type":"boolean"}},"required":["transactionId","agentId","amount","currency","category","recipient","currentResult","wouldBe","reasons","changed"]}},"summary":{"type":"object","properties":{"total":{"type":"integer"},"allow":{"type":"integer"},"deny":{"type":"integer"},"requireApproval":{"type":"integer"},"newlyBlocked":{"type":"integer"},"newlyAllowed":{"type":"integer"},"contextDependentRuleTypes":{"type":"array","items":{"type":"string"}}},"required":["total","allow","deny","requireApproval","newlyBlocked","newlyAllowed","contextDependentRuleTypes"]}},"required":["results","summary"]}}}},"400":{"description":"Validation error"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiPoliciesSimulate"}},"/api/policies/{id}":{"get":{"tags":["Policies"],"summary":"Get policy by ID","security":[{"sessionAuth":[]},{"orgApiKey":[]},{"sandboxSetupKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Policy details with rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyWithRules"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Resource not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPoliciesById"},"patch":{"tags":["Policies"],"summary":"Update policy","description":"Update policy metadata or scope. Remove all target assignments before changing an assigned policy to organization scope.","security":[{"sessionAuth":[]},{"orgApiKey":[]},{"sandboxSetupKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePolicyRequest"}}}},"responses":{"200":{"description":"Policy updated"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Resource not found"},"409":{"description":"Scope conflicts with existing assignments"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"patchApiPoliciesById"},"delete":{"tags":["Policies"],"summary":"Delete policy","description":"Permanently delete a policy and remove it from all agents. Consider deactivating (PATCH with isActive: false) instead if you want to preserve the policy configuration.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Policy deleted"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Resource not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"deleteApiPoliciesById"}},"/api/policies/{id}/rules":{"get":{"tags":["Policies"],"summary":"List rules for a policy","security":[{"sessionAuth":[]},{"orgApiKey":[]},{"sandboxSetupKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"List of policy rules","content":{"application/json":{"schema":{"type":"object","properties":{"rules":{"type":"array","items":{"$ref":"#/components/schemas/PolicyRuleResponse"}}},"required":["rules"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPoliciesByIdRules"},"post":{"tags":["Policies"],"summary":"Add rules to a policy","description":"Add one or more rules to an existing policy. For new policies, provide rules inline when creating the policy. Rules use AND logic, so every rule must pass for a payment to be approved.","security":[{"sessionAuth":[]},{"orgApiKey":[]},{"sandboxSetupKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePolicyRulesRequest"}}}},"responses":{"201":{"description":"Rules added","content":{"application/json":{"schema":{"type":"object","properties":{"rules":{"type":"array","items":{"$ref":"#/components/schemas/PolicyRuleResponse"}},"count":{"type":"integer"}},"required":["rules","count"]}}}},"400":{"description":"Validation error, including time, date, blackout, or geographic rule values the engine cannot read"},"404":{"description":"Resource not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiPoliciesByIdRules"}},"/api/policies/{id}/versions":{"get":{"tags":["Policies"],"summary":"List policy version history","description":"Every change to a policy's definition or rules appends an immutable version. Returns the version history newest first. Assignments are not part of a version.","security":[{"sessionAuth":[]},{"orgApiKey":[]},{"sandboxSetupKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Version history","content":{"application/json":{"schema":{"type":"object","properties":{"versions":{"type":"array","items":{"type":"object","properties":{"version":{"type":"integer"},"changeType":{"type":"string","enum":["CREATED","UPDATED","RULES_CHANGED","ROLLED_BACK"]},"note":{"type":["string","null"]},"createdBy":{"type":["string","null"]},"createdByType":{"type":["string","null"]},"createdAt":{"type":"string"},"rulesCount":{"type":"integer"}},"required":["version","changeType","note","createdBy","createdByType","createdAt","rulesCount"]}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["versions","total","limit","offset"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Resource not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPoliciesByIdVersions"}},"/api/policies/{id}/versions/compare":{"get":{"tags":["Policies"],"summary":"Compare two policy versions","description":"Diff two versions of a policy. Metadata fields are compared directly. Rules are compared by content, so an edited rule appears as one removed and one added.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1},"required":true,"name":"from","in":"query"},{"schema":{"type":"integer","minimum":1},"required":true,"name":"to","in":"query"}],"responses":{"200":{"description":"Diff between the two versions","content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"integer"},"to":{"type":"integer"},"diff":{"type":"object","properties":{"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"from":{},"to":{}},"required":["field"]}},"rulesAdded":{"type":"array","items":{"type":"object","properties":{"ruleType":{"type":"string"},"operator":{"type":"string"},"value":{"type":"string"},"action":{"type":"string"}},"required":["ruleType","operator","value","action"]}},"rulesRemoved":{"type":"array","items":{"type":"object","properties":{"ruleType":{"type":"string"},"operator":{"type":"string"},"value":{"type":"string"},"action":{"type":"string"}},"required":["ruleType","operator","value","action"]}},"unchanged":{"type":"boolean"}},"required":["fields","rulesAdded","rulesRemoved","unchanged"]}},"required":["from","to","diff"]}}}},"400":{"description":"Validation error"},"404":{"description":"Resource not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPoliciesByIdVersionsCompare"}},"/api/policies/{id}/versions/{version}":{"get":{"tags":["Policies"],"summary":"Get a policy version snapshot","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1},"required":true,"name":"version","in":"path"}],"responses":{"200":{"description":"Version snapshot","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"integer"},"changeType":{"type":"string","enum":["CREATED","UPDATED","RULES_CHANGED","ROLLED_BACK"]},"note":{"type":["string","null"]},"createdBy":{"type":["string","null"]},"createdByType":{"type":["string","null"]},"createdAt":{"type":"string"},"snapshot":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":["string","null"]},"policyType":{"type":"string"},"scope":{"type":"string","enum":["organization","assigned"]},"priority":{"type":"integer"},"isActive":{"type":"boolean"},"rules":{"type":"array","items":{"type":"object","properties":{"ruleType":{"type":"string"},"operator":{"type":"string"},"value":{"type":"string"},"action":{"type":"string"}},"required":["ruleType","operator","value","action"]}}},"required":["name","description","policyType","scope","priority","isActive","rules"]}},"required":["version","changeType","note","createdBy","createdByType","createdAt","snapshot"]}}}},"400":{"description":"Validation error"},"404":{"description":"Resource not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPoliciesByIdVersionsByVersion"}},"/api/policies/{id}/versions/{version}/rollback":{"post":{"tags":["Policies"],"summary":"Roll back a policy to an earlier version","description":"Restore a policy's definition and rules from an earlier version. This is itself a change, so it appends a new ROLLED_BACK version and, when the organization requires it, goes through the governance approval workflow. policyType is immutable and is not changed.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":1},"required":true,"name":"version","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"Policy restored to the target version"},"400":{"description":"Validation error"},"404":{"description":"Resource not found"},"409":{"description":"Scope conflicts with existing assignments"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiPoliciesByIdVersionsByVersionRollback"}},"/api/contract-registry":{"get":{"tags":["Policies"],"summary":"List known contract classifications","description":"List organization-owned contract metadata used to resolve protocol names and categories during contract policy evaluation.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string","maxLength":50},"required":false,"name":"category","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Paginated contract classifications","content":{"application/json":{"schema":{"type":"object","properties":{"contracts":{"type":"array","items":{"type":"object","properties":{"address":{"type":"string"},"chainId":{"type":"string"},"label":{"type":"string"},"protocolName":{"type":"string"},"protocolCategory":{"type":"string"}},"required":["address"]}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["contracts","total","limit","offset"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiContractRegistry"},"post":{"tags":["Policies"],"summary":"Save a contract classification","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","minLength":1,"maxLength":100},"chainId":{"type":"string","minLength":1,"maxLength":20},"label":{"type":"string","minLength":1,"maxLength":200},"protocolName":{"type":"string","minLength":1,"maxLength":100},"protocolCategory":{"type":"string","minLength":1,"maxLength":50}},"required":["address"],"additionalProperties":false}}}},"responses":{"201":{"description":"Contract classification saved","content":{"application/json":{"schema":{"type":"object","properties":{"contract":{"type":"object","properties":{"address":{"type":"string"},"chainId":{"type":"string"},"label":{"type":"string"},"protocolName":{"type":"string"},"protocolCategory":{"type":"string"}},"required":["address"]}},"required":["contract"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiContractRegistry"}},"/api/contract-registry/{address}":{"get":{"tags":["Policies"],"summary":"Get a contract classification","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100},"required":true,"name":"address","in":"path"}],"responses":{"200":{"description":"Contract classification","content":{"application/json":{"schema":{"type":"object","properties":{"contract":{"type":"object","properties":{"address":{"type":"string"},"chainId":{"type":"string"},"label":{"type":"string"},"protocolName":{"type":"string"},"protocolCategory":{"type":"string"}},"required":["address"]}},"required":["contract"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Contract classification not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiContractRegistryByAddress"},"patch":{"tags":["Policies"],"summary":"Update a contract classification","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100},"required":true,"name":"address","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"chainId":{"type":"string","minLength":1,"maxLength":20},"label":{"type":"string","minLength":1,"maxLength":200},"protocolName":{"type":"string","minLength":1,"maxLength":100},"protocolCategory":{"type":"string","minLength":1,"maxLength":50}},"additionalProperties":false}}}},"responses":{"200":{"description":"Contract classification","content":{"application/json":{"schema":{"type":"object","properties":{"contract":{"type":"object","properties":{"address":{"type":"string"},"chainId":{"type":"string"},"label":{"type":"string"},"protocolName":{"type":"string"},"protocolCategory":{"type":"string"}},"required":["address"]}},"required":["contract"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Contract classification not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"patchApiContractRegistryByAddress"},"delete":{"tags":["Policies"],"summary":"Delete a contract classification","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100},"required":true,"name":"address","in":"path"}],"responses":{"200":{"description":"Contract classification deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]},"address":{"type":"string"}},"required":["deleted","address"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Contract classification not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"deleteApiContractRegistryByAddress"}},"/api/approval-workflows":{"get":{"tags":["Approval Workflows"],"summary":"List approval workflows","description":"List the approval controls configured for the organization, including stable trigger, reviewer, timeout, escalation, and usage summaries.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"boolean"},"required":false,"name":"enabled","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Approval workflows","content":{"application/json":{"schema":{"type":"object","properties":{"workflows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"enabled":{"type":"boolean"},"priority":{"type":"integer"},"triggers":{"type":"object","properties":{"minimumAmount":{"type":"number"},"currency":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"agentIds":{"type":"array","items":{"type":"string"}},"agentTypes":{"type":"array","items":{"type":"string"}},"newRecipients":{"type":"boolean","enum":[true]},"counterpartyTrustLevels":{"type":"array","items":{"type":"string","enum":["TRUSTED","VERIFIED","UNKNOWN","SUSPICIOUS","BLOCKED"]}}},"additionalProperties":false},"approvals":{"type":"object","properties":{"required":{"type":"integer"},"order":{"type":"string","enum":["any_order","sequential"]},"allowRequester":{"type":"boolean"},"approvers":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["roles"]},"roles":{"type":"array","items":{"type":"string","enum":["OWNER","ADMIN","MANAGER"]},"minItems":1,"maxItems":3}},"required":["type","roles"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["specific_members"]},"membershipIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":100}},"required":["type","membershipIds"],"additionalProperties":false}]},"steps":{"type":["array","null"],"items":{"type":"object","properties":{"position":{"type":"integer","exclusiveMinimum":0},"membershipId":{"type":"string"}},"required":["position","membershipId"],"additionalProperties":false}}},"required":["required","order","allowRequester","approvers","steps"],"additionalProperties":false},"expiresAfterHours":{"type":["integer","null"]},"escalation":{"type":["object","null"],"properties":{"afterHours":{"type":"integer","minimum":1,"maximum":8760},"roles":{"type":"array","items":{"type":"string","enum":["OWNER","ADMIN","MANAGER"]},"maxItems":3,"default":[]},"membershipIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":100,"default":[]}},"required":["afterHours"],"additionalProperties":false},"requestCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","description","enabled","priority","triggers","approvals","expiresAfterHours","escalation","requestCount","createdAt","updatedAt"],"additionalProperties":false}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["workflows","total","limit","offset"],"additionalProperties":false}}}},"400":{"description":"Invalid filters"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient permission"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiApprovalWorkflows"},"post":{"tags":["Approval Workflows"],"summary":"Create an approval workflow","description":"Create a workflow that routes matching payments to role-based or named reviewers. Sequential review is supported for an ordered list of organization members.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":["string","null"],"maxLength":500,"default":null},"triggers":{"type":"object","properties":{"minimumAmount":{"type":"number","minimum":0},"currency":{"type":"string","minLength":1,"maxLength":20},"categories":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":100},"agentIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":100},"agentTypes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":100},"newRecipients":{"type":"boolean","enum":[true]},"counterpartyTrustLevels":{"type":"array","items":{"type":"string","enum":["TRUSTED","VERIFIED","UNKNOWN","SUSPICIOUS","BLOCKED"]},"minItems":1,"maxItems":5}},"additionalProperties":false},"approvals":{"type":"object","properties":{"required":{"type":"integer","minimum":1,"maximum":10,"default":2},"order":{"type":"string","enum":["any_order","sequential"],"default":"any_order"},"allowRequester":{"type":"boolean","default":false},"approvers":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["roles"]},"roles":{"type":"array","items":{"type":"string","enum":["OWNER","ADMIN","MANAGER"]},"minItems":1,"maxItems":3}},"required":["type","roles"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["specific_members"]},"membershipIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":100}},"required":["type","membershipIds"],"additionalProperties":false}],"default":{"type":"roles","roles":["OWNER","ADMIN"]}}},"default":{},"additionalProperties":false},"expiresAfterHours":{"type":["integer","null"],"minimum":1,"maximum":168,"default":24},"escalation":{"type":["object","null"],"properties":{"afterHours":{"type":"integer","minimum":1,"maximum":8760},"roles":{"type":"array","items":{"type":"string","enum":["OWNER","ADMIN","MANAGER"]},"maxItems":3,"default":[]},"membershipIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":100,"default":[]}},"default":null,"required":["afterHours"],"additionalProperties":false},"priority":{"type":"integer","minimum":0,"maximum":100,"default":0},"enabled":{"type":"boolean","default":true}},"required":["name","triggers"],"additionalProperties":false}}}},"responses":{"201":{"description":"Approval workflow created","content":{"application/json":{"schema":{"type":"object","properties":{"workflow":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"enabled":{"type":"boolean"},"priority":{"type":"integer"},"triggers":{"type":"object","properties":{"minimumAmount":{"type":"number"},"currency":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"agentIds":{"type":"array","items":{"type":"string"}},"agentTypes":{"type":"array","items":{"type":"string"}},"newRecipients":{"type":"boolean","enum":[true]},"counterpartyTrustLevels":{"type":"array","items":{"type":"string","enum":["TRUSTED","VERIFIED","UNKNOWN","SUSPICIOUS","BLOCKED"]}}},"additionalProperties":false},"approvals":{"type":"object","properties":{"required":{"type":"integer"},"order":{"type":"string","enum":["any_order","sequential"]},"allowRequester":{"type":"boolean"},"approvers":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["roles"]},"roles":{"type":"array","items":{"type":"string","enum":["OWNER","ADMIN","MANAGER"]},"minItems":1,"maxItems":3}},"required":["type","roles"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["specific_members"]},"membershipIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":100}},"required":["type","membershipIds"],"additionalProperties":false}]},"steps":{"type":["array","null"],"items":{"type":"object","properties":{"position":{"type":"integer","exclusiveMinimum":0},"membershipId":{"type":"string"}},"required":["position","membershipId"],"additionalProperties":false}}},"required":["required","order","allowRequester","approvers","steps"],"additionalProperties":false},"expiresAfterHours":{"type":["integer","null"]},"escalation":{"type":["object","null"],"properties":{"afterHours":{"type":"integer","minimum":1,"maximum":8760},"roles":{"type":"array","items":{"type":"string","enum":["OWNER","ADMIN","MANAGER"]},"maxItems":3,"default":[]},"membershipIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":100,"default":[]}},"required":["afterHours"],"additionalProperties":false},"requestCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","description","enabled","priority","triggers","approvals","expiresAfterHours","escalation","requestCount","createdAt","updatedAt"],"additionalProperties":false}},"required":["workflow"],"additionalProperties":false}}}},"202":{"description":"The organization requires governance approval for this change. Nothing is applied. After approval, resend the identical request with the x-governance-approval-id header within 15 minutes."},"400":{"description":"Invalid workflow, agent scope, or reviewer"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient permission"},"409":{"description":"The governance approval is not approved, has expired, or no longer matches this request"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiApprovalWorkflows"}},"/api/approval-workflows/{workflowId}":{"get":{"tags":["Approval Workflows"],"summary":"Get an approval workflow","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Approval workflow ID"},"required":true,"name":"workflowId","in":"path"}],"responses":{"200":{"description":"Approval workflow","content":{"application/json":{"schema":{"type":"object","properties":{"workflow":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"enabled":{"type":"boolean"},"priority":{"type":"integer"},"triggers":{"type":"object","properties":{"minimumAmount":{"type":"number"},"currency":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"agentIds":{"type":"array","items":{"type":"string"}},"agentTypes":{"type":"array","items":{"type":"string"}},"newRecipients":{"type":"boolean","enum":[true]},"counterpartyTrustLevels":{"type":"array","items":{"type":"string","enum":["TRUSTED","VERIFIED","UNKNOWN","SUSPICIOUS","BLOCKED"]}}},"additionalProperties":false},"approvals":{"type":"object","properties":{"required":{"type":"integer"},"order":{"type":"string","enum":["any_order","sequential"]},"allowRequester":{"type":"boolean"},"approvers":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["roles"]},"roles":{"type":"array","items":{"type":"string","enum":["OWNER","ADMIN","MANAGER"]},"minItems":1,"maxItems":3}},"required":["type","roles"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["specific_members"]},"membershipIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":100}},"required":["type","membershipIds"],"additionalProperties":false}]},"steps":{"type":["array","null"],"items":{"type":"object","properties":{"position":{"type":"integer","exclusiveMinimum":0},"membershipId":{"type":"string"}},"required":["position","membershipId"],"additionalProperties":false}}},"required":["required","order","allowRequester","approvers","steps"],"additionalProperties":false},"expiresAfterHours":{"type":["integer","null"]},"escalation":{"type":["object","null"],"properties":{"afterHours":{"type":"integer","minimum":1,"maximum":8760},"roles":{"type":"array","items":{"type":"string","enum":["OWNER","ADMIN","MANAGER"]},"maxItems":3,"default":[]},"membershipIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":100,"default":[]}},"required":["afterHours"],"additionalProperties":false},"requestCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","description","enabled","priority","triggers","approvals","expiresAfterHours","escalation","requestCount","createdAt","updatedAt"],"additionalProperties":false}},"required":["workflow"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Approval workflow not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiApprovalWorkflowsByWorkflowId"},"patch":{"tags":["Approval Workflows"],"summary":"Update an approval workflow","description":"Update supported workflow settings. The triggers object replaces the current trigger set; nested approval settings can be patched individually.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Approval workflow ID"},"required":true,"name":"workflowId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":["string","null"],"maxLength":500},"triggers":{"type":"object","properties":{"minimumAmount":{"type":"number","minimum":0},"currency":{"type":"string","minLength":1,"maxLength":20},"categories":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":100},"agentIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":100},"agentTypes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":100},"newRecipients":{"type":"boolean","enum":[true]},"counterpartyTrustLevels":{"type":"array","items":{"type":"string","enum":["TRUSTED","VERIFIED","UNKNOWN","SUSPICIOUS","BLOCKED"]},"minItems":1,"maxItems":5}},"additionalProperties":false},"approvals":{"type":"object","properties":{"required":{"type":"integer","minimum":1,"maximum":10},"order":{"type":"string","enum":["any_order","sequential"]},"allowRequester":{"type":"boolean"},"approvers":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["roles"]},"roles":{"type":"array","items":{"type":"string","enum":["OWNER","ADMIN","MANAGER"]},"minItems":1,"maxItems":3}},"required":["type","roles"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["specific_members"]},"membershipIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":100}},"required":["type","membershipIds"],"additionalProperties":false}]}},"additionalProperties":false},"expiresAfterHours":{"type":["integer","null"],"minimum":1,"maximum":168},"escalation":{"type":["object","null"],"properties":{"afterHours":{"type":"integer","minimum":1,"maximum":8760},"roles":{"type":"array","items":{"type":"string","enum":["OWNER","ADMIN","MANAGER"]},"maxItems":3,"default":[]},"membershipIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":100,"default":[]}},"required":["afterHours"],"additionalProperties":false},"priority":{"type":"integer","minimum":0,"maximum":100},"enabled":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Approval workflow updated","content":{"application/json":{"schema":{"type":"object","properties":{"workflow":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"enabled":{"type":"boolean"},"priority":{"type":"integer"},"triggers":{"type":"object","properties":{"minimumAmount":{"type":"number"},"currency":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"agentIds":{"type":"array","items":{"type":"string"}},"agentTypes":{"type":"array","items":{"type":"string"}},"newRecipients":{"type":"boolean","enum":[true]},"counterpartyTrustLevels":{"type":"array","items":{"type":"string","enum":["TRUSTED","VERIFIED","UNKNOWN","SUSPICIOUS","BLOCKED"]}}},"additionalProperties":false},"approvals":{"type":"object","properties":{"required":{"type":"integer"},"order":{"type":"string","enum":["any_order","sequential"]},"allowRequester":{"type":"boolean"},"approvers":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["roles"]},"roles":{"type":"array","items":{"type":"string","enum":["OWNER","ADMIN","MANAGER"]},"minItems":1,"maxItems":3}},"required":["type","roles"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["specific_members"]},"membershipIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":100}},"required":["type","membershipIds"],"additionalProperties":false}]},"steps":{"type":["array","null"],"items":{"type":"object","properties":{"position":{"type":"integer","exclusiveMinimum":0},"membershipId":{"type":"string"}},"required":["position","membershipId"],"additionalProperties":false}}},"required":["required","order","allowRequester","approvers","steps"],"additionalProperties":false},"expiresAfterHours":{"type":["integer","null"]},"escalation":{"type":["object","null"],"properties":{"afterHours":{"type":"integer","minimum":1,"maximum":8760},"roles":{"type":"array","items":{"type":"string","enum":["OWNER","ADMIN","MANAGER"]},"maxItems":3,"default":[]},"membershipIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":100,"default":[]}},"required":["afterHours"],"additionalProperties":false},"requestCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","description","enabled","priority","triggers","approvals","expiresAfterHours","escalation","requestCount","createdAt","updatedAt"],"additionalProperties":false}},"required":["workflow"],"additionalProperties":false}}}},"202":{"description":"The organization requires governance approval for this change. Nothing is applied. After approval, resend the identical request with the x-governance-approval-id header within 15 minutes."},"400":{"description":"Invalid workflow, agent scope, or reviewer"},"404":{"description":"Approval workflow not found"},"409":{"description":"The governance approval is not approved, has expired, or no longer matches this request"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"patchApiApprovalWorkflowsByWorkflowId"},"delete":{"tags":["Approval Workflows"],"summary":"Delete an approval workflow","description":"Delete a workflow after all pending approval requests have been resolved.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Approval workflow ID"},"required":true,"name":"workflowId","in":"path"}],"responses":{"200":{"description":"Approval workflow deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","enum":[true]},"workflowId":{"type":"string"}},"required":["deleted","workflowId"],"additionalProperties":false}}}},"202":{"description":"The organization requires governance approval for this change. Nothing is applied. After approval, resend the identical request with the x-governance-approval-id header within 15 minutes."},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Approval workflow not found"},"409":{"description":"Workflow still has pending approval requests, or the governance approval is not approved, has expired, or no longer matches this request"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"deleteApiApprovalWorkflowsByWorkflowId"}},"/api/governance/approval-settings":{"get":{"tags":["Governance Approvals"],"summary":"Get governance approval settings","description":"Return which organization changes need a second person to approve them, such as API key and policy changes. Requires `org:read`.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"responses":{"200":{"description":"Current settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GovernanceApprovalSettings"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Missing org:read scope"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiGovernanceApprovalSettings"}},"/api/governance/approval-requests":{"get":{"tags":["Governance Approvals"],"summary":"List governance approval requests","description":"When a change needs approval, the endpoint you called returns 202 with `requiresGovernanceApproval: true` and an `approvalRequest`. Poll this list for its status. An organization owner or admin other than the requester decides it in the Conto dashboard. After approval, send the identical request again with the `x-governance-approval-id` header. Requires `org:read`.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["PENDING","APPROVED","REJECTED","EXPIRED","CONSUMED"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Governance approval requests, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"requests":{"type":"array","items":{"$ref":"#/components/schemas/GovernanceApprovalRequest"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"availableActions":{"type":"array","items":{"$ref":"#/components/schemas/GovernanceApprovalAction"}}},"required":["requests","total","limit","offset","availableActions"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Missing org:read scope"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiGovernanceApprovalRequests"}},"/api/notification-channels":{"get":{"tags":["Notification Channels"],"summary":"List notification channels","description":"List the channels that deliver approval requests and payment events for the organization. Requires `policies:read`.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"responses":{"200":{"description":"Notification channels, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"channels":{"type":"array","items":{"$ref":"#/components/schemas/NotificationChannel"}}},"required":["channels"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Missing policies:read scope"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiNotificationChannels"},"post":{"tags":["Notification Channels"],"summary":"Create a notification channel","description":"Send approval requests and payment events to email, Slack, Telegram, WhatsApp, or a signed webhook. Webhook URLs must be publicly reachable. Requires `policies:write`.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNotificationChannelRequest"}}}},"responses":{"201":{"description":"Channel created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationChannel"}}}},"400":{"description":"Invalid settings, or an event is not supported for this channel type"},"401":{"description":"Authentication required"},"403":{"description":"Missing policies:write scope"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiNotificationChannels"}},"/api/notification-channels/{id}":{"get":{"tags":["Notification Channels"],"summary":"Get a notification channel","description":"Return one channel. Requires `policies:read`.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Notification channel ID"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Notification channel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationChannel"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Missing policies:read scope"},"404":{"description":"Channel not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiNotificationChannelsById"},"patch":{"tags":["Notification Channels"],"summary":"Update a notification channel","description":"Rename a channel, change its destination or events, or pause it with `isActive: false`. Requires `policies:write`.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Notification channel ID"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateNotificationChannelRequest"}}}},"responses":{"200":{"description":"Updated channel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationChannel"}}}},"400":{"description":"Invalid settings, or an event is not supported for this channel type"},"401":{"description":"Authentication required"},"403":{"description":"Missing policies:write scope"},"404":{"description":"Channel not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"patchApiNotificationChannelsById"},"delete":{"tags":["Notification Channels"],"summary":"Delete a notification channel","description":"Stop all deliveries to this channel and remove it. Requires `policies:write`.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Notification channel ID"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Channel deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]}},"required":["success"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Missing policies:write scope"},"404":{"description":"Channel not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"deleteApiNotificationChannelsById"}},"/api/notification-channels/{id}/test":{"post":{"tags":["Notification Channels"],"summary":"Send a test notification","description":"Deliver a sample approval request to the channel to confirm the destination works. No payment or approval is created. Requires `policies:write`.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string","description":"Notification channel ID"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Test notification delivered","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"message":{"type":"string"}},"required":["success","message"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Missing policies:write scope"},"404":{"description":"Channel not found"},"500":{"$ref":"#/components/responses/InternalServerError"},"502":{"description":"The destination did not accept the test notification"}},"operationId":"postApiNotificationChannelsByIdTest"}},"/api/organizations/me/members":{"get":{"tags":["Organization Members"],"summary":"List organization members","description":"List the members of the organization that owns the credential, oldest first. Requires `team:read` or `agents:write`.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"responses":{"200":{"description":"Organization members","content":{"application/json":{"schema":{"type":"object","properties":{"members":{"type":"array","items":{"$ref":"#/components/schemas/OrganizationMember"}}},"required":["members"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Missing team:read or agents:write scope"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiOrganizationsMeMembers"}},"/api/conto-pay/analytics":{"get":{"tags":["Analytics"],"summary":"Get Conto Pay activity analytics","description":"Returns organization-scoped activity totals, conversion rates, and stage counts for dashboards and reconciliation exports.","security":[{"sessionAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["24h","7d","30d","90d"],"default":"7d"},"required":false,"name":"period","in":"query"},{"schema":{"type":"string","enum":["json","csv"],"default":"json"},"required":false,"name":"format","in":"query"}],"responses":{"200":{"description":"Conto Pay activity analytics or CSV export","content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"string","enum":["24h","7d","30d","90d"]},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"totals":{"type":"object","properties":{"profileViews":{"type":"integer","minimum":0},"checkoutLinksCreated":{"type":"integer","minimum":0},"checkoutLinkOpens":{"type":"integer","minimum":0},"checkoutLinksCancelled":{"type":"integer","minimum":0},"requestsCreated":{"type":"integer","minimum":0},"requestsPrepared":{"type":"integer","minimum":0},"draftsPrepared":{"type":"integer","minimum":0},"authorizations":{"type":"integer","minimum":0},"sendsAttempted":{"type":"integer","minimum":0},"sendsSucceeded":{"type":"integer","minimum":0},"sendsFailed":{"type":"integer","minimum":0},"retryAttempts":{"type":"integer","minimum":0},"retrySucceeded":{"type":"integer","minimum":0},"retryFailed":{"type":"integer","minimum":0},"inspections":{"type":"integer","minimum":0},"statusViews":{"type":"integer","minimum":0}},"required":["profileViews","checkoutLinksCreated","checkoutLinkOpens","checkoutLinksCancelled","requestsCreated","requestsPrepared","draftsPrepared","authorizations","sendsAttempted","sendsSucceeded","sendsFailed","retryAttempts","retrySucceeded","retryFailed","inspections","statusViews"]},"conversion":{"type":"object","properties":{"sendSuccessRate":{"type":"number"},"authorizationToSendRate":{"type":"number"},"requestPrepareRate":{"type":"number"},"checkoutOpenRate":{"type":"number"},"sendFailureRate":{"type":"number"}},"required":["sendSuccessRate","authorizationToSendRate","requestPrepareRate","checkoutOpenRate","sendFailureRate"]},"stages":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"count":{"type":"integer","minimum":0},"latestAt":{"type":["string","null"],"format":"date-time"}},"required":["key","label","count","latestAt"]}}},"required":["period","startDate","endDate","totals","conversion","stages"]}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Invalid query"},"401":{"description":"Authentication required"},"403":{"description":"Organization access denied"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiContoPayAnalytics"}},"/api/conto-pay/cards":{"get":{"tags":["Conto Pay"],"summary":"Get Conto Pay connected cards","description":"Returns the organization's connected cards with masked card details, the agents each card is delegated to, their limits and spend today, authorization counts, card purchases waiting for review, and recent card purchases. Read-only. Returns availability `upgrade` when the plan does not include connected cards and `unavailable` when connected cards are not available to the organization.","security":[{"sessionAuth":[]}],"responses":{"200":{"description":"Connected-card summary for the Conto Pay dashboard","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"availability":{"type":"string","enum":["unavailable"]}},"required":["availability"]},{"type":"object","properties":{"availability":{"type":"string","enum":["upgrade"]},"suggestedPlan":{"type":"string","example":"BUILDER"},"canManageBilling":{"type":"boolean"}},"required":["availability","suggestedPlan","canManageBilling"]},{"type":"object","properties":{"availability":{"type":"string","enum":["ready"]},"cards":{"type":"array","items":{"type":"object","properties":{"cardId":{"type":"string"},"brand":{"type":["string","null"]},"last4":{"type":"string","example":"4242"},"state":{"type":"string","enum":["active","setup","paused","inactive"]},"statusLabel":{"type":"string","example":"Active"},"activeAuthorizationCount":{"type":"integer","minimum":0},"awaitingVerificationCount":{"type":"integer","minimum":0},"agents":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string"},"agentName":{"type":"string"},"perPurchaseLimit":{"type":["number","null"]},"dailyLimit":{"type":["number","null"]},"spentToday":{"type":["number","null"]}},"required":["agentId","agentName","perPurchaseLimit","dailyLimit","spentToday"]}}},"required":["cardId","brand","last4","state","statusLabel","activeAuthorizationCount","awaitingVerificationCount","agents"]}},"pendingReviewCount":{"type":"integer","minimum":0},"recentDraws":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string","example":"USD"},"merchantName":{"type":["string","null"]},"agentId":{"type":"string"},"agentName":{"type":"string"},"cardBrand":{"type":["string","null"]},"cardLast4":{"type":"string"},"state":{"type":"string","enum":["waiting","in_progress","done","stopped"]},"statusLabel":{"type":"string","example":"Completed"},"requestedAt":{"type":"string","format":"date-time"}},"required":["id","amount","currency","merchantName","agentId","agentName","cardBrand","cardLast4","state","statusLabel","requestedAt"]}},"canAddCard":{"type":"boolean"}},"required":["availability","cards","pendingReviewCount","recentDraws","canAddCard"]}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Organization access denied"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiContoPayCards"}},"/api/conto-pay/readiness":{"get":{"tags":["Conto Pay"],"summary":"Get Conto Pay launch readiness","description":"Returns setup, payment-mode, controls, and test-flow context without private operational fields.","security":[{"sessionAuth":[]}],"responses":{"200":{"description":"Customer launch readiness","content":{"application/json":{"schema":{"type":"object","properties":{"readiness":{"type":"object","properties":{"setup":{"type":"object","properties":{"status":{"type":"string","enum":["ready","attention_needed"]},"progress":{"type":"string"},"nextAction":{"type":["string","null"]}},"required":["status","progress","nextAction"]},"readiness":{"type":"object","properties":{"status":{"type":"string","enum":["setup_required","testing_required","ready_to_request","request_pending","live_enabled"]},"label":{"type":"string"},"livePaymentsEnabled":{"type":"boolean"},"canRequestProductionAccess":{"type":"boolean"},"productionAccessStatus":{"type":"string","enum":["not_requested","requested","under_review","completed"]},"blockerCount":{"type":"integer","minimum":0},"warningCount":{"type":"integer","minimum":0},"blockers":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}},"nextAction":{"type":"string"}},"required":["status","label","livePaymentsEnabled","canRequestProductionAccess","productionAccessStatus","blockerCount","warningCount","blockers","warnings","nextAction"]},"paymentMode":{"type":"object","properties":{"mode":{"type":"string","enum":["setup_required","sandbox","production_access_pending","live"]},"label":{"type":"string"},"sandboxPaymentsEnabled":{"type":"boolean"},"livePaymentsEnabled":{"type":"boolean"},"canPrepareSandboxPayments":{"type":"boolean"},"canPresentLivePayments":{"type":"boolean"},"productionAccessStatus":{"type":"string","enum":["not_requested","requested","under_review","completed"]},"userInstruction":{"type":"string"}},"required":["mode","label","sandboxPaymentsEnabled","livePaymentsEnabled","canPrepareSandboxPayments","canPresentLivePayments","productionAccessStatus","userInstruction"]},"profile":{"type":"object","properties":{"handle":{"type":"string"},"displayName":{"type":"string"},"aliases":{"type":"array","items":{}},"directoryListed":{"type":"boolean"},"acceptsPayments":{"type":"boolean"},"profileUrl":{"type":"string","format":"uri"},"profileApiUrl":{"type":"string","format":"uri"}},"required":["handle","displayName","aliases","directoryListed","acceptsPayments","profileUrl","profileApiUrl"]},"wallet":{"type":"object","properties":{"provisioned":{"type":"boolean"},"chainId":{"type":["string","null"]},"chainName":{"type":["string","null"]},"currency":{"type":"string"},"balance":{"type":["number","null"]}},"required":["provisioned","chainId","chainName","currency","balance"]},"controls":{"type":"object","properties":{"approvalWorkflowConfigured":{"type":"boolean"},"pendingApprovals":{"type":"integer","minimum":0},"pendingIncomingRequests":{"type":"integer","minimum":0}},"required":["approvalWorkflowConfigured","pendingApprovals","pendingIncomingRequests"]},"evidence":{"type":"object","properties":{"recipients":{"type":"integer","minimum":0},"contacts":{"type":"integer","minimum":0},"checkoutLinks":{"type":"integer","minimum":0},"activeCheckoutLinks":{"type":"integer","minimum":0},"latestCheckoutLink":{"type":["object","null"],"properties":{"mode":{"type":"string"},"status":{"type":"string"},"openCount":{"type":"integer","minimum":0},"lastOpenedAt":{"type":["string","null"],"format":"date-time"},"hostedProfileUrl":{"type":"string","format":"uri"}},"required":["mode","status","openCount","lastOpenedAt","hostedProfileUrl"]},"latestActivity":{"type":["object","null"],"properties":{"kind":{"type":"string"},"direction":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"},"primaryUrl":{"type":["string","null"],"format":"uri"}},"required":["kind","direction","status","title","primaryUrl"]}},"required":["recipients","contacts","checkoutLinks","activeCheckoutLinks","latestCheckoutLink","latestActivity"]}},"required":["setup","readiness","paymentMode","profile","wallet","controls","evidence"]}},"required":["readiness"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Organization access denied"},"409":{"description":"Conto Pay is not set up"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiContoPayReadiness"}},"/api/conto-pay/production-access":{"post":{"tags":["Conto Pay"],"summary":"Request Conto Pay production access","description":"Requests production access for live payments and returns stable status and next-action fields.","security":[{"sessionAuth":[]}],"responses":{"200":{"description":"Production-access request status","content":{"application/json":{"schema":{"type":"object","properties":{"productionAccess":{"type":"object","properties":{"requestId":{"type":["string","null"]},"status":{"type":"string","enum":["not_requested","requested","under_review","completed"]},"statusLabel":{"type":"string"},"message":{"type":"string"},"requestedAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"nextAction":{"type":"string"}},"required":["requestId","status","statusLabel","message","requestedAt","updatedAt","resolvedAt","nextAction"]}},"required":["productionAccess"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Organization access denied"},"409":{"description":"Workspace is not ready or live payments are already enabled"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiContoPayProductionAccess"}},"/api/conto-pay/reports":{"get":{"tags":["Alerts"],"summary":"List Conto Pay trust reports","description":"List trust reports concerning the current organization’s Conto Pay profiles. Requires alert read permission.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":25,"default":8},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Trust reports","content":{"application/json":{"schema":{"type":"object","properties":{"reports":{"type":"array","items":{"type":"object","properties":{"reportId":{"type":"string"},"status":{"type":"string","enum":["received","reviewing","resolved","closed"]},"statusLabel":{"type":"string"},"outcome":{"type":["string","null"],"enum":["profile_hidden_from_directory"]},"outcomeLabel":{"type":["string","null"]},"handle":{"type":["string","null"]},"reason":{"type":["string","null"]},"reasonLabel":{"type":["string","null"]},"checkoutIntentId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"message":{"type":"string"},"nextStep":{"type":["string","null"]},"severity":{"type":"string","enum":["high","medium","standard"]},"summary":{"type":"string"},"profileUrl":{"type":["string","null"]},"submittedProfileUrl":{"type":["string","null"]},"reportedDisplayName":{"type":["string","null"]},"details":{"type":["string","null"]},"action":{"type":["string","null"],"enum":["review_only","hide_profile_from_directory"]},"actionLabel":{"type":["string","null"]},"actionedAt":{"type":["string","null"],"format":"date-time"},"statusUrl":{"type":"string"}},"required":["reportId","status","statusLabel","outcome","outcomeLabel","handle","reason","reasonLabel","checkoutIntentId","createdAt","updatedAt","resolvedAt","message","nextStep","severity","summary","profileUrl","submittedProfileUrl","reportedDisplayName","details","action","actionLabel","actionedAt","statusUrl"]}}},"required":["reports"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiContoPayReports"}},"/api/conto-pay/reports/{reportId}":{"patch":{"tags":["Alerts"],"summary":"Review a Conto Pay trust report","description":"Update review status and optionally hide the reported profile from broad directory search. Requires alert management permission.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"reportId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["reviewing","resolved","closed"]},"action":{"type":"string","enum":["review_only","hide_profile_from_directory"]}},"required":["status"],"additionalProperties":false}}}},"responses":{"200":{"description":"Updated report","content":{"application/json":{"schema":{"type":"object","properties":{"report":{"type":"object","properties":{"reportId":{"type":"string"},"status":{"type":"string","enum":["received","reviewing","resolved","closed"]},"statusLabel":{"type":"string"},"outcome":{"type":["string","null"],"enum":["profile_hidden_from_directory"]},"outcomeLabel":{"type":["string","null"]},"handle":{"type":["string","null"]},"reason":{"type":["string","null"]},"reasonLabel":{"type":["string","null"]},"checkoutIntentId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"message":{"type":"string"},"nextStep":{"type":["string","null"]},"severity":{"type":"string","enum":["high","medium","standard"]},"summary":{"type":"string"},"profileUrl":{"type":["string","null"]},"submittedProfileUrl":{"type":["string","null"]},"reportedDisplayName":{"type":["string","null"]},"details":{"type":["string","null"]},"action":{"type":["string","null"],"enum":["review_only","hide_profile_from_directory"]},"actionLabel":{"type":["string","null"]},"actionedAt":{"type":["string","null"],"format":"date-time"},"statusUrl":{"type":"string"}},"required":["reportId","status","statusLabel","outcome","outcomeLabel","handle","reason","reasonLabel","checkoutIntentId","createdAt","updatedAt","resolvedAt","message","nextStep","severity","summary","profileUrl","submittedProfileUrl","reportedDisplayName","details","action","actionLabel","actionedAt","statusUrl"]}},"required":["report"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Report not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"patchApiContoPayReportsByReportId"}},"/api/sdk/payments/request":{"post":{"tags":["SDK Payments"],"summary":"Request payment authorization","description":"Request authorization for a payment. Returns APPROVED, DENIED, REQUIRES_APPROVAL, PROCESSING, or COMPLETED (an already completed payment).","security":[{"sdkKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}}},"responses":{"200":{"description":"Payment authorization result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequestResponse"}}}},"400":{"description":"Validation error"},"401":{"description":"Authentication required"},"429":{"description":"Rate limit exceeded"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkPaymentsRequest"}},"/api/sdk/payments/{requestId}":{"get":{"tags":["SDK Payments"],"summary":"Get payment request status","description":"Check the status of a payment request.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Payment request ID"},"required":true,"name":"requestId","in":"path"}],"responses":{"200":{"description":"Payment request status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentStatusResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Resource not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkPaymentsByRequestId"}},"/api/sdk/payments/{requestId}/execute":{"post":{"tags":["SDK Payments"],"summary":"Execute approved payment","description":"Execute a previously approved payment request from a managed wallet. The request must have status APPROVED and not be expired. Conto rechecks payment controls before sending. If an approver already executed the payment by approving it in Conto, returns the existing receipt with alreadyExecuted: true and sends nothing.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Payment request ID"},"required":true,"name":"requestId","in":"path"}],"responses":{"200":{"description":"Payment execution result, or the existing receipt when already executed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentExecuteResponse"}}}},"400":{"description":"Payment cannot be executed now (expired, spend limit or balance re-check failed, or not approved)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentExecuteError"}}}},"403":{"description":"Payment is declined and will not execute (POLICY_DENIED_AT_EXECUTION, POLICY_REAPPROVAL_REQUIRED, PAYMENT_DENIED). Do not retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentExecuteError"}}}},"404":{"description":"Payment request not found"},"409":{"description":"Payment state conflict (APPROVAL_PENDING, PAYMENT_PROCESSING, ALREADY_EXECUTED, NEEDS_RECONCILIATION). Check status before any further action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentExecuteError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"description":"Execution is temporarily unavailable, or PAYMENTS_PAUSED has stopped new payment actions. Read the request status before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentExecuteError"}}}}},"operationId":"postApiSdkPaymentsByRequestIdExecute"}},"/api/sdk/agents/me":{"get":{"tags":["SDK Agent"],"summary":"Get agent profile","description":"Get the authenticated agent profile and summary statistics. Requires `agents:read`.","security":[{"sdkKeyAuth":[]}],"responses":{"200":{"description":"Agent profile with spend summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SdkAgentProfile"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope: agents:read required. An organization owner must act.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SdkSelfInspectionScopeError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkAgentsMe"}},"/api/sdk/policies/exceptions":{"post":{"tags":["SDK Policies"],"summary":"Request a scoped policy change","description":"Create a reviewable policy change request for the authenticated agent. Creating a request does not edit a policy. Responses preserve the legacy uppercase `type` and `status` fields and add normalized customer-facing aliases. Requires `policies:exceptions` scope.","security":[{"sdkKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"anyOf":[{"type":"string","enum":["counterparty","spend_limit","time_window","category","custom"]},{"type":"string","enum":["ADD_TO_WHITELIST","INCREASE_SPEND_LIMIT","EXTEND_TIME_WINDOW","ADD_CATEGORY","CUSTOM"]}]},"reason":{"type":"string","minLength":1,"maxLength":1000},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"urgency":{"type":"string","enum":["LOW","NORMAL","HIGH","CRITICAL"]},"details":{"type":"object","properties":{"counterpartyAddress":{"type":"string"},"counterpartyName":{"type":"string"},"policyId":{"type":"string"},"requestedLimit":{"type":"number","exclusiveMinimum":0},"requestedCategory":{"type":"string"},"requestedTimeWindow":{"type":"string"},"amount":{"type":"number","exclusiveMinimum":0}},"additionalProperties":false}},"required":["type","reason"],"additionalProperties":false}}}},"responses":{"200":{"description":"Policy change request created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"exceptionId":{"type":"string"},"type":{"type":"string","enum":["ADD_TO_WHITELIST","INCREASE_SPEND_LIMIT","EXTEND_TIME_WINDOW","ADD_CATEGORY","CUSTOM"]},"normalizedType":{"type":"string","enum":["counterparty","spend_limit","time_window","category","custom"]},"title":{"type":"string"},"reason":{"type":["string","null"]},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"severity":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"]},"details":{"type":["object","null"],"properties":{"counterpartyAddress":{"type":"string"},"counterpartyName":{"type":"string"},"policyId":{"type":"string"},"requestedLimit":{"type":"number","exclusiveMinimum":0},"requestedCategory":{"type":"string"},"requestedTimeWindow":{"type":"string"},"amount":{"type":"number","exclusiveMinimum":0}},"additionalProperties":false},"status":{"type":"string","enum":["PENDING","ACKNOWLEDGED","RESOLVED","DISMISSED"]},"normalizedStatus":{"type":"string","enum":["pending","in_review","resolved","dismissed"]},"statusLabel":{"type":"string","enum":["Pending review","In review","Resolved","Dismissed"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"resolvedAt":{"type":["string","null"]},"reviewUrl":{"type":"string","enum":["/alerts"]},"message":{"type":"string"}},"required":["id","exceptionId","type","normalizedType","title","reason","priority","severity","details","status","normalizedStatus","statusLabel","createdAt","updatedAt","resolvedAt","reviewUrl"],"additionalProperties":false}}}},"400":{"description":"Invalid policy change request"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope: policies:exceptions required"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkPoliciesExceptions"},"get":{"tags":["SDK Policies"],"summary":"List policy change requests","description":"List the authenticated agent’s customer-visible policy change requests with compatibility fields and normalized review states. The same items are returned under `exceptions` and the additive `requests` alias. Requires `policies:exceptions` scope.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["pending","in_review","resolved","dismissed"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Policy change requests","content":{"application/json":{"schema":{"type":"object","properties":{"exceptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"exceptionId":{"type":"string"},"type":{"type":"string","enum":["ADD_TO_WHITELIST","INCREASE_SPEND_LIMIT","EXTEND_TIME_WINDOW","ADD_CATEGORY","CUSTOM"]},"normalizedType":{"type":"string","enum":["counterparty","spend_limit","time_window","category","custom"]},"title":{"type":"string"},"reason":{"type":["string","null"]},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"severity":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"]},"details":{"type":["object","null"],"properties":{"counterpartyAddress":{"type":"string"},"counterpartyName":{"type":"string"},"policyId":{"type":"string"},"requestedLimit":{"type":"number","exclusiveMinimum":0},"requestedCategory":{"type":"string"},"requestedTimeWindow":{"type":"string"},"amount":{"type":"number","exclusiveMinimum":0}},"additionalProperties":false},"status":{"type":"string","enum":["PENDING","ACKNOWLEDGED","RESOLVED","DISMISSED"]},"normalizedStatus":{"type":"string","enum":["pending","in_review","resolved","dismissed"]},"statusLabel":{"type":"string","enum":["Pending review","In review","Resolved","Dismissed"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"resolvedAt":{"type":["string","null"]},"reviewUrl":{"type":"string","enum":["/alerts"]},"message":{"type":"string"}},"required":["id","exceptionId","type","normalizedType","title","reason","priority","severity","details","status","normalizedStatus","statusLabel","createdAt","updatedAt","resolvedAt","reviewUrl"],"additionalProperties":false}},"requests":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"exceptionId":{"type":"string"},"type":{"type":"string","enum":["ADD_TO_WHITELIST","INCREASE_SPEND_LIMIT","EXTEND_TIME_WINDOW","ADD_CATEGORY","CUSTOM"]},"normalizedType":{"type":"string","enum":["counterparty","spend_limit","time_window","category","custom"]},"title":{"type":"string"},"reason":{"type":["string","null"]},"priority":{"type":"string","enum":["low","normal","high","urgent"]},"severity":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"]},"details":{"type":["object","null"],"properties":{"counterpartyAddress":{"type":"string"},"counterpartyName":{"type":"string"},"policyId":{"type":"string"},"requestedLimit":{"type":"number","exclusiveMinimum":0},"requestedCategory":{"type":"string"},"requestedTimeWindow":{"type":"string"},"amount":{"type":"number","exclusiveMinimum":0}},"additionalProperties":false},"status":{"type":"string","enum":["PENDING","ACKNOWLEDGED","RESOLVED","DISMISSED"]},"normalizedStatus":{"type":"string","enum":["pending","in_review","resolved","dismissed"]},"statusLabel":{"type":"string","enum":["Pending review","In review","Resolved","Dismissed"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"resolvedAt":{"type":["string","null"]},"reviewUrl":{"type":"string","enum":["/alerts"]},"message":{"type":"string"}},"required":["id","exceptionId","type","normalizedType","title","reason","priority","severity","details","status","normalizedStatus","statusLabel","createdAt","updatedAt","resolvedAt","reviewUrl"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["exceptions","requests","pagination"],"additionalProperties":false}}}},"400":{"description":"Invalid status filter"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope: policies:exceptions required"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkPoliciesExceptions"}},"/api/sdk/wallets":{"get":{"tags":["SDK Wallets"],"summary":"List agent wallets","description":"List all wallets assigned to the authenticated agent.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["ACTIVE","PAUSED"]},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"List of wallets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SdkWalletList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkWallets"}},"/api/sdk/wallets/{id}":{"get":{"tags":["SDK Wallets"],"summary":"Get wallet details","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Wallet details with limits and recent transactions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SdkWalletDetails"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Resource not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkWalletsById"}},"/api/sdk/transactions":{"get":{"tags":["SDK Transactions"],"summary":"List agent transactions","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["PENDING","CONFIRMING","CONFIRMED","FAILED"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"integer","maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Start date filter"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End date filter"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"List of transactions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SdkTransactionList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkTransactions"}},"/api/sdk/transactions/{id}":{"get":{"tags":["SDK Transactions"],"summary":"Get transaction details","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Transaction details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SdkTransactionDetails"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Resource not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkTransactionsById"}},"/api/sdk/transactions/reconciliation":{"get":{"tags":["SDK Transactions"],"summary":"Reconcile payments (requested vs settled)","description":"Per-payment reconciliation: requested amount, settled amount, settlement hash, status, and a reconciliation state. Pass format=csv for a full server-side export.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Filter by transaction status"},"required":false,"name":"status","in":"query"},{"schema":{"type":"integer","maximum":1000,"default":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Start date filter"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End date filter"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string","enum":["json","csv"],"default":"json"},"required":false,"name":"format","in":"query"}],"responses":{"200":{"description":"Reconciliation rows and a summary (JSON), or a CSV export","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"transactionId":{"type":"string"},"initiatedAt":{"type":"string"},"confirmedAt":{"type":["string","null"]},"status":{"type":"string"},"rail":{"type":"string"},"recipient":{"type":"string"},"requestedAmount":{"type":"number"},"requestedCurrency":{"type":"string"},"settledAmount":{"type":["number","null"]},"settledCurrency":{"type":["string","null"]},"txHash":{"type":["string","null"]},"reconciliationState":{"type":"string","enum":["RECONCILED","DISCREPANCY","PENDING","UNSETTLED"],"description":"How the settled amount compares to the requested amount"},"discrepancy":{"type":["number","null"]}},"required":["transactionId","initiatedAt","confirmedAt","status","rail","recipient","requestedAmount","requestedCurrency","settledAmount","settledCurrency","txHash","reconciliationState","discrepancy"]}},"summary":{"type":"object","properties":{"total":{"type":"integer"},"reconciled":{"type":"integer"},"discrepancy":{"type":"integer"},"pending":{"type":"integer"},"unsettled":{"type":"integer"}},"required":["total","reconciled","discrepancy","pending","unsettled"]},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["items","summary","total","limit","offset"]}},"text/csv":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkTransactionsReconciliation"}},"/api/sdk/policies":{"get":{"tags":["SDK Policies"],"summary":"List agent policies","description":"List active policies that govern the authenticated agent. Organization policies always apply. Assigned policies apply through the agent and, when `walletId` is supplied, that actively linked wallet.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Include policies assigned to this actively linked wallet."},"required":false,"name":"walletId","in":"query"}],"responses":{"200":{"description":"List of policies with effective limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SdkPolicyList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkPolicies"}},"/api/sdk/a2a/request":{"post":{"tags":["SDK A2A Payments"],"summary":"Create an A2A payment request","description":"Request payment from another Conto agent. The requesting agent is asking the target agent to send them funds. Target can be specified by agent ID or wallet address.","security":[{"sdkKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"targetAgentId":{"type":"string","description":"ID of the agent to request payment from"},"targetWalletAddress":{"type":"string","description":"Wallet address of the target agent (alternative to targetAgentId)"},"amount":{"type":"number","exclusiveMinimum":0,"description":"Payment amount"},"currency":{"type":"string","default":"USDC","description":"Currency (default: USDC)"},"purpose":{"type":"string","description":"Reason for the payment request"},"invoiceId":{"type":"string","description":"Optional invoice identifier"},"invoiceData":{"type":"object","additionalProperties":{},"description":"Customer-supplied structured invoice data"},"dueDate":{"type":"string","format":"date-time","description":"Payment due date (ISO 8601)"},"expiresAt":{"type":"string","format":"date-time","description":"Request expiration time (ISO 8601)"}},"required":["amount"]}}}},"responses":{"200":{"description":"Payment request created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"paymentRequest":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["review_required"]},"direction":{"type":"string","enum":["outgoing"]},"requestingAgent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"requestedFromAgent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"amount":{"type":"number"},"currency":{"type":"string"},"purpose":{"type":["string","null"]},"invoiceId":{"type":["string","null"]},"invoiceData":{"type":["object","null"],"additionalProperties":{}},"dueDate":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"links":{"type":"object","properties":{"details":{"type":"string"}},"required":["details"],"additionalProperties":false}},"required":["id","status","direction","requestingAgent","requestedFromAgent","amount","currency","purpose","invoiceId","invoiceData","dueDate","createdAt","expiresAt","links"],"additionalProperties":false,"description":"Payment request details"},"message":{"type":"string"}},"required":["success","paymentRequest","message"]}}}},"400":{"description":"Validation error (invalid amount, missing target)"},"401":{"description":"Authentication required"},"404":{"description":"Target agent not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkA2aRequest"}},"/api/sdk/a2a/requests":{"get":{"tags":["SDK A2A Payments"],"summary":"List A2A payment requests","description":"List payment requests for the authenticated agent. Filter by direction (incoming/outgoing) and status.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["incoming","outgoing","all"],"default":"all","description":"Filter by request direction"},"required":false,"name":"direction","in":"query"},{"schema":{"type":"string","enum":["review_required","approved","declined","processing","completed","failed","expired"],"description":"Filter by stable customer request status"},"required":false,"name":"status","in":"query"},{"schema":{"type":"integer","maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"List of A2A payment requests","content":{"application/json":{"schema":{"type":"object","properties":{"requests":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["review_required","approved","declined","processing","completed","failed","expired"]},"direction":{"type":"string","enum":["incoming","outgoing"]},"amount":{"type":"number"},"currency":{"type":"string"},"purpose":{"type":["string","null"]},"invoiceId":{"type":["string","null"]},"invoiceData":{"type":["object","null"],"additionalProperties":{}},"dueDate":{"type":["string","null"],"format":"date-time"},"requestingAgent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"requestedFromAgent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"transaction":{"type":["object","null"],"properties":{"id":{"type":"string"},"txHash":{"type":["string","null"]},"status":{"type":"string","enum":["processing","completed","failed"]},"confirmedAt":{"type":["string","null"],"format":"date-time"},"blockNumber":{"type":["integer","null"]},"chain":{"type":"object","properties":{"type":{"type":"string","enum":["evm","solana"]},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"explorerUrl":{"type":["string","null"],"format":"uri"}},"required":["id","txHash","status","confirmedAt","blockNumber","chain","explorerUrl"],"additionalProperties":false},"links":{"type":"object","properties":{"details":{"type":"string"},"approve":{"type":["string","null"]},"reject":{"type":["string","null"]},"execute":{"type":["string","null"]}},"required":["details","approve","reject","execute"],"additionalProperties":false},"approvedAt":{"type":["string","null"],"format":"date-time"},"rejectedAt":{"type":["string","null"],"format":"date-time"},"rejectionReason":{"type":["string","null"]},"paidAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","status","direction","amount","currency","purpose","invoiceId","invoiceData","dueDate","requestingAgent","requestedFromAgent","transaction","links","approvedAt","rejectedAt","rejectionReason","paidAt","expiresAt","createdAt","updatedAt"],"additionalProperties":false}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["requests","total","limit","offset"]}}}},"400":{"description":"Invalid direction, status, or pagination query"},"401":{"description":"Authentication required"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkA2aRequests"}},"/api/sdk/a2a/requests/{id}":{"get":{"tags":["SDK A2A Payments"],"summary":"Get A2A payment request details","description":"Get details of a specific A2A payment request, including direction and status.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Payment request ID"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Payment request details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["review_required","approved","declined","processing","completed","failed","expired"]},"direction":{"type":"string","enum":["incoming","outgoing"]},"amount":{"type":"number"},"currency":{"type":"string"},"purpose":{"type":["string","null"]},"invoiceId":{"type":["string","null"]},"invoiceData":{"type":["object","null"],"additionalProperties":{}},"dueDate":{"type":["string","null"],"format":"date-time"},"requestingAgent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"requestedFromAgent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"transaction":{"type":["object","null"],"properties":{"id":{"type":"string"},"txHash":{"type":["string","null"]},"status":{"type":"string","enum":["processing","completed","failed"]},"confirmedAt":{"type":["string","null"],"format":"date-time"},"blockNumber":{"type":["integer","null"]},"chain":{"type":"object","properties":{"type":{"type":"string","enum":["evm","solana"]},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"explorerUrl":{"type":["string","null"],"format":"uri"}},"required":["id","txHash","status","confirmedAt","blockNumber","chain","explorerUrl"],"additionalProperties":false},"links":{"type":"object","properties":{"details":{"type":"string"},"approve":{"type":["string","null"]},"reject":{"type":["string","null"]},"execute":{"type":["string","null"]}},"required":["details","approve","reject","execute"],"additionalProperties":false},"approvedAt":{"type":["string","null"],"format":"date-time"},"rejectedAt":{"type":["string","null"],"format":"date-time"},"rejectionReason":{"type":["string","null"]},"paidAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","status","direction","amount","currency","purpose","invoiceId","invoiceData","dueDate","requestingAgent","requestedFromAgent","transaction","links","approvedAt","rejectedAt","rejectionReason","paidAt","expiresAt","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Not authorized to view this request"},"404":{"description":"Payment request not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkA2aRequestsById"}},"/api/sdk/a2a/requests/{id}/approve":{"post":{"tags":["SDK A2A Payments"],"summary":"Approve an A2A payment request","description":"Approve an incoming request as the paying agent and receive the URL used to execute it. The agent can approve only when the payer's policies allow the payment outright. If a policy requires approval, the agent cannot clear it: the request stays pending, the response is 403 with `code: \"HUMAN_APPROVAL_REQUIRED\"`, and an authorized member of the paying organization must approve it while signed in to Conto (`POST /api/a2a/requests/{id}/approve`, session auth, `transactions:approve`). Policy denials cannot be overridden. Requires the `payments:approve` scope.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Payment request approved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"requestId":{"type":"string"},"status":{"type":"string","enum":["approved"]},"message":{"type":"string"},"links":{"type":"object","properties":{"details":{"type":"string"},"execute":{"type":"string"}},"required":["details","execute"],"additionalProperties":false}},"required":["success","requestId","status","message","links"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Only the paying agent can approve this request, or the payer policy requires human approval (`HUMAN_APPROVAL_REQUIRED`). In the second case the request stays pending.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"code":{"type":"string","enum":["HUMAN_APPROVAL_REQUIRED"]},"requestId":{"type":"string"},"status":{"type":"string","enum":["pending_human_approval"]},"links":{"type":"object","properties":{"details":{"type":"string"}},"required":["details"],"additionalProperties":false}},"required":["success","error","code","requestId","status","links"],"additionalProperties":false}}}},"404":{"description":"Payment request not found"},"409":{"description":"Payment request is no longer pending"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkA2aRequestsByIdApprove"}},"/api/sdk/a2a/requests/{id}/reject":{"post":{"tags":["SDK A2A Payments"],"summary":"Reject a pending A2A payment request","description":"Reject an incoming A2A payment request as the paying agent. An optional reason can be stored with the request.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Payment request ID"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Optional rejection reason"}}}}}},"responses":{"200":{"description":"Payment request rejected","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"paymentRequest":{}},"required":["success","message"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Only the paying agent can reject this request"},"404":{"description":"Payment request not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkA2aRequestsByIdReject"}},"/api/sdk/a2a/requests/{id}/execute":{"post":{"tags":["SDK A2A Payments"],"summary":"Execute an approved A2A payment request","description":"Execute a previously approved A2A payment request. The request must be in an approved state. Policy is evaluated again at execution. If it requires approval and no authorized human in the paying organization has approved the request, execution is refused with `code: \"HUMAN_APPROVAL_REQUIRED\"`. An approval recorded by the paying agent never satisfies a policy that requires human approval.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Payment request ID"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Payment execution initiated","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"requestId":{"type":"string"},"transaction":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["processing","completed"]}},"required":["id","status"],"additionalProperties":false},"links":{"type":"object","properties":{"details":{"type":"string"},"transaction":{"type":"string"}},"required":["details","transaction"],"additionalProperties":false},"message":{"type":"string"}},"required":["success","requestId","transaction","links","message"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Not authorized to execute this request, or the payer policy requires human approval (`HUMAN_APPROVAL_REQUIRED`)"},"404":{"description":"Payment request not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkA2aRequestsByIdExecute"}},"/api/sdk/a2a/resolve":{"get":{"tags":["SDK A2A Payments"],"summary":"Resolve a wallet address to a Conto agent","description":"Check if a wallet address belongs to a registered Conto agent. Useful for verifying recipients before sending A2A payment requests.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Wallet address to resolve"},"required":true,"name":"address","in":"query"}],"responses":{"200":{"description":"Resolution result","content":{"application/json":{"schema":{"type":"object","properties":{"isAgent":{"type":"boolean"},"address":{"type":"string"},"agent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id"],"description":"Agent info if resolved. The name is included only for agents in your organization."},"organization":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"],"description":"Included only when the agent is in your organization."},"message":{"type":"string"}},"required":["isAgent","address"]}}}},"400":{"description":"Address query parameter required"},"401":{"description":"Authentication required"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkA2aResolve"}},"/api/sdk/a2a/stats":{"get":{"tags":["SDK A2A Payments"],"summary":"Get A2A payment statistics","description":"Get aggregate A2A payment statistics for the authenticated agent.","security":[{"sdkKeyAuth":[]}],"responses":{"200":{"description":"A2A payment statistics","content":{"application/json":{"schema":{"type":"object","properties":{"sent":{"type":"object","properties":{"total":{"type":"number"},"count":{"type":"integer"}},"required":["total","count"]},"received":{"type":"object","properties":{"total":{"type":"number"},"count":{"type":"integer"}},"required":["total","count"]},"pendingRequests":{"type":"object","properties":{"incoming":{"type":"integer"},"outgoing":{"type":"integer"}},"required":["incoming","outgoing"]}},"required":["sent","received","pendingRequests"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkA2aStats"}},"/api/sdk/alerts":{"get":{"tags":["SDK Alerts & Analytics"],"summary":"List agent alerts","description":"List alerts for the authenticated agent. Requires `alerts:read` scope. Filter by status and severity.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["open","in_review","resolved","dismissed"],"description":"Filter by alert status"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","enum":["low","medium","high"],"description":"Filter by severity"},"required":false,"name":"severity","in":"query"},{"schema":{"type":"integer","maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"List of alerts with pagination","content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string"},"activeCount":{"type":"number"},"alerts":{"type":"array","items":{"$ref":"#/components/schemas/Alert"}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["agentId","activeCount","alerts","pagination"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope: alerts:read required"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkAlerts"}},"/api/sdk/alerts/{id}":{"get":{"tags":["SDK Alerts & Analytics"],"summary":"Get alert details","description":"Get details of a specific alert. Requires `alerts:read` scope.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Alert ID"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Alert details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Alert"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope: alerts:read required"},"404":{"description":"Alert not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkAlertsById"},"post":{"tags":["SDK Alerts & Analytics"],"summary":"Acknowledge or resolve an alert","description":"Update an alert status by acknowledging or resolving it. Requires `alerts:write` scope.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Alert ID"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["acknowledge","resolve"],"description":"Action to perform"}},"required":["action"],"additionalProperties":false}}}},"responses":{"200":{"description":"Alert updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Alert"}}}},"400":{"description":"Invalid action or alert status"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope: alerts:write required"},"404":{"description":"Alert not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkAlertsById"}},"/api/sdk/budget-request":{"post":{"tags":["SDK Alerts & Analytics"],"summary":"Request a spending budget","description":"Submit a budget request for human approval. Only one active budget request per agent is allowed at a time.","security":[{"sdkKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0,"description":"Requested budget amount"},"purpose":{"type":"string","minLength":1,"maxLength":1000,"description":"Purpose shown to the reviewer"},"category":{"type":"string","maxLength":50,"description":"Optional spend category"},"metadata":{"description":"Additional context metadata"}},"required":["amount","purpose"]}}}},"responses":{"201":{"description":"Budget request created","content":{"application/json":{"schema":{"type":"object","properties":{"budgetRequestId":{"type":"string"},"status":{"type":"string","enum":["PENDING"]},"requestedAmount":{"type":"number"},"purpose":{"type":"string"},"category":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["budgetRequestId","status","requestedAmount","purpose","category","createdAt"]}}}},"400":{"description":"Validation error"},"401":{"description":"Authentication required"},"409":{"description":"An active budget request already exists"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkBudgetRequest"},"get":{"tags":["SDK Alerts & Analytics"],"summary":"List budget requests","description":"List budget requests for the authenticated agent and include the currently active approved budget when one exists.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Specific budget request ID"},"required":false,"name":"id","in":"query"},{"schema":{"type":"string","enum":["PENDING","APPROVED","REJECTED","EXPIRED","EXHAUSTED"],"description":"Filter by budget request status"},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Budget request list","content":{"application/json":{"schema":{"type":"object","properties":{"budgetRequests":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"requestedAmount":{"type":"number"},"approvedAmount":{"type":["number","null"]},"currentSpend":{"type":"number"},"remainingBudget":{"type":["number","null"]},"currency":{"type":"string"},"purpose":{"type":"string"},"category":{"type":["string","null"]},"rejectionReason":{"type":["string","null"]},"expiresAt":{"type":["string","null"]},"createdAt":{"type":"string"},"approvedAt":{"type":["string","null"]}},"required":["id","status","requestedAmount","approvedAmount","currentSpend","remainingBudget","currency","purpose","category","rejectionReason","expiresAt","createdAt","approvedAt"]}},"activeBudget":{"type":["object","null"],"properties":{"id":{"type":"string"},"approvedAmount":{"type":"number"},"currentSpend":{"type":"number"},"remainingBudget":{"type":"number"},"expiresAt":{"type":["string","null"]}},"required":["id","approvedAmount","currentSpend","remainingBudget","expiresAt"]}},"required":["budgetRequests","activeBudget"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkBudgetRequest"}},"/api/sdk/analytics":{"get":{"tags":["SDK Alerts & Analytics"],"summary":"Get spending analytics","description":"Get spending analytics for the authenticated agent including volume trends, category breakdowns, and top merchants. Requires `analytics:read` scope.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["day","week","month","year"],"default":"month","description":"Time period for analytics"},"required":false,"name":"period","in":"query"}],"responses":{"200":{"description":"Spending analytics","content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string"},"period":{"type":"string"},"dateRange":{"type":"object","properties":{"start":{"type":"string"},"end":{"type":"string"}},"required":["start","end"]},"summary":{"type":"object","properties":{"totalVolume":{"type":"number"},"transactionCount":{"type":"number"},"avgTransactionSize":{"type":"number"},"volumeChange":{"type":"number"},"previousVolume":{"type":"number"}},"required":["totalVolume","transactionCount","avgTransactionSize","volumeChange","previousVolume"]},"categoryBreakdown":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"count":{"type":"number"},"volume":{"type":"number"},"percentage":{"type":"number"}},"required":["category","count","volume","percentage"]}},"typeBreakdown":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"count":{"type":"number"},"volume":{"type":"number"},"percentage":{"type":"number"}},"required":["type","count","volume","percentage"]}},"topMerchants":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"count":{"type":"number"},"volume":{"type":"number"}},"required":["name","count","volume"]}},"volumeTrend":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"volume":{"type":"number"}},"required":["date","volume"]}}},"required":["agentId","period","dateRange","summary","categoryBreakdown","typeBreakdown","topMerchants","volumeTrend"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope: analytics:read required"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkAnalytics"}},"/api/sdk/audit-logs":{"get":{"tags":["SDK Alerts & Analytics"],"summary":"List audit logs","description":"Get audit logs of actions performed by or affecting this agent. Requires `audit:read` scope.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["CONNECTED_CARD_CONNECTED","CONNECTED_CARD_AGENT_LINKED","CONNECTED_CARD_AGENT_UNLINKED","CONNECTED_CARD_AGENT_RELINKED","CONNECTED_CARD_AUTHORIZATION_CREATED","CONNECTED_CARD_VERIFICATION_RECORDED","CONNECTED_CARD_DRAW_APPROVED","CONNECTED_CARD_DRAW_REVIEW_REQUIRED","CONNECTED_CARD_DRAW_DENIED","CONNECTED_CARD_DRAW_REVIEWED","CONNECTED_CARD_CREDENTIAL_ISSUED","CONNECTED_CARD_CREDENTIAL_DELIVERY_ACKNOWLEDGED","CONNECTED_CARD_CHECKOUT_STATE_RECORDED","CONNECTED_CARD_CHECKOUT_SESSION_RECOVERED","CONNECTED_CARD_CHECKOUT_REPORTED","CONNECTED_CARD_MANDATE_REVOKED","CONNECTED_CARD_AGENT_LIMITS_UPDATED","CONNECTED_CARD_LIMITS_UPDATED","CONNECTED_CARD_PILOT_HOURS_CORRECTED","CONNECTED_CARD_MINT_CLAIMED","CONNECTED_CARD_MINT_RECONCILIATION_REQUIRED","CONNECTED_CARD_MINT_RESOLVED_EXECUTED","CONNECTED_CARD_MINT_RESOLVED_NOT_EXECUTED","CONNECTED_CARD_ISSUER_AUTHORIZATION_REPORTED","CHECKOUT_CHECKPOINT_APPROVED","CHECKOUT_CHECKPOINT_DENIED","CHECKOUT_CHECKPOINT_CONFIRMED","CHECKOUT_CHECKPOINT_STOPPED","CHECKOUT_OUTCOME_REPORTED","CHECKOUT_CHECKPOINT_CANCELLED","CHECKOUT_CHECKPOINT_EXPIRED","CHECKOUT_OUTCOME_RESOLVED","CHECKOUT_CHECKPOINT_APPROVAL_REQUESTED","CHECKOUT_CHECKPOINT_OWNER_APPROVED","CHECKOUT_CHECKPOINT_OWNER_DENIED","CHECKOUT_CHECKPOINT_APPROVAL_EXPIRED","CREATE","UPDATE","DELETE","VIEW","EXPORT","LOGIN","LOGOUT","APPROVE","REJECT","SUSPEND","ACTIVATE","FUND","WITHDRAW","TRANSFER","POLICY_VIOLATION","ALERT_CREATED","ALERT_RESOLVED","SETTINGS_CHANGED","PERMISSION_GRANTED","PERMISSION_REVOKED","AUDIT_LOG_EXPORTED","AUDIT_CHAIN_BASELINED","POLICY_EVALUATE","POLICY_CREATED","POLICY_UPDATED","POLICY_DELETED","POLICY_ASSIGNED","POLICY_UNASSIGNED","ASSIGN_POLICY","REMOVE_POLICY","LINK_WALLET","UNLINK_WALLET","UPDATE_WALLET_LINK","BULK_IMPORT","TRANSACTION_INIT","TRANSACTION_CONFIRM","TRANSACTION_FAIL","API_KEY_CREATE","API_KEY_REVOKE","PERMISSION_GRANT","PERMISSION_REVOKE","PAYMENT_REQUEST","PAYMENT_APPROVED","PAYMENT_EXECUTING","PAYMENT_STATUS_CHANGED","PAYMENT_EXECUTED","PAYMENT_CONFIRMED","PAYMENT_DENIED","PAYMENT_FAILED","PAYMENT_CANCELLED","PAYMENT_EXPIRED","EXTERNAL_PAYMENT_APPROVAL","EXTERNAL_PAYMENT_CONFIRMED","EXTERNAL_PAYMENT_DENIED","WALLET_FROZEN","WALLET_UNFROZEN","AGENT_FROZEN","AGENT_UNFROZEN","SPEND_LIMIT_CHANGED","TRUST_SCORE_UPDATE","TRANSACTION_RETRY","FUND_WALLET","CONFIRM_WALLET_SETUP","REFRESH_BALANCE","APPROVAL_WORKFLOW_TRIGGERED","APPROVAL_REQUESTED","APPROVAL_STATUS_CHANGED","APPROVAL_EXPIRED","APPROVAL_CANCELLED","APPROVAL_WORKFLOW_CREATED","APPROVAL_WORKFLOW_UPDATED","APPROVAL_WORKFLOW_DELETED","INVITE_MEMBER","ACCEPT_MEMBER_INVITE","RESEND_MEMBER_INVITE","REVOKE_MEMBER_INVITE","UPDATE_ROLE","REMOVE_MEMBER","COUNTERPARTY_CREATED","MFA_VERIFY","PLAN_CHANGED","INVOICE_PAID","BULK_ASSIGN","BULK_PAUSE","BULK_UPDATE_LIMITS"],"description":"Filter by customer-visible action type"},"required":false,"name":"action","in":"query"},{"schema":{"type":"string","enum":["agent","wallet","transaction","policy","policy_rule","policy_assignment","agent_policy","agent_wallet","user","member","organization_member","organization","alert","api_key","api-key","sdk_key","counterparty","relationship","settings","session","approval_request","approval_workflow","payment_request","budget_request","organization_invitation","contract_registry","billing","integration","x402_transaction","mpp_transaction","AUDIT_LOG"],"description":"Filter by customer-visible resource type"},"required":false,"name":"resource","in":"query"},{"schema":{"type":"integer","maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Start date filter (ISO 8601)"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End date filter (ISO 8601)"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"List of audit log entries","content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string"},"logs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable audit entry reference"},"action":{"type":"string"},"resource":{"type":"string"},"actorType":{"type":"string","enum":["USER","AGENT","SYSTEM","API","API_KEY"]},"createdAt":{"type":"string","format":"date-time"},"resourceReference":{"type":["object","null"],"properties":{"id":{"type":["string","null"]},"label":{"type":"string"},"href":{"type":"string"}},"required":["id","label","href"],"additionalProperties":false},"changes":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"label":{"type":"string"},"before":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]},"after":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"required":["field","label","before","after"],"additionalProperties":false}},"transaction":{"type":["object","null"],"properties":{"id":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"status":{"type":"string","enum":["Completed","Failed","Declined","Processing"]}},"required":["id","amount","currency","status"],"additionalProperties":false}},"required":["id","action","resource","actorType","createdAt","resourceReference","changes","transaction"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["agentId","logs","pagination"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope: audit:read required"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkAuditLogs"}},"/api/sdk/service-spend/summary":{"get":{"tags":["SDK Alerts & Analytics"],"summary":"Get machine spend summary","description":"Return a unified x402 and MPP summary for the authenticated agent, including total spend, call volume, and recent machine-spend alerts.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["24h","7d","30d","all"],"default":"30d","description":"Time window for the summary"},"required":false,"name":"period","in":"query"},{"schema":{"type":"string","enum":["all","x402","mpp"],"default":"all","description":"Protocol filter"},"required":false,"name":"protocol","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":25,"default":10},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Machine spend summary","content":{"application/json":{"schema":{"type":"object","properties":{"filters":{"type":"object","properties":{"period":{"type":"string","enum":["24h","7d","30d","all"]},"protocol":{"type":"string","enum":["all","x402","mpp"]},"agentId":{"type":"string"},"startDate":{"type":["string","null"]}},"required":["period","protocol","agentId","startDate"]},"summary":{"type":"object","properties":{"totalSpend":{"type":"number"},"totalCalls":{"type":"number"},"activeServices":{"type":"number"},"activeAgents":{"type":"number"},"activeAlerts":{"type":"number"},"micropaymentTransactions":{"type":"number"},"x402Spend":{"type":"number"},"x402Calls":{"type":"number"},"mppSpend":{"type":"number"},"mppCalls":{"type":"number"}},"required":["totalSpend","totalCalls","activeServices","activeAgents","activeAlerts","micropaymentTransactions","x402Spend","x402Calls","mppSpend","mppCalls"]},"recentAlerts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"protocol":{"type":"string","enum":["x402","mpp"]},"alertType":{"type":"string"},"severity":{"type":"string"},"status":{"type":"string"},"title":{"type":"string"},"message":{"type":"string"},"createdAt":{"type":"string"},"organizationName":{"type":"string"},"agentName":{"type":["string","null"]}},"required":["id","protocol","alertType","severity","status","title","message","createdAt","organizationName","agentName"]}}},"required":["filters","summary","recentAlerts"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope: analytics:read required"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkServiceSpendSummary"}},"/api/sdk/service-spend/services":{"get":{"tags":["SDK Alerts & Analytics"],"summary":"List machine spend services and endpoints","description":"Return the top machine-payable services and endpoints for the authenticated agent across x402 and MPP flows.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["24h","7d","30d","all"],"default":"30d","description":"Time window for the breakdown"},"required":false,"name":"period","in":"query"},{"schema":{"type":"string","enum":["all","x402","mpp"],"default":"all","description":"Protocol filter"},"required":false,"name":"protocol","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Machine spend services and endpoints","content":{"application/json":{"schema":{"type":"object","properties":{"filters":{"type":"object","properties":{"period":{"type":"string","enum":["24h","7d","30d","all"]},"protocol":{"type":"string","enum":["all","x402","mpp"]},"agentId":{"type":"string"},"startDate":{"type":["string","null"]}},"required":["period","protocol","agentId","startDate"]},"services":{"type":"array","items":{"type":"object","properties":{"protocol":{"type":"string","enum":["x402","mpp"]},"serviceDomain":{"type":"string"},"totalSpend":{"type":"number"},"totalCalls":{"type":"number"},"avgPricePerCall":{"type":"number"},"minPricePerCall":{"type":"number"},"maxPricePerCall":{"type":"number"},"firstActivityAt":{"type":["string","null"]},"lastActivityAt":{"type":["string","null"]}},"required":["protocol","serviceDomain","totalSpend","totalCalls","avgPricePerCall","minPricePerCall","maxPricePerCall","firstActivityAt","lastActivityAt"]}},"endpoints":{"type":"array","items":{"type":"object","properties":{"protocol":{"type":"string","enum":["x402","mpp"]},"resourceUrl":{"type":"string"},"serviceDomain":{"type":"string"},"totalSpend":{"type":"number"},"totalCalls":{"type":"number"},"avgPricePerCall":{"type":"number"},"lastActivityAt":{"type":["string","null"]}},"required":["protocol","resourceUrl","serviceDomain","totalSpend","totalCalls","avgPricePerCall","lastActivityAt"]}}},"required":["filters","services","endpoints"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope: analytics:read required"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkServiceSpendServices"}},"/api/sdk/approval-requests":{"get":{"tags":["SDK Approvals"],"summary":"List pending approval requests","description":"List approval requests for the agent, including stable customer statuses, counterparty identifiers, and links to inspect or act on each request.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["payment","a2a_incoming","a2a_outgoing"],"description":"Filter by request type"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","enum":["PENDING","APPROVED","DENIED","EXPIRED"],"description":"Filter by status"},"required":false,"name":"status","in":"query"},{"schema":{"type":"integer","maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"List of approval requests","content":{"application/json":{"schema":{"type":"object","properties":{"pendingCount":{"type":"number"},"requests":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"paymentRequestId":{"type":"string"},"approvalRequestId":{"type":"string"},"type":{"type":"string","enum":["payment","a2a_incoming","a2a_outgoing"]},"status":{"type":"string","enum":["PENDING","APPROVED","DENIED","EXPIRED"]},"amount":{"type":"number"},"currency":{"type":"string"},"recipient":{"type":"string"},"requester":{"type":"string"},"purpose":{"type":["string","null"]},"createdAt":{"type":"string"},"expiresAt":{"type":["string","null"]},"approval":{"type":"object","properties":{"status":{"type":"string","enum":["PENDING","APPROVED","DENIED","EXPIRED"]},"workflowName":{"type":"string"},"approvalsReceived":{"type":"number"},"requiredApprovals":{"type":"number"}},"required":["status","workflowName","approvalsReceived","requiredApprovals"],"additionalProperties":false},"counterparty":{"type":"object","properties":{"agentId":{"type":["string","null"]},"name":{"type":["string","null"]},"address":{"type":["string","null"]}},"required":["agentId","name","address"],"additionalProperties":false},"links":{"type":"object","properties":{"details":{"type":"string"},"approve":{"type":["string","null"]},"reject":{"type":["string","null"]}},"required":["details","approve","reject"],"additionalProperties":false}},"required":["id","type","status","amount","currency","createdAt","counterparty","links"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"],"additionalProperties":false}},"required":["pendingCount","requests","pagination"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkApprovalRequests"}},"/api/sdk/approval-requests/{id}/decide":{"post":{"tags":["SDK Approvals"],"summary":"Approve or deny a payment review from an agent skill","description":"Submit the assigned human owner's decision for a payment approval request. A new decision requires the matching one-time human action token from an independently delivered approval notification; an idempotent retry of an already-recorded decision does not. The assigned owner must be active and permitted to approve transactions. Configured approvers, review order, expiry, and duplicate-decision rules apply. A final approval automatically executes managed wallets; external wallets receive an explicit execute-and-confirm handoff. The execution outcome uses the same fixed codes and reasons as the execute endpoint.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Approval request ID"},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["APPROVED","REJECTED"]},"comment":{"type":"string","maxLength":500},"actionToken":{"type":"string","minLength":32,"maxLength":512,"description":"Required for a new decision; omit only when retrying the same recorded decision"}},"required":["decision"]}}}},"responses":{"200":{"description":"Decision recorded","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"approvalRequestId":{"type":"string"},"finalStatus":{"type":"string","enum":["PENDING","APPROVED","REJECTED"]},"message":{"type":"string"},"idempotent":{"type":"boolean"},"payment":{"type":"object","properties":{"paymentRequestId":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"recipientAddress":{"type":"string"},"recipientName":{"type":["string","null"]},"purpose":{"type":["string","null"]},"wallet":{"type":["object","null"],"properties":{"address":{"type":"string"},"chainType":{"type":"string"},"chainId":{"type":"string"},"custodyType":{"type":"string"}},"required":["address","chainType","chainId","custodyType"]}},"required":["paymentRequestId","amount","currency","recipientAddress","recipientName","purpose","wallet"]},"execution":{"type":"object","properties":{"success":{"type":"boolean"},"transactionId":{"type":"string"},"txHash":{"type":"string","description":"Onchain transaction hash. Omitted for test settlement."},"explorerUrl":{"type":"string"},"settlementMode":{"type":"string","enum":["test","live"],"description":"Present on success when the settlement mode is known"},"error":{"type":"string","description":"Fixed failure message. Uses the same codes and wording as the execute endpoint."},"code":{"type":"string","description":"Fixed failure code, for example POLICY_DENIED_AT_EXECUTION, NEEDS_RECONCILIATION, MANUAL_EXECUTION_REQUIRED, or EXECUTION_FAILED"},"reasons":{"type":"array","items":{"type":"string"},"description":"Fixed reasons, only for failures the agent can act on"}},"required":["success"],"description":"Outcome of the automatic execution a final approval starts, or of the payment transaction already recorded. Never includes internal error text or policy details."},"receiptUrl":{"type":"string"},"nextAction":{"type":"object","properties":{"type":{"type":"string","enum":["EXECUTE_EXTERNALLY"]},"paymentRequestId":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"recipientAddress":{"type":"string"},"walletAddress":{"type":"string"},"chainType":{"type":"string"},"chainId":{"type":"string"},"confirmUrl":{"type":"string"},"approvalTokenRequired":{"type":"boolean","enum":[false]}},"required":["type","paymentRequestId","amount","currency","recipientAddress","confirmUrl","approvalTokenRequired"]}},"required":["success","approvalRequestId","finalStatus","message","payment"]}}}},"400":{"description":"Decision rejected by the workflow"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope, owner assignment, or owner permission"},"404":{"description":"Approval request not found for this agent"},"409":{"description":"The owner already submitted a different decision"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkApprovalRequestsByIdDecide"}},"/api/sdk/spending-limits":{"get":{"tags":["SDK Alerts & Analytics"],"summary":"Get spending limits and usage","description":"Get per-wallet spending limits and current usage for the authenticated agent. Requires `wallets:read` scope.","security":[{"sdkKeyAuth":[]}],"responses":{"200":{"description":"Spending limits and current usage per wallet","content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string"},"agentName":{"type":"string"},"wallets":{"type":"array","items":{"type":"object","properties":{"walletId":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"},"balance":{"type":"number"},"limits":{"type":"object","properties":{"perTransaction":{"type":["number","null"]},"daily":{"type":["number","null"]},"weekly":{"type":["number","null"]},"monthly":{"type":["number","null"]}},"required":["perTransaction","daily","weekly","monthly"]},"spent":{"type":"object","properties":{"today":{"type":"number"},"thisWeek":{"type":"number"},"thisMonth":{"type":"number"}},"required":["today","thisWeek","thisMonth"]},"remaining":{"type":"object","properties":{"daily":{"type":["number","null"]},"weekly":{"type":["number","null"]},"monthly":{"type":["number","null"]}},"required":["daily","weekly","monthly"]}},"required":["walletId","name","address","balance","limits","spent","remaining"]}}},"required":["agentId","agentName","wallets"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope: wallets:read required"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkSpendingLimits"}},"/api/sdk/rate-limits":{"get":{"tags":["SDK Alerts & Analytics"],"summary":"Get SDK request limits","description":"Get the published SDK request ceilings and customer usage counts for the authenticated agent.","security":[{"sdkKeyAuth":[]}],"responses":{"200":{"description":"Published SDK request ceilings and usage counts","content":{"application/json":{"schema":{"type":"object","properties":{"limits":{"type":"object","properties":{"payments":{"type":"object","properties":{"requests":{"type":"integer"},"windowSeconds":{"type":"integer"}},"required":["requests","windowSeconds"]},"reads":{"type":"object","properties":{"requests":{"type":"integer"},"windowSeconds":{"type":"integer"}},"required":["requests","windowSeconds"]}},"required":["payments","reads"]},"usage":{"type":"object","properties":{"transactionsToday":{"type":"number"},"transactionsThisMonth":{"type":"number"},"paymentsAwaitingReview":{"type":"number"}},"required":["transactionsToday","transactionsThisMonth","paymentsAwaitingReview"]}},"required":["limits","usage"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkRateLimits"}},"/api/sdk/counterparties":{"get":{"tags":["SDK Counterparties"],"summary":"List agent counterparties","description":"List counterparties the agent has interacted with, including trust levels and transaction history. Requires `counterparties:read` scope.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["HIGH","MEDIUM","LOW","UNKNOWN"],"description":"Filter by trust level"},"required":false,"name":"trustLevel","in":"query"},{"schema":{"type":"integer","maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"List of counterparties with trust data","content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string"},"counterparties":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"address":{"type":"string"},"category":{"type":["string","null"]},"approvalStatus":{"type":"string","enum":["PENDING","APPROVED","BLOCKED"]},"lifecycleStatus":{"type":"string","enum":["DISCOVERED","PENDING_REVIEW","APPROVED","TRUSTED","MONITORED","QUARANTINED","BLOCKED"]},"verified":{"type":"boolean"},"riskLevel":{"type":"string"},"trustScore":{"type":"number"},"relationship":{"type":"object","properties":{"trustScore":{"type":"number"},"trustLevel":{"type":"string"},"transactionCount":{"type":"number"},"totalVolume":{"type":"number"},"firstTransactionAt":{"type":["string","null"]},"lastTransactionAt":{"type":["string","null"]}},"required":["trustScore","trustLevel","transactionCount","totalVolume","firstTransactionAt","lastTransactionAt"]}},"required":["id","name","address","category","approvalStatus","lifecycleStatus","verified","riskLevel","trustScore","relationship"]}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["agentId","counterparties","pagination"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope: counterparties:read required"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkCounterparties"},"post":{"tags":["SDK Counterparties"],"summary":"Create a counterparty for this agent","description":"Register a new counterparty (payment recipient). Requires `counterparties:write` scope.","security":[{"sdkKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Counterparty name"},"address":{"type":"string","minLength":1,"maxLength":200,"description":"Wallet address"},"type":{"type":"string","maxLength":50,"default":"VENDOR","description":"Counterparty type (default: VENDOR)"},"category":{"type":"string","maxLength":100,"description":"Category"},"description":{"type":"string","maxLength":500,"description":"Description"},"approvalStatus":{"type":"string","enum":["PENDING","APPROVED","BLOCKED"],"default":"PENDING","description":"Approval status for counterparty policies"},"lifecycleStatus":{"type":"string","enum":["DISCOVERED","PENDING_REVIEW","APPROVED","TRUSTED","MONITORED","QUARANTINED","BLOCKED"],"description":"Canonical counterparty lifecycle status"}},"required":["name","address"]}}}},"responses":{"200":{"description":"Counterparty created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"},"type":{"type":"string"},"category":{"type":["string","null"]},"approvalStatus":{"type":"string","enum":["PENDING","APPROVED","BLOCKED"]},"lifecycleStatus":{"type":"string","enum":["DISCOVERED","PENDING_REVIEW","APPROVED","TRUSTED","MONITORED","QUARANTINED","BLOCKED"]},"trustScore":{"type":"number"},"trustLevel":{"type":"string"},"riskLevel":{"type":"string"},"created":{"type":"boolean"}},"required":["id","name","address","type","category","approvalStatus","lifecycleStatus","trustScore","trustLevel","riskLevel","created"]}}}},"400":{"description":"Validation error"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope: counterparties:write required"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkCounterparties"}},"/api/sdk/counterparties/{id}":{"get":{"tags":["SDK Counterparties"],"summary":"Get counterparty details","description":"Get detailed counterparty info including trust relationship and recent transactions. Requires `counterparties:read` scope.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Counterparty ID"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Counterparty details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"address":{"type":"string"},"category":{"type":["string","null"]},"approvalStatus":{"type":"string","enum":["PENDING","APPROVED","BLOCKED"]},"lifecycleStatus":{"type":"string","enum":["DISCOVERED","PENDING_REVIEW","APPROVED","TRUSTED","MONITORED","QUARANTINED","BLOCKED"]},"verified":{"type":"boolean"},"riskLevel":{"type":"string"},"trustScore":{"type":"number"},"website":{"type":["string","null"]},"description":{"type":["string","null"]},"relationship":{"type":["object","null"],"properties":{"trustScore":{"type":"number"},"trustLevel":{"type":"string","enum":["TRUSTED","VERIFIED","UNKNOWN","SUSPICIOUS","BLOCKED"]},"transactionCount":{"type":"number"},"totalVolume":{"type":"number"},"firstTransactionAt":{"type":["string","null"]},"lastTransactionAt":{"type":["string","null"]}},"required":["trustScore","trustLevel","transactionCount","totalVolume","firstTransactionAt","lastTransactionAt"]},"recentTransactions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"status":{"type":"string"},"initiatedAt":{"type":"string"},"purpose":{"type":["string","null"]}},"required":["id","amount","currency","status","initiatedAt","purpose"]}}},"required":["id","name","address","category","approvalStatus","lifecycleStatus","verified","riskLevel","trustScore","website","description","relationship","recentTransactions"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope: counterparties:read required"},"404":{"description":"Counterparty not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkCounterpartiesById"},"patch":{"tags":["SDK Counterparties"],"summary":"Update a counterparty","description":"Update counterparty details. Requires `counterparties:write` scope.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Counterparty ID"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"}}}}}},"responses":{"200":{"description":"Counterparty updated"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope: counterparties:write required"},"404":{"description":"Counterparty not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"patchApiSdkCounterpartiesById"}},"/api/sdk/network/trust/{address}":{"get":{"tags":["SDK Counterparties"],"summary":"Get network trust for an address","description":"Look up normalized trust information for a wallet address or domain. Returns entity, relationship, activity, and risk-signal summaries. Requires `network:read` scope.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Wallet address to look up"},"required":true,"name":"address","in":"path"}],"responses":{"200":{"description":"Network trust information","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"entityType":{"type":"string","enum":["agent","counterparty","unknown"]},"entityInfo":{"type":["object","null"],"properties":{"name":{"type":["string","null"]},"category":{"type":["string","null"]},"website":{"type":["string","null"]}},"required":["name","category","website"],"additionalProperties":false},"trust":{"type":"object","properties":{"globalScore":{"type":["number","null"]},"isVerified":{"type":"boolean"},"riskLevel":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL","UNKNOWN"]},"networkRelationships":{"type":"number"},"riskSignalCount":{"type":"integer","minimum":0}},"required":["globalScore","isVerified","riskLevel","networkRelationships","riskSignalCount"]},"agentRelationship":{"type":["object","null"],"properties":{"trustScore":{"type":"number"},"trustLevel":{"type":"string","enum":["TRUSTED","VERIFIED","UNKNOWN","SUSPICIOUS","BLOCKED"]},"transactionCount":{"type":"number"},"totalVolume":{"type":"number"},"firstTransactionAt":{"type":["string","null"]},"lastTransactionAt":{"type":["string","null"]}},"required":["trustScore","trustLevel","transactionCount","totalVolume","firstTransactionAt","lastTransactionAt"]},"transactionHistory":{"type":"object","properties":{"count":{"type":"number"},"totalVolume":{"type":"number"}},"required":["count","totalVolume"]}},"required":["address","entityType","entityInfo","trust","agentRelationship","transactionHistory"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope: network:read required"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkNetworkTrustByAddress"}},"/api/sdk/all":{"get":{"tags":["SDK Agent"],"summary":"Get normalized agent data by section","description":"Deprecated compatibility endpoint. Preserves the historical section names and customer-useful fields while normalizing provider custody values, transaction policy decisions, alert status/severity, and other customer states. Wallet, policy, counterparty, transaction, alert, and analytics sections require their corresponding read scopes; capability summaries require `wallets:read`. An unavailable requested section contains a legacy scope error object and is also listed in `omittedSections`. Unknown `include` values are ignored. Raw alert metadata is not returned. Use `/api/sdk/setup` and the dedicated list endpoints for new integrations.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Comma-separated sections: agent, wallets, policies, counterparties, transactions, alerts, analytics, capabilities, endpoints. Unknown values are ignored.","example":"wallets,policies,transactions"},"required":false,"name":"include","in":"query"},{"schema":{"type":"string","enum":["day","week","month","year"],"default":"month"},"required":false,"name":"analyticsPeriod","in":"query"}],"responses":{"200":{"description":"Requested customer projections. Sections without their required SDK scope contain an error object and are identified in `omittedSections`.","headers":{"Deprecation":{"schema":{"type":"string","enum":["true"]},"required":true},"Link":{"schema":{"type":"string"},"required":true}},"content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"agentType":{"type":"string","enum":["OPENAI_ASSISTANT","ANTHROPIC_CLAUDE","AUTOGPT","CUSTOM"]},"status":{"type":"string","enum":["ACTIVE","PAUSED","SUSPENDED","REVOKED","UNAVAILABLE"]},"lastActiveAt":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","name","agentType","status","lastActiveAt","createdAt"],"additionalProperties":false},"wallets":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"},"custodyType":{"type":"string","enum":["MANAGED","EXTERNAL","SMART_CONTRACT"]},"chainId":{"type":"string"},"chainName":{"type":"string"},"chainType":{"type":"string"},"balance":{"type":"number"},"currency":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","PAUSED","UNAVAILABLE"]},"delegationType":{"type":"string","enum":["FULL","LIMITED","VIEW_ONLY","PREAPPROVED","ALLOWLIST"]},"limits":{"type":"object","properties":{"perTransaction":{"type":["number","null"]},"daily":{"type":["number","null"]},"weekly":{"type":["number","null"]},"monthly":{"type":["number","null"]}},"required":["perTransaction","daily","weekly","monthly"]},"spent":{"type":"object","properties":{"today":{"type":"number"},"thisWeek":{"type":"number"},"thisMonth":{"type":"number"}},"required":["today","thisWeek","thisMonth"]},"isExecutable":{"type":"boolean"}},"required":["id","name","address","custodyType","chainId","chainName","chainType","balance","currency","status","delegationType","limits","spent","isExecutable"],"additionalProperties":false}},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"policies":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"policyType":{"type":"string"},"priority":{"type":"number"},"description":{"type":["string","null"]},"scope":{"type":"string","enum":["organization","assigned"]},"appliesVia":{"type":"array","items":{"type":"string","enum":["organization","agent","wallet"]}},"assignedVia":{"type":"string","enum":["agent","wallet","organization"]},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"operator":{"type":"string"},"value":{"type":"string"},"action":{"type":"string"}},"required":["id","type","operator","value","action"],"additionalProperties":false}}},"required":["id","name","policyType","priority","description","scope","appliesVia","assignedVia","rules"],"additionalProperties":false}},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"counterparties":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"address":{"type":"string"},"category":{"type":["string","null"]},"trustScore":{"type":"number"},"trustLevel":{"type":"string","enum":["BLOCKED","SUSPICIOUS","UNKNOWN","VERIFIED","TRUSTED"]},"riskLevel":{"type":["string","null"]},"transactionCount":{"type":"number"},"totalVolume":{"type":"number"}},"required":["id","name","address","category","trustScore","trustLevel","riskLevel","transactionCount","totalVolume"],"additionalProperties":false}},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"transactions":{"anyOf":[{"type":"object","properties":{"recent":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"txHash":{"type":["string","null"]},"status":{"type":"string","enum":["PENDING","CONFIRMING","CONFIRMED","FAILED","UNKNOWN"]},"amount":{"type":"number"},"currency":{"type":"string"},"fromAddress":{"type":"string"},"toAddress":{"type":"string"},"recipientAgent":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"transactionType":{"type":"string","enum":["A2A","A2M","A2E","A2S","INCOMING","OTHER"]},"merchantName":{"type":["string","null"]},"merchantCategory":{"type":["string","null"]},"purpose":{"type":["string","null"]},"policyResult":{"type":"string","enum":["ALLOWED","REQUIRES_APPROVAL","DENIED","PENDING"]},"authorizationDecision":{"type":"string","enum":["approved","review_required","declined","pending"]},"initiatedAt":{"type":"string"},"confirmedAt":{"type":["string","null"]},"chainId":{"type":"string"}},"required":["id","txHash","status","amount","currency","fromAddress","toAddress","recipientAgent","transactionType","merchantName","merchantCategory","purpose","policyResult","authorizationDecision","initiatedAt","confirmedAt","chainId"],"additionalProperties":false}},"total":{"type":"number"}},"required":["recent","total"],"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"alerts":{"anyOf":[{"type":"object","properties":{"recent":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"alertType":{"type":"string","enum":["approval","payment_request","general"]},"kind":{"type":"string","enum":["approval","payment_request","general"]},"severity":{"type":"string","enum":["LOW","MEDIUM","HIGH"]},"severityLabel":{"type":"string","enum":["Low","Medium","High"]},"status":{"type":"string","enum":["PENDING","ACKNOWLEDGED","RESOLVED","DISMISSED"]},"normalizedStatus":{"type":"string","enum":["open","in_review","resolved","dismissed"]},"statusLabel":{"type":"string","enum":["Open","In review","Resolved","Dismissed"]},"title":{"type":"string"},"message":{"type":"string"},"transaction":{"type":["object","null"],"properties":{"id":{"type":"string"},"amount":{"type":"number"}},"required":["id","amount"],"additionalProperties":false},"createdAt":{"type":"string"},"reviewUrl":{"type":["string","null"]}},"required":["id","alertType","kind","severity","severityLabel","status","normalizedStatus","statusLabel","title","message","transaction","createdAt","reviewUrl"],"additionalProperties":false}},"activeCount":{"type":"number"}},"required":["recent","activeCount"],"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"analytics":{"anyOf":[{"type":"object","properties":{"period":{"type":"string","enum":["day","week","month","year"]},"summary":{"type":"object","properties":{"totalVolume":{"type":"number"},"transactionCount":{"type":"number"},"avgTransactionSize":{"type":"number"}},"required":["totalVolume","transactionCount","avgTransactionSize"],"additionalProperties":false},"categoryBreakdown":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"count":{"type":"number"},"volume":{"type":"number"},"percentage":{"type":"number"}},"required":["category","count","volume","percentage"],"additionalProperties":false}},"topMerchants":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"count":{"type":"number"},"volume":{"type":"number"}},"required":["name","count","volume"],"additionalProperties":false}}},"required":["period","summary","categoryBreakdown","topMerchants"],"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"capabilities":{"anyOf":[{"type":"object","properties":{"canRequestPayments":{"type":"boolean"},"canExecutePayments":{"type":"boolean"},"canAutoExecute":{"type":"boolean"},"maxSinglePayment":{"type":["number","null"]},"remainingDailyBudget":{"type":["number","null"]},"spentToday":{"type":"number"}},"required":["canRequestPayments","canExecutePayments","canAutoExecute","maxSinglePayment","remainingDailyBudget","spentToday"],"additionalProperties":false},{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}]},"endpoints":{"type":"array","items":{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"},"description":{"type":"string"},"scope":{"type":"string"}},"required":["method","path","description","scope"],"additionalProperties":false}},"scopes":{"type":"array","items":{"type":"string"}},"omittedSections":{"type":"array","items":{"type":"object","properties":{"section":{"type":"string"},"reason":{"type":"string","enum":["missing_scope"]},"requiredScope":{"type":"string"}},"required":["section","reason","requiredScope"]}}},"required":["scopes"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope: agents:read required"},"404":{"description":"Agent not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkAll"}},"/api/sdk/setup":{"get":{"tags":["SDK Agent"],"summary":"Get agent bootstrap configuration","description":"Returns the authenticated agent profile, normalized wallets, all effective organization/agent/wallet policies, counterparties, granted scopes, and versioned setup diagnostics. Requires `agents:read`. The response covers only this agent and includes its wallet balances, limits, and policy rules without `wallets:read` or `policies:read`. `diagnostics` says whether this key can request and execute payments, how each wallet executes, whether test and live connected cards are ready, and which issues need the agent or an owner, each with documented next actions.","security":[{"sdkKeyAuth":[]}],"responses":{"200":{"description":"Complete agent bootstrap data","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","paused","unavailable"]},"lastActiveAt":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","name","status","lastActiveAt","createdAt"]},"wallets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"address":{"type":"string"},"custodyMode":{"type":"string","enum":["MANAGED","EXTERNAL","SMART_CONTRACT"]},"chainId":{"type":["string","null"]},"chainName":{"type":["string","null"]},"chainType":{"type":["string","null"]},"isTestnet":{"type":"boolean"},"balance":{"type":"number"},"currency":{"type":"string"},"status":{"type":"string","enum":["active","paused","unavailable"]},"limits":{"type":"object","properties":{"perTransaction":{"type":["number","null"]},"daily":{"type":["number","null"]},"weekly":{"type":["number","null"]},"monthly":{"type":["number","null"]}},"required":["perTransaction","daily","weekly","monthly"]},"spent":{"type":"object","properties":{"today":{"type":"number"},"thisWeek":{"type":"number"},"thisMonth":{"type":"number"}},"required":["today","thisWeek","thisMonth"]}},"required":["id","address","custodyMode","chainId","chainName","chainType","isTestnet","balance","currency","status","limits","spent"]}},"policies":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"policyType":{"type":"string"},"priority":{"type":"number"},"scope":{"type":"string","enum":["organization","assigned"]},"appliesVia":{"type":"array","items":{"type":"string","enum":["organization","agent","wallet"]}},"assignedVia":{"type":"string","enum":["organization","agent","wallet"]},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"operator":{"type":"string"},"value":{"type":"string"},"action":{"type":"string"}},"required":["id","type","operator","value","action"]}}},"required":["id","name","description","policyType","priority","scope","appliesVia","assignedVia","rules"]}},"counterparties":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"address":{"type":"string"},"category":{"type":["string","null"]},"trustScore":{"type":"number"},"trustLevel":{"type":"string","enum":["trusted","verified","blocked","unverified"]},"transactionCount":{"type":"number"},"totalVolume":{"type":"number"}},"required":["id","name","address","category","trustScore","trustLevel","transactionCount","totalVolume"]}},"scopes":{"type":"array","items":{"type":"string"}},"diagnostics":{"anyOf":[{"$ref":"#/components/schemas/SetupDiagnostics"},{"type":"null"},{"type":"null"}],"description":"Versioned setup diagnostics. Null when Conto could not compute them for this request."}},"required":["agent","wallets","policies","counterparties","scopes","diagnostics"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication failed. A recognized key for a paused, frozen, or revoked agent, or an expired or revoked key, also gets `diagnostics` with the owner action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SdkSetupAuthError"}}}},"403":{"description":"Insufficient scope: agents:read required. An organization owner must act.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SdkSelfInspectionScopeError"}}}},"404":{"description":"Agent not found"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkSetup"}},"/api/sdk/payments/approve":{"post":{"tags":["SDK Payments"],"summary":"Check an external-wallet payment and get an approval token","description":"Request policy approval for a payment the agent will execute via its own external wallet. Returns an approval token to use when confirming. Requires `payments:approve` scope.","security":[{"sdkKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0,"description":"Payment amount"},"recipientAddress":{"type":"string","description":"Recipient wallet address"},"senderAddress":{"type":"string","description":"Sender wallet address (agent wallet)"},"recipientName":{"type":"string","description":"Recipient name"},"purpose":{"type":"string","description":"Payment purpose"},"category":{"type":"string","description":"Payment category"},"context":{"type":"object","properties":{"invoice":{"type":"object","properties":{"vendorId":{"type":"string","maxLength":255},"vendorAddress":{"type":"string","maxLength":255},"id":{"type":"string","maxLength":255},"hash":{"type":"string","maxLength":255},"sourceUrl":{"type":"string","maxLength":2048},"payload":{},"expectedAmount":{"anyOf":[{"type":"number"},{"type":"string","maxLength":255}]},"currency":{"type":"string","maxLength":50},"dueDate":{"type":"string","maxLength":255}},"additionalProperties":false}},"additionalProperties":false,"description":"Optional invoice details associated with the payment"},"chainId":{"anyOf":[{"type":"number"},{"type":"string","pattern":"^\\d+$"}],"description":"Chain ID (required). Accepts a number or numeric string. 8453=Base, 42431=Tempo Testnet, 84532=Base Sepolia, 1=Ethereum."}},"required":["amount","recipientAddress","senderAddress","chainId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Approval result","content":{"application/json":{"schema":{"type":"object","properties":{"approved":{"type":"boolean"},"decision":{"type":"string","enum":["approved","declined","review_required"]},"status":{"type":"string","enum":["ready_to_send","declined","review_required"]},"approvalId":{"type":"string"},"approvalRequestId":{"type":"string"},"approvalToken":{"type":"string"},"expiresAt":{"type":"string"},"confirmUrl":{"type":"string"},"statusUrl":{"type":"string"},"network":{"type":"object","properties":{"type":{"type":"string","enum":["evm","solana"]},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"reasons":{"type":"array","items":{"type":"string"}},"reasonCodes":{"type":"array","items":{"type":"string","enum":["INSUFFICIENT_BALANCE","SPENDING_LIMIT","RECIPIENT_NOT_ALLOWED","OUTSIDE_SCHEDULE","BUDGET_INSUFFICIENT","PAYMENT_CONTROLS","APPROVAL_REQUIRED","NO_WALLET","PAYEE_REVIEW_REQUIRED"]},"description":"Reason codes. PAYEE_REVIEW_REQUIRED means the payee is held for review; APPROVAL_REQUIRED covers other approval holds. NO_WALLET means no usable wallet is linked to the agent. It also covers a DEV or STAGING agent asking to pay from a mainnet wallet. Only PROD agents can, so the reason says to set the agent's environment to PROD and no wallet is created."},"requiresHumanApproval":{"type":"boolean"},"limits":{"type":["object","null"],"properties":{"dailyUsed":{"type":"number"},"dailyLimit":{"type":["number","null"]},"dailyRemaining":{"type":["number","null"]},"weeklyUsed":{"type":"number"},"weeklyLimit":{"type":["number","null"]},"monthlyUsed":{"type":"number"},"monthlyLimit":{"type":["number","null"]}},"required":["dailyUsed","dailyLimit","dailyRemaining","weeklyUsed","weeklyLimit","monthlyUsed","monthlyLimit"],"additionalProperties":false},"nextAction":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["submit_transaction"]},"confirmUrl":{"type":"string"},"expiresAt":{"type":"string"}},"required":["type","confirmUrl","expiresAt"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["check_status"]},"url":{"type":"string"}},"required":["type","url"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["request_budget"]},"url":{"type":"string"}},"required":["type","url"],"additionalProperties":false},{"type":"null"},{"type":"null"}]},"message":{"type":"string"}},"required":["approved","decision","status","reasons","reasonCodes","requiresHumanApproval","nextAction"],"additionalProperties":false}}}},"400":{"description":"Validation error"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope: payments:approve required"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"description":"Counterparty review (`COUNTERPARTY_REVIEW_UNAVAILABLE`) or the policy recheck after reserving spend (`POLICY_REVALIDATION_UNAVAILABLE`) is unavailable. No approval token is issued; retry later."}},"operationId":"postApiSdkPaymentsApprove"}},"/api/sdk/payments/{requestId}/confirm":{"post":{"tags":["SDK Payments"],"summary":"Confirm external wallet payment execution","description":"Confirm that an externally approved payment was executed by providing the transaction hash and approval token. Requires `payments:confirm` scope.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Payment approval ID"},"required":true,"name":"requestId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"txHash":{"type":"string","description":"Onchain transaction hash"},"approvalToken":{"type":"string","description":"Approval token from the approve response. Omit only after the payment has been approved through a configured review workflow."}},"required":["txHash"]}}}},"responses":{"200":{"description":"Payment confirmed","content":{"application/json":{"schema":{"type":"object","properties":{"confirmed":{"type":"boolean","enum":[true]},"requestId":{"type":"string"},"transactionId":{"type":"string"},"status":{"type":"string","enum":["processing"]},"txHash":{"type":"string"},"network":{"type":"object","properties":{"type":{"type":"string","enum":["evm","solana"]},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"explorerUrl":{"type":"string"},"statusUrl":{"type":"string"}},"required":["confirmed","requestId","transactionId","status","txHash","network","explorerUrl","statusUrl"],"additionalProperties":false}}}},"400":{"description":"Validation error or a non-confirmable payment state. State errors include a stable customer status and next action."},"401":{"description":"Authentication required"},"403":{"description":"Invalid approval token"},"404":{"description":"Payment approval not found"},"409":{"description":"Payment was already confirmed. Returns the existing transaction reference, hash, and status URL when available."},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkPaymentsByRequestIdConfirm"}},"/api/sdk/transactions/{id}/retry":{"post":{"tags":["SDK Transactions"],"summary":"Retry a failed transaction","description":"Create or resume one retry payment after a definitive onchain failure. The original receipt is preserved, controls are rechecked, and uncertain outcomes cannot be retried. Requires `transactions:write` and `payments:execute` scopes.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Transaction ID"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Retry request accepted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"requestId":{"type":"string"},"transactionId":{"type":["string","null"]},"status":{"type":"string","enum":["EXECUTING","CONFIRMING","CONFIRMED","COMPLETED"]},"statusUrl":{"type":"string"},"message":{"type":"string"}},"required":["success","requestId","status","statusUrl","message"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Insufficient scope: transactions:write and payments:execute required"},"404":{"description":"Transaction not found"},"409":{"description":"Transaction is not eligible for retry"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkTransactionsByIdRetry"}},"/api/sdk/x402/pre-authorize":{"post":{"tags":["x402"],"summary":"Pre-authorize an x402 payment","description":"Check policy approval before the agent signs an x402 payment with its own wallet. An approved decision returns a single-use grant for the exact wallet, recipient, and amount, and reserves the amount against spend limits for 10 minutes. Conto checks this decision but does not hold the key, so an agent that signs anyway is detected at record time, not stopped. For Privy-managed wallets use /api/sdk/x402/pay, where Conto signs and enforces.","security":[{"sdkKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402PreAuthorizeRequest"}}}},"responses":{"200":{"description":"Customer-facing authorization decision","content":{"application/json":{"schema":{"type":"object","properties":{"authorized":{"type":"boolean"},"decision":{"type":"string","enum":["approved","declined","review_required"]},"message":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"},"description":"Present when not authorized. Fixed reasons the agent can act on, without rule values or policy names."},"reasonCodes":{"type":"array","items":{"type":"string","enum":["SPENDING_LIMIT","RECIPIENT_NOT_ALLOWED","OUTSIDE_SCHEDULE","BUDGET_INSUFFICIENT","PAYMENT_CONTROLS","APPROVAL_REQUIRED","NO_WALLET","PAYEE_REVIEW_REQUIRED","INSUFFICIENT_BALANCE"]},"description":"Present when not authorized. SPENDING_LIMIT covers price ceilings, per-endpoint and session budgets, velocity, and period limits. RECIPIENT_NOT_ALLOWED covers blocked or unlisted services. PAYEE_REVIEW_REQUIRED means the payee is held for review; APPROVAL_REQUIRED covers other holds."},"grantId":{"type":"string","description":"Present when authorized. Single-use grant to pass to the record call. The amount is reserved against spend limits until it is consumed or expires."},"grantSignature":{"type":"string","description":"Signature to send back with grantId on the record call"},"grantExpiresAt":{"type":"string","description":"ISO timestamp after which the grant can no longer be consumed"},"x402":{"type":"object","properties":{"serviceDomain":{"type":"string"},"amount":{"type":"number"},"sessionId":{"type":"string"}},"required":["amount"]}},"required":["authorized","decision","message","x402"]}}}},"400":{"description":"Invalid authorization request"},"401":{"description":"Authentication required"},"422":{"description":"The wallet's network has no USDC (UNSUPPORTED_NETWORK). x402 settles in USDC. Nothing is reserved."},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"description":"PAYMENTS_PAUSED: no grant or spend reservation was created"}},"operationId":"postApiSdkX402PreAuthorize"}},"/api/sdk/x402/pay":{"post":{"tags":["x402"],"summary":"Approve and sign an x402 payment (Privy-managed wallet)","description":"Requires payments:execute. For agents whose wallet is a Privy-managed EVM wallet. Runs the same policy, budget, and grant issuance as pre-authorize. Only when approved, Conto signs an EIP-3009 TransferWithAuthorization for exactly the approved payee, amount, and USDC contract, and returns the payment header to retry the resource request with. The agent never holds the key, so Conto enforces this decision. Each grant is signed at most once. Pass the returned grant to /api/sdk/x402/record after settlement; an unrecorded grant is settled from the onchain nonce after the authorization expires. Returns 404 with code X402_MANAGED_SIGNING_DISABLED while managed x402 signing is not enabled for the deployment. The body names pre-authorize and record for agents that sign with their own wallet.","security":[{"sdkKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402PayRequest"}}}},"responses":{"200":{"description":"Authorization decision. When approved, includes the signed payment header. When declined or in review, the same body as pre-authorize and nothing is signed.","content":{"application/json":{"schema":{"type":"object","properties":{"authorized":{"type":"boolean"},"decision":{"type":"string","enum":["approved","declined","review_required"]},"message":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"},"description":"Present when not authorized. Fixed reasons the agent can act on, without rule values or policy names."},"reasonCodes":{"type":"array","items":{"type":"string","enum":["SPENDING_LIMIT","RECIPIENT_NOT_ALLOWED","OUTSIDE_SCHEDULE","BUDGET_INSUFFICIENT","PAYMENT_CONTROLS","APPROVAL_REQUIRED","NO_WALLET","PAYEE_REVIEW_REQUIRED","INSUFFICIENT_BALANCE"]},"description":"Present when not authorized. SPENDING_LIMIT covers price ceilings, per-endpoint and session budgets, velocity, and period limits. RECIPIENT_NOT_ALLOWED covers blocked or unlisted services. PAYEE_REVIEW_REQUIRED means the payee is held for review; APPROVAL_REQUIRED covers other holds."},"grantId":{"type":"string"},"grantSignature":{"type":"string"},"grantExpiresAt":{"type":"string"},"paymentHeaderName":{"type":"string","enum":["X-PAYMENT","PAYMENT-SIGNATURE"],"description":"Header to send on the retried resource request"},"xPaymentHeader":{"type":"string","description":"Base64 x402 payment payload signed by Conto"},"authorization":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"value":{"type":"string"},"validAfter":{"type":"string"},"validBefore":{"type":"string"},"nonce":{"type":"string"}},"required":["from","to","value","validAfter","validBefore","nonce"],"description":"The EIP-3009 authorization Conto signed"},"x402":{"type":"object","properties":{"serviceDomain":{"type":"string"},"amount":{"type":"number"},"sessionId":{"type":"string"}},"required":["amount"]}},"required":["authorized","decision","message","x402"]}}}},"400":{"description":"Invalid payment request"},"401":{"description":"Authentication required"},"404":{"description":"Managed x402 signing is not enabled"},"409":{"description":"Wallet not managed by Conto (MANAGED_SIGNING_UNAVAILABLE, use pre-authorize and record), grant already signed (GRANT_ALREADY_SIGNED), or wallet selection required"},"422":{"description":"Payment requirements do not match the request (REQUIREMENTS_MISMATCH): payee, amount, asset, network, scheme, or token domain. Or the wallet's network has no USDC (UNSUPPORTED_NETWORK). Nothing is reserved or signed."},"500":{"$ref":"#/components/responses/InternalServerError"},"502":{"description":"Signing failed (SIGNING_FAILED). Nothing was paid; the grant is void."},"503":{"description":"PAYMENTS_PAUSED or live-payment controls refused signing; nothing was signed"}},"operationId":"postApiSdkX402Pay"}},"/api/sdk/x402/record":{"post":{"tags":["x402"],"summary":"Record x402 payment(s)","description":"Record a single x402 payment or a batch of micropayments. Send the grant from an approved pre-authorize: Conto checks the settlement onchain against the grant recipient and amount, then consumes the grant. A record without a valid, unexpired grant is accepted because the payment already settled, but it is flagged as a policy bypass and a critical alert is raised. An organization can also configure Conto to freeze the agent automatically.","security":[{"sdkKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402RecordRequest"}}}},"responses":{"201":{"description":"Payment record accepted","content":{"application/json":{"schema":{"type":"object","properties":{"recorded":{"type":"boolean","enum":[true]},"txHash":{"type":"string"},"explorerUrl":{"type":"string","format":"uri"},"sessionId":{"type":"string"},"grantId":{"type":"string","description":"Grant consumed by this record"},"policyBypass":{"type":"boolean","enum":[true],"description":"Present when the payment was recorded without a valid, unexpired grant"},"bypassReason":{"type":"string","enum":["GRANT_MISSING","GRANT_INVALID","GRANT_EXPIRED"]},"agentFrozen":{"type":"boolean","description":"True when the organization freezes agents on a policy bypass and this record froze the agent"}},"required":["recorded"]}}}},"400":{"description":"Invalid payment record"},"401":{"description":"Authentication required"},"409":{"description":"Grant already consumed (GRANT_ALREADY_CONSUMED), payment already recorded, or settlement pending"},"422":{"description":"Settlement does not match the grant or the onchain transfer (SETTLEMENT_MISMATCH); the grant stays unused"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"description":"Settlement verification temporarily unavailable"}},"operationId":"postApiSdkX402Record"}},"/api/sdk/x402/services":{"get":{"tags":["x402"],"summary":"List x402 services used by agent","security":[{"sdkKeyAuth":[]}],"responses":{"200":{"description":"Customer-facing x402 service summaries","content":{"application/json":{"schema":{"type":"object","properties":{"services":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"name":{"type":["string","null"]},"totalCalls":{"type":"number"},"totalSpend":{"type":"number"},"averageCost":{"type":"number"},"lastUsedAt":{"type":["string","null"]},"recent":{"type":"object","properties":{"calls":{"type":"number"},"spend":{"type":"number"},"averageCost":{"type":"number"}},"required":["calls","spend","averageCost"]}},"required":["domain","name","totalCalls","totalSpend","averageCost","lastUsedAt","recent"]}},"summary":{"type":"object","properties":{"serviceCount":{"type":"number"},"totalCalls":{"type":"number"},"totalSpend":{"type":"number"},"averageCost":{"type":"number"}},"required":["serviceCount","totalCalls","totalSpend","averageCost"]},"period":{"type":"string","enum":["24h","7d","30d","90d"]}},"required":["services","summary","period"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkX402Services"}},"/api/sdk/x402/budget":{"get":{"tags":["x402"],"summary":"Check x402 budget remaining","description":"Get aggregate x402 spend, effective limits, and a customer-facing usage trend.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Customer-supplied session ID to include a session spend summary"},"required":false,"name":"sessionId","in":"query"}],"responses":{"200":{"description":"Aggregate spend, effective limits, and trend","content":{"application/json":{"schema":{"type":"object","properties":{"spend":{"type":"object","properties":{"daily":{"type":"object","properties":{"calls":{"type":"number"},"amount":{"type":"number"}},"required":["calls","amount"]},"weekly":{"type":"object","properties":{"calls":{"type":"number"},"amount":{"type":"number"}},"required":["calls","amount"]},"monthly":{"type":"object","properties":{"calls":{"type":"number"},"amount":{"type":"number"}},"required":["calls","amount"]},"session":{"type":["object","null"],"properties":{"sessionId":{"type":"string"},"calls":{"type":"number"},"amount":{"type":"number"}},"required":["sessionId","calls","amount"]}},"required":["daily","weekly","monthly","session"]},"limits":{"type":"object","properties":{"daily":{"type":["number","null"]},"weekly":{"type":["number","null"]},"monthly":{"type":["number","null"]},"perPayment":{"type":["number","null"]}},"required":["daily","weekly","monthly","perPayment"]},"trend":{"type":"object","properties":{"spendPerHour":{"type":"number"},"callsPerHour":{"type":"number"},"averageCost":{"type":"number"},"estimatedHoursRemaining":{"type":["number","null"]}},"required":["spendPerHour","callsPerHour","averageCost","estimatedHoursRemaining"]}},"required":["spend","limits","trend"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkX402Budget"}},"/api/sdk/mpp/pre-authorize":{"post":{"tags":["MPP"],"summary":"Pre-authorize an MPP payment","description":"Check policy approval before creating an MPP credential. The agent sends the WWW-Authenticate: Payment challenge contents and Conto evaluates policies without executing anything. An approved decision returns a grant and reserves the amount against spend limits. A charge grant lasts 10 minutes. A session grant lasts for the session: the shortest MPP_MAX_SESSION_DURATION rule that applies, up to 7 days, or 24 hours when no rule applies.","security":[{"sdkKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","description":"Payment amount in the wallet chain stablecoin"},"recipientAddress":{"type":"string","description":"Recipient wallet address"},"resourceUrl":{"type":"string","description":"Target API endpoint URL"},"intent":{"type":"string","enum":["charge","session"],"description":"Payment intent: charge (one-time) or session (streaming)"},"depositAmount":{"type":"number","description":"Session deposit amount (for session intent)"},"sessionId":{"type":"string","minLength":1,"maxLength":255,"description":"Customer-supplied ID used to group related MPP payments"},"scheme":{"type":"string","description":"MPP payment scheme"},"credentialId":{"type":"string","description":"MPP credential ID"},"challengeId":{"type":"string","description":"MPP challenge ID"},"paymentMethod":{"type":"string","description":"MPP payment method"},"payerAddress":{"type":"string","description":"Agent wallet address the MPP client pays from. Send it with network when the agent has more than one wallet it signs with."},"network":{"type":"string","description":"CAIP-2 network of payerAddress","example":"eip155:42431"}},"required":["amount","recipientAddress","resourceUrl"]}}}},"responses":{"200":{"description":"Customer-facing authorization decision","content":{"application/json":{"schema":{"type":"object","properties":{"authorized":{"type":"boolean"},"decision":{"type":"string","enum":["approved","declined","review_required"]},"message":{"type":"string"},"reasons":{"type":"array","items":{"type":"string"},"description":"Present when not authorized. Fixed reasons the agent can act on, without rule values or policy names."},"reasonCodes":{"type":"array","items":{"type":"string","enum":["SPENDING_LIMIT","RECIPIENT_NOT_ALLOWED","OUTSIDE_SCHEDULE","BUDGET_INSUFFICIENT","PAYMENT_CONTROLS","APPROVAL_REQUIRED","NO_WALLET","PAYEE_REVIEW_REQUIRED","INSUFFICIENT_BALANCE"]},"description":"Present when not authorized. SPENDING_LIMIT covers price ceilings, per-endpoint and session budgets, velocity, and period limits. RECIPIENT_NOT_ALLOWED covers blocked or unlisted services. PAYEE_REVIEW_REQUIRED means the payee is held for review; APPROVAL_REQUIRED covers other holds."},"grantId":{"type":"string","description":"Present when authorized. Grant to pass to the record call. The amount is reserved against spend limits until it is consumed, its session is closed, or it expires."},"grantSignature":{"type":"string","description":"Signature to send back with grantId on the record call"},"grantExpiresAt":{"type":"string","description":"ISO timestamp after which the grant can no longer be consumed"},"mpp":{"type":"object","properties":{"serviceDomain":{"type":"string"},"amount":{"type":"number"},"sessionId":{"type":"string"}},"required":["amount"]}},"required":["authorized","decision","message","mpp"]}}}},"400":{"description":"Invalid authorization request"},"401":{"description":"Authentication required"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"description":"PAYMENTS_PAUSED: no grant or spend reservation was created"}},"operationId":"postApiSdkMppPreAuthorize"}},"/api/sdk/mpp/record":{"post":{"tags":["MPP"],"summary":"Record MPP payment(s)","description":"Record a single MPP payment or a batch of micropayments. Send the grant from an approved pre-authorize: a charge grant must match the recipient and exact amount, and a session grant accepts amounts up to its remaining ceiling. A record without a valid, unexpired grant is accepted because the payment already settled, but it is flagged as a policy bypass and a critical alert is raised. An organization can also configure Conto to freeze the agent automatically. To close a session with nothing more to charge, send amount 0 with intent session, closeSession true, and the session grant: Conto closes the session and releases the unused grant without recording a transaction.","security":[{"sdkKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"description":"Total payment amount. Must be positive, except 0 on a session record that sends closeSession true and the session grant, with no txHash, paymentReceipt, or batchItems."},"currency":{"type":"string","description":"Currency symbol. If omitted, Conto resolves it from the wallet chain (for example USDC.e on Tempo mainnet or pathUSD on Tempo testnet)."},"recipientAddress":{"type":"string","description":"Recipient wallet address"},"resourceUrl":{"type":"string","description":"API endpoint URL"},"credentialId":{"type":"string","description":"Stable MPP credential ID"},"sessionId":{"type":"string","minLength":1,"maxLength":255,"description":"Customer-supplied ID used to group related MPP payments"},"paymentReceipt":{"type":"string","description":"Caller-supplied Payment-Receipt value; structurally checked but not authoritative settlement proof"},"txHash":{"type":"string","description":"Onchain transaction hash; the transfer must match sender, recipient, amount, and currency before confirmation"},"intent":{"type":"string","enum":["charge","session"],"description":"Payment intent: charge or session"},"scheme":{"type":"string","description":"MPP payment scheme"},"challengeId":{"type":"string","description":"Expected challenge ID for receipt binding"},"paymentMethod":{"type":"string","description":"MPP payment method"},"depositAmount":{"type":"number","description":"Opening session deposit amount"},"batchItems":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"number"},"resourceUrl":{"type":"string"},"credentialId":{"type":"string"}},"required":["amount","resourceUrl","credentialId"]},"description":"Batch of individual MPP calls"},"grantId":{"type":"string","description":"Grant ID returned by an approved pre-authorize. A record without a valid, unexpired grant is accepted as a policy bypass: the transaction is flagged and a critical alert is raised. An organization can also configure Conto to freeze the agent automatically."},"grantSignature":{"type":"string","description":"Grant signature returned by pre-authorize, sent back unchanged"},"closeSession":{"type":"boolean","description":"Send true on the final record of a session. Conto marks the session closed, so it no longer counts toward MPP_MAX_CONCURRENT_SESSIONS, and releases the unused part of the session grant. Requires intent session. When the session has nothing more to charge, send amount 0: the close needs the session grant and records no transaction. Repeating it returns the same response."}},"required":["amount","recipientAddress","resourceUrl","credentialId"]}}}},"responses":{"200":{"description":"Session closed with no charge (amount 0 and closeSession true)","content":{"application/json":{"schema":{"type":"object","properties":{"recorded":{"type":"boolean","enum":[true]},"sessionClosed":{"type":"boolean","enum":[true]},"sessionId":{"type":"string"},"grantId":{"type":"string","description":"Session grant closed by this record"}},"required":["recorded","sessionClosed","sessionId","grantId"]}}}},"201":{"description":"Payment record accepted","content":{"application/json":{"schema":{"type":"object","properties":{"recorded":{"type":"boolean","enum":[true]},"confirmed":{"type":"boolean"},"txHash":{"type":"string"},"explorerUrl":{"type":"string","format":"uri"},"sessionId":{"type":"string"},"grantId":{"type":"string","description":"Grant consumed by this record"},"policyBypass":{"type":"boolean","enum":[true],"description":"Present when the payment was recorded without a valid, unexpired grant"},"bypassReason":{"type":"string","enum":["GRANT_MISSING","GRANT_INVALID","GRANT_EXPIRED"]},"agentFrozen":{"type":"boolean","description":"True when the organization freezes agents on a policy bypass and this record froze the agent"}},"required":["recorded","confirmed"]}}}},"400":{"description":"Invalid request or unsuccessful/challenge-mismatched receipt"},"401":{"description":"Authentication required"},"409":{"description":"Grant already consumed (GRANT_ALREADY_CONSUMED), grant expired before a close with no charge (GRANT_EXPIRED), session owned by another agent, duplicate credential ID, receipt mismatch, or settlement still pending"},"422":{"description":"Settlement does not match the grant or the onchain transfer (SETTLEMENT_MISMATCH), or a close with no charge presents no valid grant for this agent (GRANT_INVALID). The grant stays unused"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"description":"Settlement verification temporarily unavailable"}},"operationId":"postApiSdkMppRecord"}},"/api/sdk/mpp/services":{"get":{"tags":["MPP"],"summary":"List MPP services used by agent","description":"List all MPP services the agent has interacted with, including spend summaries, price trends, and known endpoints.","security":[{"sdkKeyAuth":[]}],"responses":{"200":{"description":"Customer-facing MPP service summaries","content":{"application/json":{"schema":{"type":"object","properties":{"services":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"name":{"type":["string","null"]},"totalCalls":{"type":"number"},"totalSpend":{"type":"number"},"averageCost":{"type":"number"},"lastUsedAt":{"type":["string","null"]},"recent":{"type":"object","properties":{"calls":{"type":"number"},"spend":{"type":"number"},"averageCost":{"type":"number"}},"required":["calls","spend","averageCost"]}},"required":["domain","name","totalCalls","totalSpend","averageCost","lastUsedAt","recent"]}},"summary":{"type":"object","properties":{"serviceCount":{"type":"number"},"totalCalls":{"type":"number"},"totalSpend":{"type":"number"},"averageCost":{"type":"number"}},"required":["serviceCount","totalCalls","totalSpend","averageCost"]},"period":{"type":"string","enum":["24h","7d","30d","90d"]}},"required":["services","summary","period"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkMppServices"}},"/api/sdk/mpp/budget":{"get":{"tags":["MPP"],"summary":"Check MPP budget remaining","description":"Get aggregate MPP spend, effective limits, and a customer-facing usage trend.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Customer-supplied session ID to include a session spend summary"},"required":false,"name":"sessionId","in":"query"}],"responses":{"200":{"description":"Aggregate spend, effective limits, and trend","content":{"application/json":{"schema":{"type":"object","properties":{"spend":{"type":"object","properties":{"daily":{"type":"object","properties":{"calls":{"type":"number"},"amount":{"type":"number"}},"required":["calls","amount"]},"weekly":{"type":"object","properties":{"calls":{"type":"number"},"amount":{"type":"number"}},"required":["calls","amount"]},"monthly":{"type":"object","properties":{"calls":{"type":"number"},"amount":{"type":"number"}},"required":["calls","amount"]},"session":{"type":["object","null"],"properties":{"sessionId":{"type":"string"},"calls":{"type":"number"},"amount":{"type":"number"}},"required":["sessionId","calls","amount"]}},"required":["daily","weekly","monthly","session"]},"limits":{"type":"object","properties":{"daily":{"type":["number","null"]},"weekly":{"type":["number","null"]},"monthly":{"type":["number","null"]},"perPayment":{"type":["number","null"]}},"required":["daily","weekly","monthly","perPayment"]},"trend":{"type":"object","properties":{"spendPerHour":{"type":"number"},"callsPerHour":{"type":"number"},"averageCost":{"type":"number"},"estimatedHoursRemaining":{"type":["number","null"]}},"required":["spendPerHour","callsPerHour","averageCost","estimatedHoursRemaining"]}},"required":["spend","limits","trend"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkMppBudget"}},"/api/sdk/checkout-checkpoints":{"post":{"tags":["Checkout checkpoints"],"summary":"Check a proposed checkout before opening its payment method","description":"Requires payments:request. The caller must stop when the response does not approve the purchase. This check is enforced by the caller, not by the payment method. When the rules require approval, the spend is held, the owner is asked, and the checkpoint returns stage AWAITING_APPROVAL with the approval request id. Poll the checkpoint until the owner decides.","security":[{"sdkKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"idempotencyKey":{"type":"string","minLength":8,"maxLength":255},"checkoutMethod":{"type":"string","enum":["LINK","CARD","SHOP_PAY","PAYPAL"]},"merchant":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"checkoutUrl":{"type":"string","format":"uri"}},"required":["id","name","checkoutUrl"]},"amountMinor":{"type":"integer","exclusiveMinimum":0,"maximum":500000},"currency":{"type":"string","enum":["USD"]},"purpose":{"type":"string"},"category":{"type":"string"},"cart":{"type":"object","properties":{"lineItems":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"quantity":{"type":"integer","exclusiveMinimum":0},"unitAmountMinor":{"type":"integer","minimum":0},"description":{"type":"string"},"sku":{"type":"string"},"productUrl":{"type":"string","format":"uri"}},"required":["name","quantity","unitAmountMinor"]},"minItems":1,"maxItems":50},"totals":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["subtotal","tax","total","items_base_amount","items_discount","discount","fulfillment","shipping","fee","gift_wrap","tip","store_credit"]},"label":{"type":"string"},"amountMinor":{"type":"integer"}},"required":["type","label","amountMinor"]},"minItems":1,"maxItems":25},"fulfillment":{"type":"object","properties":{"recipient":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"locality":{"type":"string"},"region":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2}}}},"required":["lineItems","totals"]},"providerPresentation":{"type":"object","properties":{"approvalSummary":{"type":"string"},"lineItemLabels":{"type":"array","items":{"type":"string"}}},"required":["approvalSummary","lineItemLabels"]}},"required":["idempotencyKey","merchant","amountMinor","currency","purpose","cart"]}}}},"responses":{"200":{"description":"Current checkout checkpoint; outcomes are caller-reported, not verified settlement","content":{"application/json":{"schema":{"type":"object","properties":{"checkpoint":{"type":"object","properties":{"id":{"type":"string"},"idempotencyKey":{"type":"string"},"agentId":{"type":"string"},"checkoutMethod":{"type":"string","enum":["LINK","CARD","SHOP_PAY","PAYPAL"]},"stage":{"type":"string","enum":["AWAITING_APPROVAL","APPROVED","CONFIRMING","CONFIRMED","PAID","NOT_PAID","OUTCOME_UNKNOWN","DENIED","CANCELLED","EXPIRED"]},"nextAction":{"type":"string","enum":["WAIT_FOR_APPROVAL","CONFIRM_BEFORE_PAYING","PAY_THEN_REPORT_OUTCOME","REPORT_OUTCOME","WAIT","NONE"]},"amountMinor":{"type":"number"},"currency":{"type":"string","enum":["USD"]},"purpose":{"type":"string"},"category":{"type":"string"},"merchant":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"checkoutUrl":{"type":"string"}},"required":["id","name","checkoutUrl"]},"cart":{"type":"object","properties":{"lineItems":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"quantity":{"type":"number"},"unitAmountMinor":{"type":"number"}},"required":["name","quantity","unitAmountMinor"]}},"totals":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"label":{"type":"string"},"amountMinor":{"type":"number"}},"required":["type","label","amountMinor"]}},"fulfillment":{"type":"object","additionalProperties":{"type":"string"}}},"required":["lineItems","totals"]},"expiresAt":{"type":"string"},"approval":{"type":"object","properties":{"requestId":{"type":"string"},"status":{"type":"string","enum":["PENDING","APPROVED","DENIED","EXPIRED","CANCELLED"]},"expiresAt":{"type":"string"}},"required":["requestId","status"]},"outcomeReference":{"type":"string"},"paymentReference":{"type":"object","properties":{"provider":{"type":"string","enum":["LINK"]},"id":{"type":"string","pattern":"^lsrq_[A-Za-z0-9]{1,64}$","description":"Link spend request id, such as lsrq_... An id only: a value that contains a card number is refused."}},"required":["provider","id"],"description":"The payment behind this checkout, such as the Link spend request that issued a Link card. The checkpoint keeps the first one it receives."},"settlementVerified":{"type":"boolean","enum":[false]}},"required":["id","idempotencyKey","agentId","checkoutMethod","stage","nextAction","amountMinor","currency","purpose","merchant","cart","expiresAt","settlementVerified"]}},"required":["checkpoint"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Denied by policy or missing scope"},"409":{"description":"Idempotency conflict"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"description":"PAYMENTS_PAUSED: no new spend was reserved or released"}},"operationId":"postApiSdkCheckoutCheckpoints"}},"/api/sdk/checkout-checkpoints/{id}":{"get":{"tags":["Checkout checkpoints"],"summary":"Read a checkout checkpoint","description":"Requires transactions:read. Read before retrying after an uncertain response, and to poll while the stage is AWAITING_APPROVAL.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Current checkout checkpoint; outcomes are caller-reported, not verified settlement","content":{"application/json":{"schema":{"type":"object","properties":{"checkpoint":{"type":"object","properties":{"id":{"type":"string"},"idempotencyKey":{"type":"string"},"agentId":{"type":"string"},"checkoutMethod":{"type":"string","enum":["LINK","CARD","SHOP_PAY","PAYPAL"]},"stage":{"type":"string","enum":["AWAITING_APPROVAL","APPROVED","CONFIRMING","CONFIRMED","PAID","NOT_PAID","OUTCOME_UNKNOWN","DENIED","CANCELLED","EXPIRED"]},"nextAction":{"type":"string","enum":["WAIT_FOR_APPROVAL","CONFIRM_BEFORE_PAYING","PAY_THEN_REPORT_OUTCOME","REPORT_OUTCOME","WAIT","NONE"]},"amountMinor":{"type":"number"},"currency":{"type":"string","enum":["USD"]},"purpose":{"type":"string"},"category":{"type":"string"},"merchant":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"checkoutUrl":{"type":"string"}},"required":["id","name","checkoutUrl"]},"cart":{"type":"object","properties":{"lineItems":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"quantity":{"type":"number"},"unitAmountMinor":{"type":"number"}},"required":["name","quantity","unitAmountMinor"]}},"totals":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"label":{"type":"string"},"amountMinor":{"type":"number"}},"required":["type","label","amountMinor"]}},"fulfillment":{"type":"object","additionalProperties":{"type":"string"}}},"required":["lineItems","totals"]},"expiresAt":{"type":"string"},"approval":{"type":"object","properties":{"requestId":{"type":"string"},"status":{"type":"string","enum":["PENDING","APPROVED","DENIED","EXPIRED","CANCELLED"]},"expiresAt":{"type":"string"}},"required":["requestId","status"]},"outcomeReference":{"type":"string"},"paymentReference":{"type":"object","properties":{"provider":{"type":"string","enum":["LINK"]},"id":{"type":"string","pattern":"^lsrq_[A-Za-z0-9]{1,64}$","description":"Link spend request id, such as lsrq_... An id only: a value that contains a card number is refused."}},"required":["provider","id"],"description":"The payment behind this checkout, such as the Link spend request that issued a Link card. The checkpoint keeps the first one it receives."},"settlementVerified":{"type":"boolean","enum":[false]}},"required":["id","idempotencyKey","agentId","checkoutMethod","stage","nextAction","amountMinor","currency","purpose","merchant","cart","expiresAt","settlementVerified"]}},"required":["checkpoint"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"404":{"description":"Checkpoint not found for this agent"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkCheckoutCheckpointsById"}},"/api/sdk/checkout-checkpoints/{id}/confirm":{"post":{"tags":["Checkout checkpoints"],"summary":"Recheck final checkout details before payment submission","description":"Requires payments:execute. A changed total is refused; cancel and begin a new checkpoint for the final total.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amountMinor":{"type":"integer","exclusiveMinimum":0,"maximum":500000},"currency":{"type":"string","enum":["USD"]},"cart":{"type":"object","properties":{"lineItems":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"quantity":{"type":"integer","exclusiveMinimum":0},"unitAmountMinor":{"type":"integer","minimum":0},"description":{"type":"string"},"sku":{"type":"string"},"productUrl":{"type":"string","format":"uri"}},"required":["name","quantity","unitAmountMinor"]},"minItems":1,"maxItems":50},"totals":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["subtotal","tax","total","items_base_amount","items_discount","discount","fulfillment","shipping","fee","gift_wrap","tip","store_credit"]},"label":{"type":"string"},"amountMinor":{"type":"integer"}},"required":["type","label","amountMinor"]},"minItems":1,"maxItems":25},"fulfillment":{"type":"object","properties":{"recipient":{"type":"string"},"addressLine1":{"type":"string"},"addressLine2":{"type":"string"},"locality":{"type":"string"},"region":{"type":"string"},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2}}}},"required":["lineItems","totals"]},"pageUrl":{"type":"string","format":"uri"},"paymentReference":{"type":"object","properties":{"provider":{"type":"string","enum":["LINK"]},"id":{"type":"string","pattern":"^lsrq_[A-Za-z0-9]{1,64}$","description":"Link spend request id, such as lsrq_... An id only: a value that contains a card number is refused."}},"required":["provider","id"],"description":"The payment behind this checkout, such as the Link spend request that issued a Link card. The checkpoint keeps the first one it receives."}},"required":["amountMinor","currency"]}}}},"responses":{"200":{"description":"Current checkout checkpoint; outcomes are caller-reported, not verified settlement","content":{"application/json":{"schema":{"type":"object","properties":{"checkpoint":{"type":"object","properties":{"id":{"type":"string"},"idempotencyKey":{"type":"string"},"agentId":{"type":"string"},"checkoutMethod":{"type":"string","enum":["LINK","CARD","SHOP_PAY","PAYPAL"]},"stage":{"type":"string","enum":["AWAITING_APPROVAL","APPROVED","CONFIRMING","CONFIRMED","PAID","NOT_PAID","OUTCOME_UNKNOWN","DENIED","CANCELLED","EXPIRED"]},"nextAction":{"type":"string","enum":["WAIT_FOR_APPROVAL","CONFIRM_BEFORE_PAYING","PAY_THEN_REPORT_OUTCOME","REPORT_OUTCOME","WAIT","NONE"]},"amountMinor":{"type":"number"},"currency":{"type":"string","enum":["USD"]},"purpose":{"type":"string"},"category":{"type":"string"},"merchant":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"checkoutUrl":{"type":"string"}},"required":["id","name","checkoutUrl"]},"cart":{"type":"object","properties":{"lineItems":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"quantity":{"type":"number"},"unitAmountMinor":{"type":"number"}},"required":["name","quantity","unitAmountMinor"]}},"totals":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"label":{"type":"string"},"amountMinor":{"type":"number"}},"required":["type","label","amountMinor"]}},"fulfillment":{"type":"object","additionalProperties":{"type":"string"}}},"required":["lineItems","totals"]},"expiresAt":{"type":"string"},"approval":{"type":"object","properties":{"requestId":{"type":"string"},"status":{"type":"string","enum":["PENDING","APPROVED","DENIED","EXPIRED","CANCELLED"]},"expiresAt":{"type":"string"}},"required":["requestId","status"]},"outcomeReference":{"type":"string"},"paymentReference":{"type":"object","properties":{"provider":{"type":"string","enum":["LINK"]},"id":{"type":"string","pattern":"^lsrq_[A-Za-z0-9]{1,64}$","description":"Link spend request id, such as lsrq_... An id only: a value that contains a card number is refused."}},"required":["provider","id"],"description":"The payment behind this checkout, such as the Link spend request that issued a Link card. The checkpoint keeps the first one it receives."},"settlementVerified":{"type":"boolean","enum":[false]}},"required":["id","idempotencyKey","agentId","checkoutMethod","stage","nextAction","amountMinor","currency","purpose","merchant","cart","expiresAt","settlementVerified"]}},"required":["checkpoint"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"403":{"description":"Denied by policy or missing scope"},"409":{"description":"Total changed, owner approval still pending (APPROVAL_REQUIRED), a different payment reference, expired, or invalid checkpoint state"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"description":"PAYMENTS_PAUSED: no new spend was reserved or released"}},"operationId":"postApiSdkCheckoutCheckpointsByIdConfirm"}},"/api/sdk/checkout-checkpoints/{id}/outcome":{"post":{"tags":["Checkout checkpoints"],"summary":"Report the outcome of a confirmed checkout","description":"Requires payments:confirm. PAID keeps the spend counted, NOT_PAID releases it, and UNKNOWN keeps it reserved for reconciliation. The report is not verified settlement evidence.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","enum":["PAID","NOT_PAID","UNKNOWN"]},"reference":{"type":"string","pattern":"^[A-Za-z0-9._:#/-]+$"},"paymentReference":{"type":"object","properties":{"provider":{"type":"string","enum":["LINK"]},"id":{"type":"string","pattern":"^lsrq_[A-Za-z0-9]{1,64}$","description":"Link spend request id, such as lsrq_... An id only: a value that contains a card number is refused."}},"required":["provider","id"],"description":"The payment behind this checkout, such as the Link spend request that issued a Link card. The checkpoint keeps the first one it receives."}},"required":["outcome"]}}}},"responses":{"200":{"description":"Current checkout checkpoint; outcomes are caller-reported, not verified settlement","content":{"application/json":{"schema":{"type":"object","properties":{"checkpoint":{"type":"object","properties":{"id":{"type":"string"},"idempotencyKey":{"type":"string"},"agentId":{"type":"string"},"checkoutMethod":{"type":"string","enum":["LINK","CARD","SHOP_PAY","PAYPAL"]},"stage":{"type":"string","enum":["AWAITING_APPROVAL","APPROVED","CONFIRMING","CONFIRMED","PAID","NOT_PAID","OUTCOME_UNKNOWN","DENIED","CANCELLED","EXPIRED"]},"nextAction":{"type":"string","enum":["WAIT_FOR_APPROVAL","CONFIRM_BEFORE_PAYING","PAY_THEN_REPORT_OUTCOME","REPORT_OUTCOME","WAIT","NONE"]},"amountMinor":{"type":"number"},"currency":{"type":"string","enum":["USD"]},"purpose":{"type":"string"},"category":{"type":"string"},"merchant":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"checkoutUrl":{"type":"string"}},"required":["id","name","checkoutUrl"]},"cart":{"type":"object","properties":{"lineItems":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"quantity":{"type":"number"},"unitAmountMinor":{"type":"number"}},"required":["name","quantity","unitAmountMinor"]}},"totals":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"label":{"type":"string"},"amountMinor":{"type":"number"}},"required":["type","label","amountMinor"]}},"fulfillment":{"type":"object","additionalProperties":{"type":"string"}}},"required":["lineItems","totals"]},"expiresAt":{"type":"string"},"approval":{"type":"object","properties":{"requestId":{"type":"string"},"status":{"type":"string","enum":["PENDING","APPROVED","DENIED","EXPIRED","CANCELLED"]},"expiresAt":{"type":"string"}},"required":["requestId","status"]},"outcomeReference":{"type":"string"},"paymentReference":{"type":"object","properties":{"provider":{"type":"string","enum":["LINK"]},"id":{"type":"string","pattern":"^lsrq_[A-Za-z0-9]{1,64}$","description":"Link spend request id, such as lsrq_... An id only: a value that contains a card number is refused."}},"required":["provider","id"],"description":"The payment behind this checkout, such as the Link spend request that issued a Link card. The checkpoint keeps the first one it receives."},"settlementVerified":{"type":"boolean","enum":[false]}},"required":["id","idempotencyKey","agentId","checkoutMethod","stage","nextAction","amountMinor","currency","purpose","merchant","cart","expiresAt","settlementVerified"]}},"required":["checkpoint"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"409":{"description":"Outcome conflicts with a final result, a different payment reference, or checkpoint state"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkCheckoutCheckpointsByIdOutcome"}},"/api/sdk/checkout-checkpoints/{id}/cancel":{"post":{"tags":["Checkout checkpoints"],"summary":"Cancel an unconfirmed checkout checkpoint","description":"Requires payments:execute. Releases the reserved spend, and withdraws the approval request of a checkpoint waiting for the owner. After confirmation, report an outcome instead.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Current checkout checkpoint; outcomes are caller-reported, not verified settlement","content":{"application/json":{"schema":{"type":"object","properties":{"checkpoint":{"type":"object","properties":{"id":{"type":"string"},"idempotencyKey":{"type":"string"},"agentId":{"type":"string"},"checkoutMethod":{"type":"string","enum":["LINK","CARD","SHOP_PAY","PAYPAL"]},"stage":{"type":"string","enum":["AWAITING_APPROVAL","APPROVED","CONFIRMING","CONFIRMED","PAID","NOT_PAID","OUTCOME_UNKNOWN","DENIED","CANCELLED","EXPIRED"]},"nextAction":{"type":"string","enum":["WAIT_FOR_APPROVAL","CONFIRM_BEFORE_PAYING","PAY_THEN_REPORT_OUTCOME","REPORT_OUTCOME","WAIT","NONE"]},"amountMinor":{"type":"number"},"currency":{"type":"string","enum":["USD"]},"purpose":{"type":"string"},"category":{"type":"string"},"merchant":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"checkoutUrl":{"type":"string"}},"required":["id","name","checkoutUrl"]},"cart":{"type":"object","properties":{"lineItems":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"quantity":{"type":"number"},"unitAmountMinor":{"type":"number"}},"required":["name","quantity","unitAmountMinor"]}},"totals":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"label":{"type":"string"},"amountMinor":{"type":"number"}},"required":["type","label","amountMinor"]}},"fulfillment":{"type":"object","additionalProperties":{"type":"string"}}},"required":["lineItems","totals"]},"expiresAt":{"type":"string"},"approval":{"type":"object","properties":{"requestId":{"type":"string"},"status":{"type":"string","enum":["PENDING","APPROVED","DENIED","EXPIRED","CANCELLED"]},"expiresAt":{"type":"string"}},"required":["requestId","status"]},"outcomeReference":{"type":"string"},"paymentReference":{"type":"object","properties":{"provider":{"type":"string","enum":["LINK"]},"id":{"type":"string","pattern":"^lsrq_[A-Za-z0-9]{1,64}$","description":"Link spend request id, such as lsrq_... An id only: a value that contains a card number is refused."}},"required":["provider","id"],"description":"The payment behind this checkout, such as the Link spend request that issued a Link card. The checkpoint keeps the first one it receives."},"settlementVerified":{"type":"boolean","enum":[false]}},"required":["id","idempotencyKey","agentId","checkoutMethod","stage","nextAction","amountMinor","currency","purpose","merchant","cart","expiresAt","settlementVerified"]}},"required":["checkpoint"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Authentication required"},"409":{"description":"Checkpoint already confirmed; report an outcome instead"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkCheckoutCheckpointsByIdCancel"}},"/api/sdk/purchases":{"post":{"tags":["Conto Commerce agent"],"summary":"Start a purchase","description":"Requires payments:request. Starts a purchase for the agent’s own buyer under an active delegation and returns at once. The purchase continues in the background until it succeeds, ends, or needs someone. The maximum cost can narrow the delegation, never widen it. USD only.","security":[{"sdkKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePurchaseRequest"}}}},"responses":{"200":{"description":"The purchase this idempotency key already created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Purchase"}}}},"201":{"description":"Purchase created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Purchase"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"409":{"description":"Idempotency conflict, purchase in progress, or delegation revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"422":{"description":"Outside the delegation, unsupported currency, wrong card environment, or a payment method choice is needed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"description":"New purchases are paused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}}},"operationId":"postApiSdkPurchases"},"get":{"tags":["Conto Commerce agent"],"summary":"List purchases","description":"Requires transactions:read. The agent’s own purchases, newest first.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","minimum":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string"},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Purchases","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkPurchases"}},"/api/sdk/purchases/{id}":{"get":{"tags":["Conto Commerce agent"],"summary":"Get a purchase","description":"Requires transactions:read. The current snapshot: status, phase, version, the required action and payment evidence. Evidence that is missing is reported as unknown.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Purchase","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Purchase"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkPurchasesById"}},"/api/sdk/purchases/{id}/responses":{"post":{"tags":["Conto Commerce agent"],"summary":"Answer a purchase action","description":"Requires payments:request. Answers an open buyer_details action with the fields it lists. The answer is acknowledged at once and applied in the background. The same answer again returns the same acknowledgment. A different answer conflicts. Review, approval and card verification cannot be answered here.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseResponseRequest"}}}},"responses":{"200":{"description":"The same answer was already accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseResponseAck"}}}},"202":{"description":"Accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseResponseAck"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"description":"This action is completed by the buyer, the cardholder or a reviewer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"409":{"description":"The action is not open, expired, or already has a different answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"422":{"description":"The fields do not match the action’s form","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkPurchasesByIdResponses"}},"/api/sdk/purchases/{id}/events":{"get":{"tags":["Conto Commerce agent"],"summary":"List purchase events","description":"Requires transactions:read. Durable history after a version cursor, oldest first. A cursor ahead of the purchase returns CURSOR_INVALID: read the purchase and resume from its version.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":0},"required":false,"name":"after","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseEventList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"409":{"description":"Cursor ahead of the purchase","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkPurchasesByIdEvents"}},"/api/sdk/purchases/{id}/events/stream":{"get":{"tags":["Conto Commerce agent"],"summary":"Stream purchase events","description":"Requires transactions:read. Server-sent events after a version cursor, from the after query parameter or the Last-Event-ID header. Each event id is its version, so a duplicate after reconnecting is safe to drop. A cursor ahead of the purchase gets a resync event with the current purchase. The stream ends with an end event when the purchase finishes, or after about 50 seconds: reconnect with the last event id.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":0},"required":false,"name":"after","in":"query"}],"responses":{"200":{"description":"Event stream","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkPurchasesByIdEventsStream"}},"/api/sdk/purchases/{id}/cancel":{"post":{"tags":["Conto Commerce agent"],"summary":"Cancel a purchase","description":"Requires payments:request. Before payment the purchase stops. Once payment may have been submitted it stays in reconciliation until its outcome is known. Cancelling never refunds or reverses a payment.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Purchase with cancellationOutcome: cancelled, requested, too_late or already_final","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Purchase"},{"type":"object","properties":{"cancellationOutcome":{"type":"string","enum":["cancelled","requested","too_late","already_final"]}},"required":["cancellationOutcome"]}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkPurchasesByIdCancel"}},"/api/purchasing/buyers":{"post":{"tags":["Conto Commerce"],"summary":"Create a buyer","description":"Requires agents:create. Maps one of your users to a buyer with its own agent, or returns the existing buyer for the same external id. Issue that agent an SDK key with the agent key API.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePurchaseBuyerRequest"}}}},"responses":{"200":{"description":"Existing buyer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseBuyer"}}}},"201":{"description":"Buyer created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseBuyer"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"description":"Agent keys cannot manage buyers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiPurchasingBuyers"},"get":{"tags":["Conto Commerce"],"summary":"List buyers","description":"Requires agents:read.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"integer"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer"},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"Buyers","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseBuyer"}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["items","total","limit","offset"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPurchasingBuyers"}},"/api/purchasing/buyers/{id}":{"get":{"tags":["Conto Commerce"],"summary":"Get a buyer","description":"Requires agents:read.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Buyer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseBuyer"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPurchasingBuyersById"}},"/api/purchasing/buyers/{id}/stop":{"post":{"tags":["Conto Commerce"],"summary":"Stop a buyer","description":"Requires agents:suspend. Stops the buyer’s agent: no new purchases or card credentials, and pending authorizations are revoked. A purchase whose payment may already be submitted stays visible until its outcome is known.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Buyer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseBuyer"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiPurchasingBuyersByIdStop"}},"/api/purchasing/company-cards":{"post":{"tags":["Conto Commerce"],"summary":"Add a company card","description":"Requires wallets:create. One card your organization pays its buyers’ purchases with, under a per-order cap and a monthly cap for all buyers together. Test company cards only for now: they pay Conto test stores. Needs company cards enabled for your organization.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePurchaseCompanyCardRequest"}}}},"responses":{"201":{"description":"Company card","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseCompanyCard"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"description":"Company cards are not enabled, or a live card was requested","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiPurchasingCompanyCards"},"get":{"tags":["Conto Commerce"],"summary":"List company cards","description":"Requires wallets:read. Masked cards only.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"responses":{"200":{"description":"Company cards","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseCompanyCard"}}},"required":["items"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPurchasingCompanyCards"}},"/api/purchasing/company-cards/{id}":{"get":{"tags":["Conto Commerce"],"summary":"Get a company card","description":"Requires wallets:read.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Company card","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseCompanyCard"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPurchasingCompanyCardsById"},"patch":{"tags":["Conto Commerce"],"summary":"Change a company card’s caps","description":"Requires wallets:create. Each buyer’s own limits stay as they are.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePurchaseCompanyCardRequest"}}}},"responses":{"200":{"description":"Company card","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseCompanyCard"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"patchApiPurchasingCompanyCardsById"},"delete":{"tags":["Conto Commerce"],"summary":"Remove a company card","description":"Requires wallets:create. No buyer can start or pay a purchase with the card after this. A purchase whose payment may already be submitted stays visible until its outcome is known.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Company card","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseCompanyCard"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"deleteApiPurchasingCompanyCardsById"}},"/api/purchasing/buyers/{id}/company-card":{"put":{"tags":["Conto Commerce"],"summary":"Let a buyer pay with a company card","description":"Requires wallets:create. The buyer draws from the company card within the per-order, daily and monthly limits you set for them, so one buyer cannot use up the card. Orders at or below reviewAboveMinor go ahead without review. Orders above it wait for your purchase_review answer. Calling it again replaces the limits. The buyer must not have a card of their own.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseBuyerCompanyCardRequest"}}}},"responses":{"200":{"description":"Buyer on the company card","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseBuyerCompanyCard"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"409":{"description":"The buyer has their own card, the buyer is stopped, or the card was removed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"putApiPurchasingBuyersByIdCompanyCard"},"delete":{"tags":["Conto Commerce"],"summary":"Stop a buyer paying with a company card","description":"Requires wallets:create.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"type":"object","properties":{"buyerId":{"type":"string"},"object":{"type":"string","enum":["buyer_company_card"]},"removed":{"type":"boolean","enum":[true]}},"required":["buyerId","object","removed"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"deleteApiPurchasingBuyersByIdCompanyCard"}},"/api/purchasing/buyers/{id}/context":{"put":{"tags":["Conto Commerce"],"summary":"Replace what a buyer has at home","description":"Requires agents:create. Your app’s snapshot of the buyer’s kitchen: inventory with levels, usuals, preferences, the recipes they picked and the list they keep. Conto keeps the latest one, encrypted, for the buyer’s agent. Each call replaces the whole snapshot. It changes no limit, card or purchase. Needs Conto to enable kitchen context for your organization.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PurchaseKitchenContext"},{"type":"object"}]}}}},"responses":{"200":{"description":"The snapshot Conto holds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseBuyerKitchenContext"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"description":"Kitchen context is not enabled for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"409":{"description":"The buyer is stopped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"413":{"description":"The snapshot is over 128 KB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"putApiPurchasingBuyersByIdContext"},"get":{"tags":["Conto Commerce"],"summary":"Read what a buyer has at home","description":"Requires agents:read. context is null when nothing was pushed.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The snapshot Conto holds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseBuyerKitchenContext"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"description":"Kitchen context is not enabled for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPurchasingBuyersByIdContext"},"delete":{"tags":["Conto Commerce"],"summary":"Clear what a buyer has at home","description":"Requires agents:create. Allowed for a stopped buyer too.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Cleared","content":{"application/json":{"schema":{"type":"object","properties":{"buyerId":{"type":"string"},"object":{"type":"string","enum":["buyer_kitchen_context"]},"removed":{"type":"boolean","enum":[true]}},"required":["buyerId","object","removed"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"description":"Kitchen context is not enabled for this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"deleteApiPurchasingBuyersByIdContext"}},"/api/purchasing/payment-methods/setup-sessions":{"post":{"tags":["Conto Commerce"],"summary":"Create a hosted setup link","description":"Requires wallets:create. A single-use link to Conto’s hosted setup page for one buyer, where the buyer sets limits, adds a card and authorizes the agent. A test setup offers a test card that pays Conto test merchants only.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseSetupSessionRequest"}}}},"responses":{"201":{"description":"Link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseHostedLink"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"422":{"description":"Return URL origin not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiPurchasingPaymentMethodsSetupSessions"}},"/api/purchasing/payment-methods":{"get":{"tags":["Conto Commerce"],"summary":"List payment methods","description":"Requires wallets:read. Masked cards only.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"buyerId","in":"query"}],"responses":{"200":{"description":"Payment methods","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PurchasePaymentMethod"}}},"required":["items"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPurchasingPaymentMethods"}},"/api/purchasing/payment-methods/{id}":{"delete":{"tags":["Conto Commerce"],"summary":"Remove a payment method","description":"Requires wallets:create. Removes the card and revokes its delegations. Refused while a purchase uses it.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Removed"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"422":{"description":"A purchase uses this card","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"deleteApiPurchasingPaymentMethodsById"}},"/api/purchasing/delegations":{"get":{"tags":["Conto Commerce"],"summary":"List delegations","description":"Requires wallets:read. Delegations are created by the buyer on the hosted setup page.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"buyerId","in":"query"}],"responses":{"200":{"description":"Delegations","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseDelegation"}}},"required":["items"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPurchasingDelegations"}},"/api/purchasing/delegations/{id}":{"get":{"tags":["Conto Commerce"],"summary":"Get a delegation","description":"Requires wallets:read.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Delegation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseDelegation"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPurchasingDelegationsById"}},"/api/purchasing/delegations/{id}/revoke":{"post":{"tags":["Conto Commerce"],"summary":"Revoke a delegation","description":"Requires wallets:create. New purchases under it are refused, and a purchase that has not requested its card credential is cancelled.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Delegation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseDelegation"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiPurchasingDelegationsByIdRevoke"}},"/api/purchasing/allowances":{"get":{"tags":["Conto Commerce"],"summary":"List allowances","description":"Requires wallets:read. An allowance lets the buyer’s agent buy at one store without the buyer’s review, inside a per-purchase cap and a period cap, until it expires. Only the buyer grants one, while approving a purchase at that store.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"buyerId","in":"query"}],"responses":{"200":{"description":"Allowances","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseAllowance"}}},"required":["items"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPurchasingAllowances"}},"/api/purchasing/allowances/{id}":{"get":{"tags":["Conto Commerce"],"summary":"Get an allowance","description":"Requires wallets:read.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Allowance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseAllowance"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPurchasingAllowancesById"}},"/api/purchasing/allowances/{id}/revoke":{"post":{"tags":["Conto Commerce"],"summary":"Revoke an allowance","description":"Requires wallets:create. Later purchases at the store go to the buyer’s review. A purchase under the allowance that has not requested its card credential stops before it does.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Allowance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseAllowance"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiPurchasingAllowancesByIdRevoke"}},"/api/sdk/recurring-purchases":{"get":{"tags":["Conto Commerce agent"],"summary":"List repeat orders","description":"Requires transactions:read. Only the buyer sets up a repeat order, while approving a purchase on the hosted review page.","security":[{"sdkKeyAuth":[]}],"responses":{"200":{"description":"Repeat orders","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RecurringPurchase"}}},"required":["items"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkRecurringPurchases"}},"/api/sdk/recurring-purchases/{id}":{"get":{"tags":["Conto Commerce agent"],"summary":"Get a repeat order","description":"Requires transactions:read.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Repeat order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringPurchase"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiSdkRecurringPurchasesById"}},"/api/sdk/recurring-purchases/{id}/cycles":{"post":{"tags":["Conto Commerce agent"],"summary":"Start one order of a repeat order","description":"Requires payments:request. Starts one order of the buyer’s repeat order. The same cycle key returns the same order. Conto shops it. When it matches the order, the buyer gets a heads-up and it pays at its payment time unless they skip it. When the items changed or the total is over the price room, it waits for the buyer’s review. Refused while another order is open, before the schedule allows the next one, or while the buyer paused or ended the repeat.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringPurchaseStartCycleRequest"}}}},"responses":{"200":{"description":"The order this cycle key already named","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringPurchaseCycleResult"}}}},"201":{"description":"Order started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringPurchaseCycleResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"409":{"description":"Another order is open, too soon, paused or ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkRecurringPurchasesByIdCycles"}},"/api/sdk/recurring-purchases/{id}/cycles/{cycleKey}/skip":{"post":{"tags":["Conto Commerce agent"],"summary":"Skip one order of a repeat order","description":"Requires payments:request. Skips the order with this cycle key, also before it starts. An order waiting for its payment time closes unpaid.","security":[{"sdkKeyAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"cycleKey","in":"path"}],"responses":{"200":{"description":"Skipped"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"409":{"description":"Already being paid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiSdkRecurringPurchasesByIdCyclesByCycleKeySkip"}},"/api/purchasing/recurring-purchases":{"get":{"tags":["Conto Commerce"],"summary":"List repeat orders","description":"Requires transactions:read. Only the buyer sets up a repeat order, while approving a purchase on the hosted review page.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"buyerId","in":"query"}],"responses":{"200":{"description":"Repeat orders","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RecurringPurchase"}}},"required":["items"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPurchasingRecurringPurchases"}},"/api/purchasing/recurring-purchases/{id}":{"get":{"tags":["Conto Commerce"],"summary":"Get a repeat order","description":"Requires transactions:read.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Repeat order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringPurchase"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPurchasingRecurringPurchasesById"}},"/api/purchasing/recurring-purchases/{id}/cycles":{"post":{"tags":["Conto Commerce"],"summary":"Start one order of a repeat order","description":"Requires transactions:write. Starts one order of the buyer’s repeat order. The same cycle key returns the same order. Conto shops it. When it matches the order, the buyer gets a heads-up and it pays at its payment time unless they skip it. When the items changed or the total is over the price room, it waits for the buyer’s review. Refused while another order is open, before the schedule allows the next one, or while the buyer paused or ended the repeat.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringPurchaseStartCycleRequest"}}}},"responses":{"200":{"description":"The order this cycle key already named","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringPurchaseCycleResult"}}}},"201":{"description":"Order started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringPurchaseCycleResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"409":{"description":"Another order is open, too soon, paused or ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiPurchasingRecurringPurchasesByIdCycles"}},"/api/purchasing/recurring-purchases/{id}/cycles/{cycleKey}/skip":{"post":{"tags":["Conto Commerce"],"summary":"Skip one order of a repeat order","description":"Requires transactions:write. Skips the order with this cycle key, also before it starts. An order waiting for its payment time closes unpaid.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"cycleKey","in":"path"}],"responses":{"200":{"description":"Skipped"},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"409":{"description":"Already being paid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiPurchasingRecurringPurchasesByIdCyclesByCycleKeySkip"}},"/api/purchasing/recurring-purchases/{id}/cancel":{"post":{"tags":["Conto Commerce"],"summary":"Cancel a repeat order","description":"Requires wallets:create. Its allowance and card authorization end, and an order waiting for its payment time closes unpaid.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Repeat order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringPurchase"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiPurchasingRecurringPurchasesByIdCancel"}},"/api/purchasing/purchases":{"post":{"tags":["Conto Commerce"],"summary":"Start a purchase for a buyer","description":"Requires transactions:write. Starts a purchase for one of the organization’s buyers with the organization key, as that buyer’s agent. The buyer’s delegation, review and card verification apply exactly as for an agent key, and the same idempotency key with the same body returns the same purchase. Returns at once.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePurchaseRequest"}}}},"responses":{"200":{"description":"The purchase this idempotency key already created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Purchase"}}}},"201":{"description":"Purchase created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Purchase"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"409":{"description":"Idempotency conflict, purchase in progress, or delegation revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"422":{"description":"Outside the delegation, unsupported currency, wrong card environment, or a payment method choice is needed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"description":"New purchases are paused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}}},"operationId":"postApiPurchasingPurchases"},"get":{"tags":["Conto Commerce"],"summary":"List the organization’s purchases","description":"Requires transactions:read.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"integer"},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer"},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"buyerId","in":"query"}],"responses":{"200":{"description":"Purchases","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPurchasingPurchases"}},"/api/purchasing/purchases/{id}/responses":{"post":{"tags":["Conto Commerce"],"summary":"Answer a purchase action","description":"Requires transactions:write. Answers an open buyer_details action with the organization key, or the purchase_review of a purchase paid with your company card: { decision: \"approve\", totalMinor } with the quote total you saw, or { decision: \"decline\" }. A review answer is applied at once. Other reviews, approvals and card verification cannot be answered here.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseResponseRequest"}}}},"responses":{"200":{"description":"The same answer was already accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseResponseAck"}}}},"202":{"description":"Accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseResponseAck"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"description":"This action is completed by the buyer, the cardholder or a reviewer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"409":{"description":"The action is not open, expired, or already has a different answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"422":{"description":"The fields do not match the action’s form","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiPurchasingPurchasesByIdResponses"}},"/api/purchasing/purchases/{id}/events/stream":{"get":{"tags":["Conto Commerce"],"summary":"Stream a purchase’s events","description":"Requires transactions:read. Same server-sent events and cursor rules as the agent route. Webhooks deliver the same events to a server without holding a connection open.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","minimum":0},"required":false,"name":"after","in":"query"}],"responses":{"200":{"description":"Event stream","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPurchasingPurchasesByIdEventsStream"}},"/api/purchasing/purchases/{id}":{"get":{"tags":["Conto Commerce"],"summary":"Get a purchase","description":"Requires transactions:read.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Purchase","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Purchase"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPurchasingPurchasesById"}},"/api/purchasing/purchases/{id}/events":{"get":{"tags":["Conto Commerce"],"summary":"List a purchase’s events","description":"Requires transactions:read. Same cursor rules as the agent route.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer"},"required":false,"name":"after","in":"query"},{"schema":{"type":"integer"},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseEventList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"409":{"description":"Cursor ahead of the purchase","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPurchasingPurchasesByIdEvents"}},"/api/purchasing/purchases/{id}/cancel":{"post":{"tags":["Conto Commerce"],"summary":"Cancel a purchase","description":"Requires transactions:write. Same rules as the agent route. Never refunds.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Purchase","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Purchase"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiPurchasingPurchasesByIdCancel"}},"/api/purchasing/purchases/{id}/action-sessions":{"post":{"tags":["Conto Commerce"],"summary":"Create a hosted action link","description":"Requires wallets:create. A single-use link that opens the purchase’s buyer actions, such as review and card verification, on Conto’s hosted page for the purchase’s buyer.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseActionSessionRequest"}}}},"responses":{"201":{"description":"Link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseHostedLink"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Not found, or not visible to this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseError"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiPurchasingPurchasesByIdActionSessions"}},"/api/purchasing/settings":{"get":{"tags":["Conto Commerce"],"summary":"Get purchasing settings","description":"Requires settings:read.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchasingSettings"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPurchasingSettings"},"put":{"tags":["Conto Commerce"],"summary":"Update purchasing settings","description":"Requires settings:write. The https origins a hosted page may return buyers to.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchasingSettings"}}}},"responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchasingSettings"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"putApiPurchasingSettings"}},"/api/purchasing/capabilities":{"get":{"tags":["Conto Commerce"],"summary":"Get purchasing capabilities","description":"Requires agents:read. What this organization can run now: currencies, card networks and checkout paths (browser_checkout, store_order, test_store), with a reason for anything unavailable.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"responses":{"200":{"description":"Capabilities"},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiPurchasingCapabilities"}},"/api/api-keys":{"get":{"tags":["API Keys"],"summary":"List organization API keys","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"responses":{"200":{"description":"List of API keys (prefixes only)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiApiKeys"},"post":{"tags":["API Keys"],"summary":"Create organization API key","description":"Create an org-level API key with scoped permissions. The full key is returned only once. Org keys always expire: `expiresInDays` defaults to 365 and is capped at 365. `null` is rejected with `400 VALIDATION_ERROR`.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyRequest"}}}},"responses":{"201":{"description":"API key created. Full key shown only once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyResponse"}}}},"400":{"description":"Validation error"},"403":{"description":"Only owners can create admin keys"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiApiKeys"}},"/api/api-keys/{id}":{"delete":{"tags":["API Keys"],"summary":"Revoke organization API key","description":"Soft-revoke an organization API key. The key remains visible for audit history but can no longer authenticate.","security":[{"sessionAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"API key revoked","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"revokedAt":{"type":"string","format":"date-time"}},"required":["success","revokedAt"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"API key not found"},"409":{"description":"API key already revoked"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"deleteApiApiKeysById"}},"/api/api-keys/{id}/rotate":{"post":{"tags":["API Keys"],"summary":"Rotate organization API key","description":"Create a replacement key with the same scopes, revoke the old key, and link the lifecycle records. The replacement key is returned only once.","security":[{"sessionAuth":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"expiresInDays":{"type":"integer","minimum":1,"maximum":365,"description":"Replacement key lifetime in days, capped at 365. Omit to keep the current expiry. A key with no expiry gets 365 days. null is rejected."},"revocationReason":{"type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"API key rotated. Replacement key shown only once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyResponse"}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"API key not found"},"409":{"description":"API key already revoked or misconfigured"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiApiKeysByIdRotate"}},"/api/transactions":{"get":{"tags":["Transactions"],"summary":"List transactions","description":"List payment transactions for the organization with merchant classification, customer-supplied reconciliation context, wallet and agent references, and network receipt details.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["PENDING","PENDING_APPROVAL","CONFIRMING","CONFIRMED","FAILED","REJECTED","CANCELLED","EXECUTING"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"agentId","in":"query"},{"schema":{"type":"integer","default":50},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"List of transactions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiTransactions"}},"/api/counterparties":{"get":{"tags":["Counterparties"],"summary":"List counterparties","description":"List counterparties (payment recipients) with their trust levels and transaction history. Trust levels: TRUSTED, VERIFIED, UNKNOWN, BLOCKED.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string"},"required":false,"name":"trustLevel","in":"query"},{"schema":{"type":"string"},"required":false,"name":"search","in":"query"}],"responses":{"200":{"description":"List of counterparties","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CounterpartyListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiCounterparties"},"post":{"tags":["Counterparties"],"summary":"Create a counterparty","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCounterpartyRequest"}}}},"responses":{"201":{"description":"Counterparty created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Counterparty"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"postApiCounterparties"}},"/api/alerts":{"get":{"tags":["Alerts"],"summary":"List alerts","description":"List customer-visible alerts and notifications for the organization.","security":[{"sessionAuth":[]},{"orgApiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["open","in_review","resolved","dismissed"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","enum":["low","medium","high"]},"required":false,"name":"severity","in":"query"},{"schema":{"type":"string"},"required":false,"name":"alertType","in":"query"},{"schema":{"type":"string"},"required":false,"name":"agentId","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","minimum":0,"default":0},"required":false,"name":"offset","in":"query"}],"responses":{"200":{"description":"List of alerts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiAlerts"}},"/api/chains":{"get":{"tags":["Chains"],"summary":"List supported chains","description":"List the chains and stablecoins Conto supports, with the default chain ID. No authentication required.","security":[],"parameters":[{"schema":{"type":"string","enum":["true","false"],"description":"Return only testnets (`true`) or only mainnets (`false`)."},"required":false,"name":"testnet","in":"query"},{"schema":{"$ref":"#/components/schemas/ChainType"},"required":false,"name":"type","in":"query"}],"responses":{"200":{"description":"Supported chains","content":{"application/json":{"schema":{"type":"object","properties":{"chains":{"type":"array","items":{"$ref":"#/components/schemas/SupportedChain"}},"defaultChainId":{"type":"string"}},"required":["chains","defaultChainId"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"500":{"$ref":"#/components/responses/InternalServerError"}},"operationId":"getApiChains"}}},"webhooks":{}}