agentcard

{'type': 'object', 'required': ['amount_cents'], 'properties': {'amount_cents': {'type': 'number', 'description': 'Amount to add in cents (e.g. 5000 = $50.00). Typical range: $20.00 to $10,000.00 (2000 to 1000000 cents); the exact range depends on the active funding provider and is returned by the API when the amount is invalid.'}, 'payment_method': {'enum': ['apple_pay', 'google_pay'], 'type': 'string', 'description': 'Payment method for the checkout: apple_pay or google_pay. Ask the user which one their device has; apple_pay only when unknown.'}}}

{'type': 'object', 'required': ['message'], 'properties': {'message': {'type': 'string', 'description': 'Human-readable result or next step.'}, 'amountUsd': {'type': 'string', 'description': 'Amount of the created checkout in USD.'}, 'checkoutUrl': {'type': 'string', 'description': 'Single-use payment link to hand the user verbatim (present when a checkout was created).'}}}

{'type': 'object', 'required': ['pattern'], 'properties': {'card_id': {'type': 'string', 'description': 'Card id (from list_cards).'}, 'pattern': {'type': 'string', 'description': 'Merchant name pattern to remember, e.g. "STARBUCKS" or "ODD CAFE".'}}}

{'type': 'object', 'required': ['message'], 'properties': {'scope': {'type': 'string'}, 'preset': {'type': ['object', 'null'], 'properties': {'id': {'type': 'string'}, 'name': {'type': ['string', 'null']}, 'summary': {'type': 'string'}, 'version': {'type': 'number'}}}, 'message': {'type': 'string'}, 'pattern': {'type': 'string'}, 'summary': {'type': 'string'}, 'messages': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Card scope: where the remember is enforced.'}, 'needsNewCard': {'type': 'boolean', 'description': 'Card scope: true when the card keeps a network category allowlist the remember cannot widen.'}, 'policyVersion': {'type': 'number'}}}

{'type': 'object', 'required': ['approval_id', 'decision', 'action', 'resource_id'], 'properties': {'action': {'enum': ['card_details', 'transaction', 'cross_app:details', 'cross_app:close', 'cross_app:pause', 'cross_app:resume', 'cross_app:update'], 'type': 'string', 'description': 'The original action type from the approval prompt (list_pending_approvals rows carry it as action).'}, 'decision': {'enum': ['approved', 'denied'], 'type': 'string', 'description': 'Whether to approve or deny the request'}, 'approval_id': {'type': 'string', 'description': 'The approval request ID'}, 'resource_id': {'type': 'string', 'description': 'Card ID (for card_details and cross_app actions) or approval ID (for transaction)'}}}

{'type': 'object', 'required': ['message'], 'properties': {'card': {'type': 'object', 'properties': {'id': {'type': 'string', 'description': 'Card ID.'}, 'last4': {'type': 'string', 'description': 'Last 4 digits of the card number.'}, 'expiry': {'type': 'string', 'description': 'Card expiry date.'}, 'status': {'type': 'string', 'description': 'Card status.'}, 'balanceCents': {'type': 'number', 'description': 'Card balance in cents.'}}, 'description': 'The card resource returned by the approved follow-up action, when applicable.'}, 'action': {'type': 'string', 'description': "The original action type from the approval prompt: 'card_details' or 'transaction'."}, 'status': {'type': 'string', 'description': "Outcome of the request: 'denied', 'card_details', 'card_created', 'resolved' (cross_app approvals: consent recorded, the requesting app completes the action), 'personal_surface_only' (company-connected session; the user resolves personally), or 'unknown_action'."}, 'message': {'type': 'string', 'description': 'Human-readable summary of the approval outcome and any follow-up action.'}, 'decision': {'type': 'string', 'description': "The decision that was applied: 'approved' or 'denied'."}}}

{'type': 'object', 'required': ['request'], 'properties': {'request': {'type': 'string', 'description': 'The natural-language ask or follow-up, e.g. "order a caesar salad from Zuni on DoorDash", "deliver to 123 Main St", or "yes, place the order".'}, 'new_order': {'type': 'boolean', 'description': 'Start a fresh shopping conversation instead of continuing the current one. Use when beginning an unrelated order (ignores any conversation_id).'}, 'conversation_id': {'type': 'string', 'description': 'The conversation_id returned by a previous buy call. Pass it to continue the SAME order (keeps the cart + confirmation). Omit to start a new order.'}}}

{'type': 'object', 'required': ['message'], 'properties': {'status': {'enum': ['assistant_turn', 'conversation_start_failed', 'request_failed'], 'type': 'string', 'description': "Discriminator for the outcome. 'assistant_turn' when the buy loop replied; 'conversation_start_failed' or 'request_failed' on errors."}, 'message': {'type': 'string', 'description': "The assistant's conversational turn (it may ask for the delivery address, show the cart + total, confirm, or report a placed order), or an error explanation."}, 'messages': {'type': 'array', 'items': {'type': 'string'}, 'description': 'The same turn split into ordered messages for multi-bubble surfaces (each narration segment, then the final reply/confirmation). `message` is the same content consolidated; clients that show one bubble should use `message` and ignore this.'}, 'conversation_id': {'type': 'string', 'description': 'The conversation id to thread back as conversation_id on the next buy call to continue the SAME order. Present on a successful assistant turn.'}}}

{'type': 'object', 'required': ['merchant'], 'properties': {'merchant': {'type': 'string', 'description': 'merchant slug (e.g. doordash)'}}}

{'type': 'object', 'required': ['message'], 'properties': {'status': {'type': 'string', 'description': "Outcome: 'pending' (hosted login started), 'ready'/'linked' (auto-link merchant â\x80\x94 no login needed), or 'error'."}, 'message': {'type': 'string', 'description': 'Human-readable next step.'}, 'loginUrl': {'type': 'string', 'description': 'URL the user must open to log in to the merchant. Absent for auto-link merchants.'}, 'merchant': {'type': 'string', 'description': 'The merchant slug, present when an auto-link merchant needs no login.'}, 'pendingId': {'type': 'string', 'description': 'Session id to pass to buy_connect_status. Absent for auto-link merchants.'}}}

{'type': 'object', 'required': ['merchant', 'pending_id'], 'properties': {'merchant': {'type': 'string', 'description': 'merchant slug (e.g. doordash)'}, 'pending_id': {'type': 'string', 'description': 'The pending_id returned by buy_connect.'}}}

{'type': 'object', 'required': ['message'], 'properties': {'status': {'type': 'string', 'description': "Connect state: 'linking', 'linked', 'expired', or 'error'."}, 'message': {'type': 'string', 'description': 'Human-readable status / next step.'}, 'merchant': {'type': 'string', 'description': 'The merchant slug, present when linked.'}, 'cart_carried_over': {'type': 'boolean', 'description': 'True when a cart built anonymously before linking was moved onto the linked account â\x80\x94 re-show it (buy_view_cart) and re-confirm the total before checkout.'}}}

{'type': 'object', 'required': [], 'properties': {}}

{'type': 'object', 'required': ['message'], 'properties': {'count': {'type': 'number', 'description': 'Number of merchants returned.'}, 'status': {'type': 'string', 'description': "Outcome: 'ok', 'empty', or 'error'."}, 'message': {'type': 'string', 'description': 'Human-readable merchant list (or an error / empty note).'}, 'merchants': {'type': 'array', 'items': {'type': 'object', 'properties': {'name': {'type': 'string', 'description': 'Merchant display name.'}, 'slug': {'type': 'string', 'description': 'Merchant slug identifier.'}, 'link_status': {'type': 'string', 'description': "'ready' (no account needed) or 'linked' (account linked): shop now. 'unlinked': no account linked yet. 'pending': a link was started and not finished. 'error': the last link attempt failed."}}}, 'description': "Available commerce merchants and this user's link status for each."}}}

{'type': 'object', 'required': ['merchant'], 'properties': {'merchant': {'type': 'string', 'description': 'Merchant slug to disconnect (e.g. doordash).'}}}

{'type': 'object', 'required': ['message'], 'properties': {'status': {'type': 'string', 'description': "Outcome: 'unlinked', 'not_linked', or 'error'."}, 'message': {'type': 'string', 'description': 'Human-readable unlink outcome.'}, 'merchant': {'type': 'string', 'description': 'The merchant slug that was unlinked (or attempted).'}}}

{'type': 'object', 'required': [], 'properties': {}}

{'type': 'object', 'required': ['message'], 'properties': {'message': {'type': 'string'}, 'nextStep': {'type': ['string', 'null']}, 'uploadUrl': {'type': 'string'}, 'missingFields': {'type': 'array', 'items': {'type': 'string'}}, 'verificationUrl': {'type': 'string'}}}

{'type': 'object', 'required': ['card_id'], 'properties': {'card_id': {'type': 'string', 'description': 'The card ID to close'}, 'approval_id': {'type': 'string', 'description': 'Approval id from a prior approval_required response, once the user has approved. Only for cards created through ANOTHER app: first call without it (the user is emailed an approve link), then retry with it.'}, 'confirm_rewards_card': {'type': 'boolean', 'description': 'Required to close the rewards card. Only set after the user explicitly confirms; never set it preemptively.'}}}

{'type': 'object', 'required': ['message'], 'properties': {'cardId': {'type': 'string', 'description': 'The ID of the card that was closed.'}, 'status': {'type': 'string', 'description': 'Outcome discriminator; always "closed" on success.'}, 'message': {'type': 'string', 'description': 'Human-readable confirmation that the card was closed.'}, 'approvalId': {'type': 'string', 'description': 'Present when status is approval_required: pass it back as approval_id after the user approves.'}}}

{'type': 'object', 'required': ['amount_cents'], 'properties': {'type': {'enum': ['single_use', 'multi_use'], 'type': 'string', 'description': "Card behavior. 'single_use' (default) closes after its first approved charge â\x80\x94 right for one-off purchases. 'multi_use' stays open across charges until its total limit is spent â\x80\x94 right for subscriptions and recurring merchants. Multi-use cards can be paused (pause_card), resumed (resume_card), and resized (update_card_limit)."}, 'preset': {'oneOf': [{'type': 'string'}, {'type': 'object', 'required': ['privileges'], 'properties': {'name': {'type': 'string'}, 'privileges': {'type': 'array', 'items': {}}}}], 'description': 'Preset for this card: a template name (ai_labs, weekday_meals, cli_only, daily), comma-separated templates, a saved preset name/id, inline JSON privileges, or { name?, privileges }. Adds restrictions only â\x80\x94 omit for a normal unrestricted card.'}, 'source': {'enum': ['issued'], 'type': 'string', 'description': "Force the card to be funded from the user's cash balance (the issued path: KYC + wallet funding) even when they have an added or vaulted card or would otherwise be offered the vault. Use it only after the user explicitly picks the balance option. Omit for the default (an active added card wins; first-time users get the vault link)."}, 'expires_at': {'type': 'string', 'description': 'Optional hard expiry for a multi-use card (ISO-8601 with timezone, e.g. "2027-01-01T00:00:00Z"). Must be in the future, at most 365 days out. The card closes automatically when it passes.'}, 'amount_cents': {'type': 'number', 'description': 'Card funding amount in CENTS, not dollars (minimum 100). 100 = $1.00 and 2500 = $25.00 â\x80\x94 a value like 25 would be $0.25. Company-governed connections have no maximum; personal accounts are capped by their plan â\x80\x94 call get_plan for the limits in effect.'}, 'funds_source': {'enum': ['onramp_flow', 'company_flow'], 'type': 'string', 'description': "Where the card funds come from. OMIT unless instructed: the server applies the right default (company-connected accounts use the company wallet automatically when the company enables it). company_flow = the company's wallet funds the card; onramp_flow = the user's own wallet."}, 'purchase_key': {'type': 'string', 'description': 'The purchaseKey from the same approval_pending answer as pending_card_id; the pair proves the retry is for that purchase.'}, 'scope_preset': {'enum': ['ai_labs'], 'type': 'string', 'description': "Silent alias for preset 'ai_labs': a multi-use card restricted to AI-lab merchants (OpenAI, Anthropic, Gemini); charges anywhere else are declined at authorization. AI cards earn boosted tokenback on eligible spend. Implies type 'multi_use'. Prefer `preset`."}, 'restart_setup': {'type': 'boolean', 'description': 'Set true ONLY when the user lost or never received a vault link, it expired (about 15 minutes), or they want to add ANOTHER card. Never needed on the first call or for normal retries. amount_cents is still required on this call (the link itself carries no amount).'}, 'pending_card_id': {'type': 'string', 'description': 'Only when retrying an approval_pending purchase whose preset has since changed: the cardId from that earlier answer, together with purchase_key. The older approval link is retired once the replacement is minted. Never pass it for a different purchase.'}, 'connected_card_id': {'type': 'string', 'description': "Multi-card: issue against a SPECIFIC added card (an id from the user's added cards, see list_added_cards) instead of the newest active one. Omit for the default."}}}

{'type': 'object', 'required': ['message'], 'properties': {'last4': {'type': 'string', 'description': 'Last four digits of the new card. Present only when status is "created".'}, 'cardId': {'type': 'string', 'description': 'The new card ID. Present only when status is "created".'}, 'expiry': {'type': 'string', 'description': 'Card expiry (MM/YY). Present only when status is "created".'}, 'preset': {'type': ['object', 'null'], 'properties': {'id': {'type': 'string'}, 'name': {'type': ['string', 'null']}, 'summary': {'type': 'string'}, 'version': {'type': 'number'}}, 'description': 'Preset summary for the new card, or null when unrestricted. Present when status is "created".'}, 'reason': {'type': 'string', 'description': 'On "issuing_suggested" (legacy servers only; current servers route every first-time user to the vault instead): why the card could not be added. On "kyc_required": why the previous identity-verification attempt failed (e.g. "document_unverified_other"), present only when a prior attempt was rejected.'}, 'source': {'type': 'string', 'description': '"connected" when the card was created against the user\'s added card. Absent for wallet-funded cards.'}, 'status': {'type': 'string', 'description': 'Outcome discriminator: "created" (card issued), "vault_started" (first-time setup: send vaultUrl to the user; once their card is in the vault, purchases go through buy, not create_card), "vault_ready" (the user\'s own card is already in their vault: use buy; only source "issued" produces a card number), "attach_started" / "attach_pending" (an older add-card enrollment still in flight: send attachUrl or wait, then call again with the same arguments), "issuing_suggested" (legacy servers only: offer the balance-funded fallback, noting it requires KYC, and only then call again with source "issued"), "approval_required" (human approval needed), "approval_pending" (added-card passkey approval: send approvalUrl to the user, then retry with the same arguments in ~10s), "kyc_required" (issued path only), "user_info_required" (check missingFields: phone/terms go through submit_user_info; consent must be recorded by the connecting platform), "beta_capacity_reached", "issuing_balance_insufficient" (issued path only), "payment_method_declined", "limit_reached", "funding_in_progress" (company wallet funding underway: retry with the same arguments in ~10s), "funding_not_approved", "org_wallet_funding_required", "org_wallet_unavailable" (the company wallet backing this account is not active: the company must finish setup; do not retry immediately), "rate_limited" (wait ~1 minute, then retry), "issuer_daily_limit" (the issuing rail\'s daily card budget is spent: retry in about an hour, never in a loop), "issuer_capacity" / "wallet_balance_unavailable" (the rail is briefly unavailable: retry shortly). A refusal this build does not model relays the backend\'s own code here with its message.'}, 'message': {'type': 'string', 'description': 'Human-readable result or guidance for the next step.'}, 'vaultUrl': {'type': 'string', 'description': 'The secure link the user opens to put their card in their vault. Present only when status is "vault_started".'}, 'attachUrl': {'type': 'string', 'description': 'The secure link the user opens to finish an older add-card enrollment. Present only when status is "attach_started".'}, 'expiresAt': {'type': 'string', 'description': 'When the link expires (ISO 8601). Present when status is "vault_started" or "attach_started".'}, 'approvalId': {'type': 'string', 'description': 'The approval request ID to pass to approve_request. Present only when status is "approval_required".'}, 'cardStatus': {'type': 'string', 'description': 'Card status, e.g. "active". Present only when status is "created".'}, 'vaultCards': {'type': 'number', 'description': 'How many cards the user already holds in their vault. Present only when status is "vault_ready".'}, 'approvalUrl': {'type': 'string', 'description': 'The passkey approval link to send to the user. Present only when status is "approval_pending".'}, 'purchaseKey': {'type': 'string', 'description': 'The purchase\'s key. Present only when status is "approval_pending"; pass it back as purchase_key with pending_card_id.'}, 'balanceCents': {'type': 'number', 'description': 'Card balance in cents. Present only when status is "created".'}, 'missingFields': {'type': 'array', 'items': {'type': 'string'}, 'description': 'What is missing when status is "user_info_required" (e.g. "termsAccepted", "consent").'}, 'pendingCardId': {'type': 'string', 'description': 'The parked card awaiting the passkey. Present only when status is "approval_pending"; pass it back as pending_card_id on the retry, with purchaseKey as purchase_key.'}, 'balanceDollars': {'type': 'string', 'description': 'Card balance formatted as USD dollars, e.g. "12.50". Present only when status is "created".'}, 'maxAmountCents': {'type': 'number', 'description': 'The issuing rail\'s per-card ceiling in cents. Present when status is "limit_reached" because the amount exceeded that ceiling; retry with amount_cents at most this value.'}}}

{'type': 'object', 'required': ['name'], 'properties': {'name': {'type': 'string', 'description': 'The saved preset name to delete.'}}}

{'type': 'object', 'required': ['message'], 'properties': {'deleted': {'type': 'boolean'}, 'message': {'type': 'string'}}}

{'type': 'object', 'required': [], 'properties': {}}

{'type': 'object', 'required': ['message'], 'properties': {'status': {'type': 'string', 'description': 'Balance account status.'}, 'message': {'type': 'string', 'description': 'Human-readable balance summary.'}, 'balanceUsd': {'type': 'string', 'description': 'Spendable cash balance in USD (string decimal).'}, 'confirmingUsd': {'type': 'string', 'description': 'Deposit clearing on-chain, not yet spendable (present only mid-deposit).'}}}

{'type': 'object', 'required': ['card_id'], 'properties': {'card_id': {'type': 'string', 'description': 'The card ID'}}}

{'type': 'object', 'required': ['message'], 'properties': {'cached': {'type': 'boolean', 'description': 'Whether the balance was served from a short-lived cache rather than fetched live.'}, 'message': {'type': 'string', 'description': 'Human-readable balance summary.'}, 'balanceCents': {'type': 'number', 'description': 'Available balance in cents.'}, 'balanceDollars': {'type': 'string', 'description': 'Available balance formatted as USD dollars, e.g. "12.50".'}}}

{'type': 'object', 'required': ['card_id'], 'properties': {'card_id': {'type': 'string', 'description': 'The card ID'}, 'approval_id': {'type': 'string', 'description': 'Approval id from a prior approval_required response, once the user has approved. Only for cards created through ANOTHER app: first call without it (the user is emailed an approve link), then retry with it.'}}}

{'type': 'object', 'required': ['message'], 'properties': {'last4': {'type': 'string', 'description': 'Last four digits of the card number. Present only when status is "details".'}, 'cardId': {'type': 'string', 'description': 'The card ID.'}, 'expiry': {'type': 'string', 'description': 'Card expiry (MM/YY). Present only when status is "details".'}, 'status': {'type': 'string', 'description': 'Outcome discriminator: "details" when credentials were returned, "approval_required" when human approval is needed first, "not_accessible" when the card exists outside this connection\'s scope, "policy_denied" when the card preset blocks reveal (message is the deny reason), "managed_by_organization" for org-issued read-only cards.'}, 'message': {'type': 'string', 'description': 'Human-readable card details (or an approval-required prompt).'}, 'approvalId': {'type': 'string', 'description': 'The approval request ID to pass to approve_request. Present only when status is "approval_required".'}, 'cardStatus': {'type': 'string', 'description': 'Card status, e.g. "active" or "closed". Present only when status is "details".'}, 'balanceCents': {'type': 'number', 'description': 'Card balance in cents. Present only when status is "details".'}, 'balanceDollars': {'type': 'string', 'description': 'Card balance formatted as USD dollars, e.g. "12.50". Present only when status is "details".'}}}

{'type': 'object', 'required': ['card_id'], 'properties': {'card_id': {'type': 'string', 'description': 'The card id (from list_cards).'}}}

{'type': 'object', 'required': ['message'], 'properties': {'cardId': {'type': 'string'}, 'preset': {'type': ['object', 'null'], 'properties': {'id': {'type': 'string'}, 'name': {'type': ['string', 'null']}, 'summary': {'type': 'string'}, 'version': {'type': 'number'}}, 'description': 'Preset summary, or null when unrestricted.'}, 'message': {'type': 'string'}}}

{'type': 'object', 'required': [], 'properties': {}}

{'type': 'object', 'required': ['message'], 'properties': {'message': {'type': 'string', 'description': 'The latest buy usage guide / instructions text.'}}}

{'type': 'object', 'required': [], 'properties': {}}

{'type': 'object', 'required': ['message'], 'properties': {'reason': {'type': ['string', 'null'], 'description': 'Failure reason from the verification provider when one exists.'}, 'status': {'type': ['string', 'null'], 'description': 'Raw KYC state: "verified", "pending", "requires_input", "duplicate_identity", "canceled", or null if never started.'}, 'message': {'type': 'string', 'description': 'Human-readable status / next step.'}, 'nextStep': {'type': ['string', 'null'], 'description': 'Conversational next step when the flow is in progress.'}, 'verified': {'type': 'boolean', 'description': 'True when identity verification has passed.'}, 'missingFields': {'type': 'array', 'items': {'type': 'string'}}, 'verificationUrl': {'type': 'string'}}}

{'type': 'object', 'required': [], 'properties': {}}

{'type': 'object', 'required': ['message'], 'properties': {'plan': {'type': 'string', 'description': "Raw plan id, e.g. 'free', 'basic', or 'pro'."}, 'message': {'type': 'string', 'description': 'Human-readable plan + usage summary.'}, 'planName': {'type': 'string', 'description': 'Display label of the plan, e.g. "Basic ($15/mo)".'}, 'ordersPlaced': {'type': 'number', 'description': 'Orders placed (counts toward the free-order quota on Free).'}, 'cardsRemaining': {'type': ['number', 'null'], 'description': 'Cards remaining this month; null means unlimited.'}, 'cardsThisMonth': {'type': 'number', 'description': 'Number of cards created this month.'}, 'currentPeriodEnd': {'type': ['string', 'null'], 'description': 'ISO date the current billing period ends, or null.'}, 'maxCardsPerMonth': {'type': ['number', 'null'], 'description': 'Max cards allowed per month; null means unlimited (connections through a company OAuth client or organization have no card limits).'}, 'cancelAtPeriodEnd': {'type': 'boolean', 'description': 'Whether the subscription cancels at the end of the current billing period.'}, 'maxLifetimeOrders': {'type': ['number', 'null'], 'description': 'Lifetime free-order quota; null means unlimited (paid plans).'}, 'maxCardAmountCents': {'type': ['number', 'null'], 'description': "The per-card cap in effect, in cents: the tighter of the plan cap and the issuing rail's own ceiling; null means no per-card cap at all."}, 'subscriptionStatus': {'type': ['string', 'null'], 'description': "Stripe subscription status (e.g. 'active', 'past_due'), or null on Free / when unavailable."}, 'activeMultiUseCards': {'type': 'number', 'description': 'How many multi-use cards the user currently holds open (they hold their limit as collateral for their whole life, so closing one frees a slot).'}, 'maxCardAmountDollars': {'type': ['string', 'null'], 'description': 'The per-card cap in effect, formatted as USD dollars, e.g. "500.00"; null means no per-card cap.'}, 'maxActiveMultiUseCards': {'type': ['number', 'null'], 'description': 'How many multi-use cards may be open at once. 0 means multi-use cards need a paid plan and create_card with type "multi_use" will be refused; null means unlimited (company-governed).'}, 'planMaxCardAmountCents': {'type': ['number', 'null'], 'description': "The personal plan's per-card cap, in cents; null for company-governed connections (no plan cap)."}, 'railMaxCardAmountCents': {'type': ['number', 'null'], 'description': 'The issuing rail\'s own per-card ceiling for cards funded from the cash balance (source "issued"), in cents, when the rail this account mints on has one; enforced when such a card is created, not on purchases against the user\'s own added card. null when the rail has none.'}}}

{'type': 'object', 'properties': {}}

{'type': 'object', 'required': ['message'], 'properties': {'message': {'type': 'string', 'description': 'Human-readable summary.'}, 'balanceTokens': {'type': 'number', 'description': 'Current token balance (1 token = 1 cent).'}, 'redeemedTokens': {'type': 'number', 'description': 'Tokens redeemed all-time.'}, 'minRedeemTokens': {'type': 'number', 'description': 'Minimum tokens per redemption.'}, 'lifetimeEarnedTokens': {'type': 'number', 'description': 'Tokens earned all-time.'}}}

{'type': 'object', 'required': [], 'properties': {}}

{'type': 'object', 'required': ['message'], 'properties': {'message': {'type': 'string', 'description': 'Human-readable settings summary.'}, 'authorization': {'type': 'object', 'description': 'Authorization (approval) settings â\x80\x94 read-only.'}, 'notifications': {'type': 'object', 'description': 'Email notification preferences.'}, 'default_payment': {'type': ['object', 'null'], 'description': "The wallet-level default payment source: { source: 'balance' } or { source: 'connected', connected_card_id }. null = auto (an active added card wins, else the balance)."}, 'delivery_address': {'type': ['object', 'null'], 'description': 'The wallet-level default delivery address (street/city/state/zip + optional address2/phone/name), or null when unset.'}}}

{'type': 'object', 'required': [], 'properties': {'purpose': {'enum': ['wallet', 'add_card'], 'type': 'string', 'description': '"wallet" (default) opens the hosted wallet. "add_card" opens the vault card form so the user can put their own card on file; single-use, about 15 minutes.'}, 'merchant': {'type': 'string', 'description': 'Merchant name shown on the payment-approval sheet (with amount_cents).'}, 'amount_cents': {'type': 'integer', 'minimum': 1, 'description': 'Amount in cents. When present, the link opens on the payment-approval sheet for this charge.'}}}

{'type': 'object', 'required': ['message'], 'properties': {'url': {'type': 'string', 'description': 'The hosted wallet URL to share with the user.'}, 'kind': {'type': 'string', 'description': 'purpose add_card only: how the vault link signs the user in. "connected" = a one-time code to their own phone or email; "handoff" = directly; "open" = passkey setup or passkey sign-in.'}, 'message': {'type': 'string', 'description': 'Ready-to-send sentence containing the URL.'}, 'sandbox': {'type': 'boolean', 'description': 'True when the connection is in test mode.'}, 'expiresAt': {'type': 'string', 'description': 'ISO time the link stops working.'}}}

{'type': 'object', 'required': [], 'properties': {'code': {'type': 'string', 'description': 'Step 2: the one-time code the user received.'}, 'type': {'enum': ['email', 'phone'], 'type': 'string', 'description': 'Step 1: which kind of identifier the OTHER account uses.'}, 'ticket': {'type': 'string', 'description': 'Step 2: the ticket returned by step 1.'}, 'identifier': {'type': 'string', 'description': 'Step 1: the email address or phone number of the other account to verify.'}}}

{'type': 'object', 'required': ['message'], 'properties': {'message': {'type': 'string', 'description': 'Human-readable result or next step.'}}}

{'type': 'object', 'required': [], 'properties': {}}

{'type': 'object', 'required': ['message'], 'properties': {'count': {'type': 'number', 'description': 'Number of non-revoked added cards.'}, 'message': {'type': 'string', 'description': 'Human-readable list (or an empty-state note).'}, 'attachedCards': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string', 'description': 'Id of the added card (pass to create_card connected_card_id or remove_added_card).'}, 'brand': {'type': ['string', 'null'], 'description': 'Card brand.'}, 'label': {'type': 'string', 'description': "Display name every surface shares: the nickname when set, else 'Bancorp Visa â\x80¢â\x80¢â\x80¢â\x80¢ 6830'."}, 'last4': {'type': ['string', 'null'], 'description': 'Last four digits.'}, 'issuer': {'type': ['string', 'null'], 'description': "Issuing bank, statement-style ('Bancorp', 'Chase'). Null when BIN data lacked it."}, 'status': {'type': 'string', 'description': 'pending | active | ineligible.'}, 'nickname': {'type': ['string', 'null'], 'description': 'User-set name for the card, when they gave it one.'}, 'isDefault': {'type': 'boolean', 'description': 'Whether create_card uses this one when no connected_card_id is given.'}, 'statusDetail': {'type': 'string', 'description': 'Ineligible rows only: why the card could not be added, in user-ready copy.'}}}, 'description': 'Added-card enrollments, newest first. The row with isDefault true is the default for new cards; none is marked when the default payment is the wallet balance.'}}}

{'type': 'object', 'required': [], 'properties': {}}

{'type': 'object', 'required': ['message'], 'properties': {'cards': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string', 'description': 'Card ID.'}, 'last4': {'type': 'string', 'description': 'Last four digits of the card number.'}, 'expiry': {'type': 'string', 'description': 'Card expiry (MM/YY).'}, 'preset': {'type': ['object', 'null'], 'properties': {'id': {'type': 'string'}, 'name': {'type': ['string', 'null']}, 'summary': {'type': 'string'}, 'version': {'type': 'number'}}, 'description': 'Preset summary when the card has restrictions; omit or null when unrestricted.'}, 'status': {'type': 'string', 'description': 'Card status, e.g. "active" or "closed".'}, 'sandbox': {'type': 'boolean', 'description': 'Whether this is a test/sandbox card.'}, 'balanceCents': {'type': 'number', 'description': 'Card balance in cents.'}, 'spendLimitCents': {'type': 'number', 'description': 'Per-card spend limit in cents.'}}}, 'description': "The user's own virtual cards."}, 'count': {'type': 'number', 'description': "Total number of cards across the user's own cards and any connected-account cards."}, 'wallet': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string', 'description': 'Card ID.'}, 'last4': {'type': 'string', 'description': 'Last four digits of the card number.'}, 'access': {'enum': ['owned', 'connected'], 'type': 'string', 'description': 'Whether THIS session can manage the card (owned) or only see it (connected = read-only here).'}, 'expiry': {'type': 'string', 'description': 'Card expiry (MM/YY).'}, 'preset': {'type': ['object', 'null'], 'properties': {'id': {'type': 'string'}, 'name': {'type': ['string', 'null']}, 'summary': {'type': 'string'}, 'version': {'type': 'number'}}, 'description': 'Preset summary when present.'}, 'source': {'type': 'object', 'properties': {'app': {'type': ['string', 'null'], 'description': 'OAuth client id of the app that created the card (null for first-party surfaces).'}, 'kind': {'enum': ['personal', 'company'], 'type': 'string', 'description': "personal = created on the user's own account; company = created under a company the user is connected to."}, 'appName': {'type': ['string', 'null'], 'description': 'Display name of the issuing app (null when unknown or first-party).'}, 'companyId': {'type': 'string', 'description': 'Company id (company cards only).'}, 'companyName': {'type': 'string', 'description': 'Company name (company cards only).'}}, 'description': 'Where this card came from.'}, 'status': {'type': 'string', 'description': 'Card status.'}, 'sandbox': {'type': 'boolean', 'description': 'Whether this is a test card.'}, 'balanceCents': {'type': 'number', 'description': 'Card balance in cents.'}, 'spendLimitCents': {'type': 'number', 'description': 'Per-card spend limit in cents.'}}}, 'description': 'One-wallet view (present when the shared wallet is enabled): every LIVE card across personal and company sources, each tagged with its provenance. Closed cards are excluded; transactions carry history.'}, 'message': {'type': 'string', 'description': 'Human-readable list of cards (or an empty-state message).'}, 'vaultCards': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string', 'description': 'Vault card ID.'}, 'brand': {'type': ['string', 'null'], 'description': 'Card brand, e.g. "visa".'}, 'label': {'type': ['string', 'null'], 'description': "The user's nickname for the card, if any."}, 'last4': {'type': ['string', 'null'], 'description': 'Last four digits.'}, 'expiry': {'type': ['string', 'null'], 'description': 'Card expiry (MM/YY).'}}}, 'description': "The user's own cards stored in their Agentcard vault. Display fields only; they pay through buy with an approval on the user's device (their passkey or master password) and never expose a card number."}, 'connectedAccounts': {'type': 'array', 'items': {'type': 'object', 'properties': {'cards': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string', 'description': 'Card ID.'}, 'last4': {'type': 'string', 'description': 'Last four digits of the card number.'}, 'expiry': {'type': 'string', 'description': 'Card expiry (MM/YY).'}, 'preset': {'type': ['object', 'null'], 'properties': {'id': {'type': 'string'}, 'name': {'type': ['string', 'null']}, 'summary': {'type': 'string'}, 'version': {'type': 'number'}}, 'description': 'Preset summary when present.'}, 'status': {'type': 'string', 'description': 'Card status, e.g. "active" or "closed".'}, 'sandbox': {'type': 'boolean', 'description': 'Whether this is a test/sandbox card.'}, 'balanceCents': {'type': 'number', 'description': 'Card balance in cents.'}, 'spendLimitCents': {'type': 'number', 'description': 'Per-card spend limit in cents.'}}}, 'description': 'Cards issued under this connected account.'}, 'readOnly': {'type': 'boolean', 'description': 'Whether these cards are read-only for the user.'}, 'cardholderId': {'type': 'string', 'description': "The user's cardholder ID within the organization."}, 'organizationId': {'type': 'string', 'description': 'ID of the organization that owns these cards.'}, 'organizationName': {'type': 'string', 'description': 'Name of the organization that owns these cards.'}}}, 'description': 'Read-only cards issued and managed by an organization the user is linked to.'}}}

{'type': 'object', 'required': [], 'properties': {}}

{'type': 'object', 'required': ['message'], 'properties': {'count': {'type': 'number', 'description': 'Number of connected apps.'}, 'status': {'type': 'string', 'description': 'Result status: "no_connections" when none are connected, otherwise "ok".'}, 'message': {'type': 'string', 'description': 'Human-readable summary of the connected apps.'}, 'connections': {'type': 'array', 'items': {'type': 'object', 'properties': {'active': {'type': 'boolean', 'description': 'Whether the connection is still active.'}, 'scopes': {'type': 'array', 'items': {'type': 'string'}, 'description': 'OAuth scopes granted to the app.'}, 'clientId': {'type': 'string', 'description': 'The OAuth client ID of the connected app.'}, 'clientName': {'type': ['string', 'null'], 'description': 'The display name of the connected app, or null if unnamed.'}, 'connectedAt': {'type': 'string', 'description': 'ISO timestamp of when the app was first connected.'}, 'lastTokenAt': {'type': 'string', 'description': 'ISO timestamp of the most recent token issued to the app.'}}}, 'description': "The third-party apps connected to the user's account via OAuth."}}}

{'type': 'object', 'required': [], 'properties': {}}

{'type': 'object', 'required': ['message'], 'properties': {'count': {'type': 'number', 'description': 'Number of saved payment methods.'}, 'status': {'enum': ['listed', 'no_payment_method'], 'type': 'string', 'description': 'Whether any payment methods are saved.'}, 'message': {'type': 'string', 'description': 'Human-readable summary of the saved payment methods.'}, 'defaultId': {'type': 'string', 'description': 'The id of the payment method marked as default, if any.'}, 'paymentMethods': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string', 'description': 'The payment method ID (e.g. pm_xxx).'}, 'brand': {'type': 'string', 'description': 'Card brand, e.g. "visa".'}, 'last4': {'type': 'string', 'description': 'Last 4 digits of the card.'}, 'expYear': {'type': 'number', 'description': 'Card expiry year.'}, 'expMonth': {'type': 'number', 'description': 'Card expiry month.'}, 'isDefault': {'type': 'boolean', 'description': 'Whether this is the default payment method.'}}}, 'description': 'The saved payment methods.'}}}

{'type': 'object', 'required': [], 'properties': {}}

{'type': 'object', 'required': ['message'], 'properties': {'count': {'type': 'number', 'description': 'Number of pending approvals.'}, 'status': {'type': 'string', 'description': 'Present only when the list is unavailable: "personal_surface_only" for company-connected sessions.'}, 'message': {'type': 'string', 'description': 'Human-readable list of pending approvals (or an empty-state note).'}, 'approvals': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string', 'description': 'Approval id. Pass as approval_id to approve_request once the user decides.'}, 'card': {'type': ['object', 'null'], 'properties': {'id': {'type': 'string', 'description': 'Card id.'}, 'last4': {'type': 'string', 'description': 'Last four digits.'}, 'provider': {'type': 'string', 'description': 'Issuing provider.'}, 'connectedCard': {'type': ['object', 'null'], 'description': "For cards created against the user's added card: the real card behind it (issuer, brand, last4, nickname)."}}, 'description': 'The card the ask is about (null for card-creation asks).'}, 'action': {'type': 'string', 'description': "Machine action, e.g. 'transaction', 'card_details', 'cross_app:close'."}, 'params': {'type': 'object', 'description': 'Structured numbers bound to the ask, e.g. { amountCents } or { newLimitCents }.'}, 'appName': {'type': ['string', 'null'], 'description': 'The app or company asking, when known.'}, 'summary': {'type': ['string', 'null'], 'description': 'Short human summary of the ask, e.g. "$25.00 card".'}, 'createdAt': {'type': 'string', 'description': 'ISO timestamp when the ask was made.'}, 'expiresAt': {'type': 'string', 'description': 'ISO timestamp when the ask expires unanswered.'}, 'actionLabel': {'type': 'string', 'description': "Human verb for the ask, e.g. 'Create a card'."}}}, 'description': "Pending, unexpired approval requests, newest first. Each is waiting on the user's decision."}}}

{'type': 'object', 'required': [], 'properties': {}}

{'type': 'object', 'required': ['message'], 'properties': {'message': {'type': 'string'}, 'presets': {'type': 'array', 'items': {'type': 'object', 'properties': {'key': {'type': 'string', 'description': 'The name to pass elsewhere as `preset`.'}, 'builtin': {'type': 'boolean'}, 'summary': {'type': 'string'}, 'version': {'type': 'number'}}}}}}

{'type': 'object', 'required': [], 'properties': {'limit': {'type': 'number', 'description': 'Max number of transactions to return (default 20)'}, 'offset': {'type': 'number', 'description': 'Skip this many (all-cards view pagination; ignored for a single card).'}, 'status': {'type': 'string', 'description': 'Filter by transaction status (e.g. PENDING, SETTLED, DECLINED, REVERSED, EXPIRED, REFUNDED)'}, 'card_id': {'type': 'string', 'description': "A card ID for that card's transactions; omit for all cards in the account."}}}

{'type': 'object', 'required': ['message'], 'properties': {'count': {'type': 'number', 'description': 'Number of transactions returned.'}, 'message': {'type': 'string', 'description': 'Human-readable list of transactions (or a "no transactions" note).'}, 'transactions': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string', 'description': 'Transaction ID.'}, 'mcc': {'type': 'string', 'description': 'Merchant category code.'}, 'cardId': {'type': ['string', 'null'], 'description': 'Card ID (present in the all-cards view; null for wallet-funding rows).'}, 'source': {'type': 'string', 'description': 'Transaction source.'}, 'status': {'type': 'string', 'description': 'Status, e.g. PENDING, SETTLED, DECLINED, REVERSED, EXPIRED, REFUNDED.'}, 'merchant': {'type': 'string', 'description': 'Merchant name.'}, 'cardLast4': {'type': ['string', 'null'], 'description': 'Last four of the card (present in the all-cards view; null for wallet-funding rows).'}, 'createdAt': {'type': 'string', 'description': 'ISO timestamp when the transaction was created.'}, 'eventType': {'type': 'string', 'description': 'Underlying issuing event type.'}, 'amountCents': {'type': 'number', 'description': 'Transaction amount in cents.'}, 'description': {'type': 'string', 'description': 'Transaction description.'}, 'processorTransactionId': {'type': ['string', 'null'], 'description': "The card processor's reference for the charge, the value transaction.* webhook events carry as data.id (their transaction_id is this row's id). Null for wallet-funding rows."}}}, 'description': 'The transactions for the card, newest first.'}}}

{'type': 'object', 'required': ['merchant', 'action'], 'properties': {'date': {'type': 'string', 'description': 'skip/unskip: one ISO delivery date (YYYY-MM-DD)'}, 'dates': {'type': 'array', 'items': {'type': 'string'}, 'description': 'set_skip_dates: FULL set of ISO dates to skip ([] resumes all)'}, 'limit': {'type': 'number', 'description': 'menu_search: max items'}, 'query': {'type': 'string', 'description': "menu_search: term over the recurring menu (e.g. 'salmon'); '' lists everything"}, 'value': {'description': 'update_setting: the new value (number, string, or array of strings)'}, 'action': {'enum': ['menu_search', 'get_skip_dates', 'skip', 'unskip', 'set_skip_dates', 'update_setting'], 'type': 'string', 'description': 'the management action'}, 'setting': {'type': 'string', 'description': 'update_setting: the setting key (see description)'}, 'merchant': {'type': 'string', 'description': 'merchant slug (e.g. locale)'}}}

{'type': 'object', 'required': ['message'], 'properties': {'message': {'type': 'string', 'description': 'Human-readable result or next step.'}}}

{'type': 'object', 'required': ['card_id'], 'properties': {'card_id': {'type': 'string', 'description': 'The vault card id (from list_cards â\x86\x92 vaultCards).'}, 'product': {'type': 'string', 'description': 'The card product as the user says it, e.g. "Chase Sapphire Preferred" or "Amex Gold". Four characters minimum.'}, 'clear_product': {'type': 'boolean', 'description': 'true = forget the product name. Do not combine with product.'}, 'smart_excluded': {'type': 'boolean', 'description': 'true = leave this card out of smart purchases; false = include it again.'}}}

{'type': 'object', 'required': ['message', 'status'], 'properties': {'status': {'type': 'string', 'description': '"named" | "cleared" | "updated" | "no_match" | "ambiguous" (several products match; nothing saved, ask the user) | "noop".'}, 'matches': {'type': 'array', 'description': 'On no_match or an ambiguous name: the closest products found, to offer the user.'}, 'message': {'type': 'string', 'description': 'What was saved.'}, 'product_key': {'type': ['string', 'null'], 'description': 'The saved product key.'}, 'product_name': {'type': ['string', 'null'], 'description': 'The saved product name.'}}}

{'type': 'object', 'required': ['card_id'], 'properties': {'card_id': {'type': 'string', 'description': 'The card ID to pause (from list_cards or create_card).'}, 'approval_id': {'type': 'string', 'description': 'Approval id from a prior approval_required response, once the user has approved. Only for cards created through ANOTHER app: first call without it (the user is emailed an approve link), then retry with it.'}}}

{'type': 'object', 'required': ['message'], 'properties': {'cardId': {'type': 'string', 'description': 'The card ID.'}, 'status': {'type': 'string', 'description': '"paused" on success; an error discriminator otherwise (e.g. "not_multi_use", "card_not_updatable").'}, 'message': {'type': 'string', 'description': 'Human-readable result.'}}}

{'type': 'object', 'required': ['conversation_id'], 'properties': {'conversation_id': {'type': 'string', 'description': 'The conversation ID'}}}

{'type': 'object', 'required': ['message'], 'properties': {'count': {'type': 'number', 'description': 'Number of messages returned.'}, 'status': {'type': 'string', 'description': "Outcome of the read: 'empty' when there are no messages yet, 'ok' when messages were returned."}, 'message': {'type': 'string', 'description': 'Human-readable rendering of the conversation history.'}, 'messages': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string', 'description': 'Unique message ID.'}, 'body': {'type': 'string', 'description': 'The message text.'}, 'role': {'type': 'string', 'description': "Author role, e.g. 'visitor' for the user or an agent role for support."}, 'createdAt': {'type': 'string', 'description': 'ISO timestamp of when the message was created.'}}}, 'description': 'The messages in the conversation, oldest first.'}}}

{'type': 'object', 'required': ['merchant'], 'properties': {'currency': {'type': 'string', 'description': 'ISO currency code, default usd. Non-USD purchases account for foreign transaction fees.'}, 'merchant': {'type': 'string', 'description': 'The merchant as the user would see it, e.g. "DoorDash".'}, 'amount_cents': {'type': 'number', 'description': 'Order total in cents, when known.'}, 'merchant_url': {'type': 'string', 'description': "The merchant's website or checkout origin, e.g. https://www.doordash.com. Improves the category match."}}}

{'type': 'object', 'required': ['message'], 'properties': {'reason': {'type': ['string', 'null'], 'description': 'Why, in one or two sentences the user can be told verbatim.'}, 'card_id': {'type': ['string', 'null'], 'description': 'The vault card to pay with (pass as card_id at checkout), or null.'}, 'message': {'type': 'string', 'description': 'Human-readable pick and reason.'}, 'category': {'type': ['string', 'null'], 'description': 'The spend category the merchant resolved to.'}, 'alternatives': {'type': 'array', 'description': 'Other stored cards with their estimated value in cents and reason.'}}}

{'type': 'object', 'required': ['code'], 'properties': {'code': {'type': 'string', 'description': 'The promo code exactly as the user provided it (case and dashes are forgiven).'}}}

{'type': 'object', 'required': ['message'], 'properties': {'message': {'type': 'string', 'description': 'Human-readable result or next step.'}}}

{'type': 'object', 'required': ['tokens'], 'properties': {'tokens': {'type': 'number', 'description': 'How many tokens to redeem (1 token = 1 cent, so 500 tokens = $5.00 of wallet credit).'}}}

{'type': 'object', 'required': ['message'], 'properties': {'status': {'type': 'string', 'description': '"redeemed" on success; an error discriminator otherwise (e.g. "below_minimum", "insufficient_tokens", "redemption_in_progress").'}, 'message': {'type': 'string', 'description': 'Human-readable result.'}, 'amountCents': {'type': 'number', 'description': 'Wallet credit in cents. Present when status is "redeemed".'}, 'redemptionId': {'type': 'string', 'description': 'The redemption ID. Present when status is "redeemed".'}, 'deliveredCardId': {'type': 'string', 'description': 'Rewards card the value landed on, when delivery completed inline. Absent = the value sits as wallet credit (it reaches the rewards card within a few minutes when delivery is enabled).'}, 'deliveredCardLast4': {'type': 'string', 'description': 'Last 4 digits of the rewards card, when delivered inline.'}}}

{'type': 'object', 'required': ['attached_card_id'], 'properties': {'attached_card_id': {'type': 'string', 'description': 'The id of the added card to remove (from list_added_cards).'}}}

{'type': 'object', 'required': ['message'], 'properties': {'id': {'type': 'string', 'description': 'The id of the removed card.'}, 'status': {'type': 'string', 'description': '"revoked" on success.'}, 'message': {'type': 'string', 'description': 'Human-readable confirmation or guidance.'}, 'closedCards': {'type': 'number', 'description': 'How many virtual cards created against it were closed.'}}}

{'type': 'object', 'required': ['card_id'], 'properties': {'card_id': {'type': 'string', 'description': 'The paused card ID to resume.'}, 'approval_id': {'type': 'string', 'description': 'Approval id from a prior approval_required response, once the user has approved. Only for cards created through ANOTHER app: first call without it (the user is emailed an approve link), then retry with it.'}}}

{'type': 'object', 'required': ['message'], 'properties': {'cardId': {'type': 'string', 'description': 'The card ID.'}, 'status': {'type': 'string', 'description': '"active" on success; an error discriminator otherwise (e.g. "card_not_paused").'}, 'message': {'type': 'string', 'description': 'Human-readable result.'}}}

{'type': 'object', 'required': ['client_id'], 'properties': {'client_id': {'type': 'string', 'description': 'The OAuth client ID of the app to revoke (from list_connections).'}}}

{'type': 'object', 'required': ['message'], 'properties': {'status': {'type': 'string', 'description': 'Result status: "revoked" when tokens were invalidated, "not_connected" when the app had no active access.'}, 'message': {'type': 'string', 'description': 'Human-readable outcome.'}, 'revoked': {'type': 'number', 'description': 'Number of OAuth tokens that were revoked.'}, 'clientId': {'type': 'string', 'description': 'The client ID that was revoked.'}}}

{'type': 'object', 'required': ['name'], 'properties': {'mode': {'enum': ['strict', 'watch'], 'type': 'string', 'description': 'What the preset does when a purchase breaks any of its rules: "strict" refuses it (the default), "watch" lets it through and tells the user once.'}, 'name': {'type': 'string', 'description': 'A name for this preset, e.g. "meals-only".'}, 'total': {'type': 'number', 'description': 'Lifetime spend cap, in US dollars.'}, 'only_in': {'type': 'string', 'description': 'Comma-separated places to allow charges from: a country ("US", "Canada"), a region ("europe", "eu", "north-america", "latin-america", "apac"), or a US state ("California", "US-CA"). A region expands to its countries; a state next to a region narrows only the US, e.g. "north-america,US-CA". Example: "europe,Canada".'}, 'per_day': {'type': 'number', 'description': 'Spend cap per rolling 24 hours, in US dollars.'}, 'per_week': {'type': 'number', 'description': 'Spend cap per rolling 7 days, in US dollars.'}, 'timezone': {'type': 'string', 'description': 'IANA timezone for only_days/only_hours (default UTC), e.g. "America/Los_Angeles". Always shown in summaries.'}, 'only_days': {'type': 'string', 'description': 'Comma-separated days to allow, e.g. "mon,tue,wed" or "weekdays"/"weekends".'}, 'only_from': {'type': 'string', 'description': 'Comma-separated callers to allow, e.g. "cli,mcp" (cli, mcp, api, browser).'}, 'per_month': {'type': 'number', 'description': 'Spend cap per rolling 30 days, in US dollars.'}, 'categories': {'type': 'string', 'description': 'Comma-separated spend categories to allow, e.g. "meals,groceries" (meals, groceries, travel, software, ai, wellness, retail).'}, 'currencies': {'type': 'string', 'description': 'Comma-separated purchase currencies to allow: ISO 4217 codes or common names, e.g. "usd,eur" or "dollars,euros,pounds,yen". In strict mode a purchase in another currency is refused at checkout and a settled charge in another currency pauses the card. Checked by Agentcard at checkout and settlement, not by the card network. Unknown currencies are refused.'}, 'only_hours': {'type': 'string', 'description': 'An hour range to allow, e.g. "9-17" (24-hour clock; defaults to UTC without timezone).'}, 'privileges': {'type': 'array', 'items': {}, 'description': 'Advanced: raw privilege objects instead of the rule fields above.'}, 'only_merchants': {'type': 'string', 'description': 'Comma-separated merchant name patterns to allow, e.g. "openai,anthropic".'}}}

{'type': 'object', 'required': ['message'], 'properties': {'preset': {'type': ['object', 'null'], 'properties': {'id': {'type': 'string'}, 'name': {'type': ['string', 'null']}, 'summary': {'type': 'string'}, 'version': {'type': 'number'}}}, 'message': {'type': 'string'}}}

{'type': 'object', 'required': ['conversation_id', 'message'], 'properties': {'message': {'type': 'string', 'description': 'Your message'}, 'conversation_id': {'type': 'string', 'description': 'The conversation ID'}}}

{'type': 'object', 'required': ['message'], 'properties': {'message': {'type': 'string', 'description': 'Human-readable confirmation that the message was sent.'}, 'conversationId': {'type': 'string', 'description': 'The ID of the conversation the message was sent to.'}}}

{'type': 'object', 'required': ['card_id', 'preset'], 'properties': {'preset': {'oneOf': [{'type': 'string'}, {'type': 'null'}, {'type': 'object', 'required': ['privileges'], 'properties': {'name': {'type': 'string'}, 'privileges': {'type': 'array', 'items': {}}}}], 'description': 'Template name (ai_labs, weekday_meals, cli_only, daily), comma-separated templates, inline JSON privileges, or { name?, privileges }. Pass null or "" with card_id to clear that card\'s preset.'}, 'card_id': {'type': 'string', 'description': 'The card id (from list_cards).'}}}

{'type': 'object', 'required': ['message'], 'properties': {'preset': {'type': ['object', 'null'], 'properties': {'id': {'type': 'string'}, 'name': {'type': ['string', 'null']}, 'summary': {'type': 'string'}, 'version': {'type': 'number'}}}, 'pushed': {'type': 'array', 'items': {'type': 'string'}}, 'message': {'type': 'string'}, 'summary': {'type': 'string'}, 'messages': {'type': 'array', 'items': {'type': 'string'}}, 'policyId': {'type': 'string'}, 'needsNewCard': {'type': 'boolean'}, 'agentcardOnly': {'type': 'array', 'items': {'type': 'string'}}, 'policyVersion': {'type': 'number'}}}

{'type': 'object', 'required': [], 'properties': {}}

{'type': 'object', 'required': ['message'], 'properties': {'message': {'type': 'string', 'description': 'Human-readable summary of the result.'}, 'checkoutUrl': {'type': 'string', 'description': 'Secure Stripe checkout URL the user must open to save their payment method.'}, 'stripeSessionId': {'type': 'string', 'description': 'Identifier of the Stripe Checkout session created for the setup.'}}}

{'type': 'object', 'required': [], 'properties': {'terms_accepted': {'type': 'boolean', 'description': "DEPRECATED â\x80\x94 use agreements_accepted. Pass true once the user has explicitly agreed to the card issuer's cardholder terms in the conversation."}, 'agreements_accepted': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Keys of the User Agreements the user explicitly accepted, one by one (the full required set from the agreements list â\x80\x94 e.g. e_sign, account_opening_privacy, card_terms, accuracy, non_solicitation). Only pass after presenting each agreement verbatim and getting a yes covering all of them.'}}}

{'type': 'object', 'required': ['message'], 'properties': {'reason': {'type': ['string', 'null'], 'description': 'Provider reason on rejection.'}, 'status': {'type': 'string', 'description': '"started", "verified", "rejected", or "unknown".'}, 'message': {'type': 'string', 'description': 'Human-readable summary / next step.'}, 'nextStep': {'type': ['string', 'null'], 'description': 'Conversational step: id_document | fields | terms | face_verification | review_pending | verified | rejected.'}, 'uploadUrl': {'type': 'string', 'description': 'Browser upload page for the ID photo (1h validity).'}, 'missingFields': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Fields still needed from the user.'}, 'verificationUrl': {'type': 'string', 'description': 'Face-scan page (conversational flow) or hosted verification URL (legacy flow), 48h validity.'}}}

{'type': 'object', 'required': [], 'properties': {}}

{'type': 'object', 'required': ['message'], 'properties': {'message': {'type': 'string', 'description': 'Human-readable result or next step.'}}}

{'type': 'object', 'required': ['message'], 'properties': {'message': {'type': 'string', 'description': 'Your initial support message'}}}

{'type': 'object', 'required': ['message'], 'properties': {'message': {'type': 'string', 'description': 'Human-readable summary confirming the conversation was started.'}, 'conversationId': {'type': 'string', 'description': 'The ID of the newly created support conversation. Pass this to send_support_message or read_support_chat.'}}}

{'type': 'object', 'required': [], 'properties': {'file_path': {'type': 'string', 'description': 'Local path to the ID photo (front of license, or passport photo page). Local/stdio connections only â\x80\x94 remote connections without image data receive an upload link instead.'}, 'back_base64': {'type': 'string', 'description': 'Base64 image bytes of the license back (optional, recommended â\x80\x94 the barcode reads most accurately). Same rule: programmatically sourced only.'}, 'front_base64': {'type': 'string', 'description': 'Base64 image bytes of the ID front (or passport photo page). ONLY pass base64 you received programmatically from your platform (e.g. an injected chat attachment) â\x80\x94 never type or reconstruct image bytes yourself.'}, 'document_type': {'enum': ['drivers_license', 'state_id', 'passport'], 'type': 'string', 'description': 'ONLY pass this when the user themselves said what the document is ("here\'s my license") â\x80\x94 otherwise omit it; the type is detected from the photo. Never ask up front.'}, 'back_file_path': {'type': 'string', 'description': 'Local path to the back of the license (optional, recommended). Local/stdio connections only.'}, 'back_mime_type': {'type': 'string', 'description': 'MIME type of back_base64. Defaults to image/jpeg.'}, 'front_mime_type': {'type': 'string', 'description': 'MIME type of front_base64 (image/jpeg, image/png, image/webp). Defaults to image/jpeg.'}, 'issuing_country': {'type': 'string', 'description': '2-letter ISO country that issued the document (e.g. US, AR). ONLY when the user volunteered it â\x80\x94 otherwise omit; it is detected from the photo. Never ask up front.'}}}

{'type': 'object', 'required': ['message'], 'properties': {'status': {'type': 'string', 'description': 'processed | document_expired | upload_failed | upload_link_provided'}, 'message': {'type': 'string'}, 'nextStep': {'type': ['string', 'null']}, 'extracted': {'type': 'object', 'description': 'Fields read from the document (confirm with the user).'}, 'uploadUrl': {'type': 'string'}, 'unreadable': {'type': 'boolean', 'description': 'True when the image was received but NO identity fields could be read from it â\x80\x94 it did not read as an ID; never assert to the user that it was one.'}, 'missingFields': {'type': 'array', 'items': {'type': 'string'}}, 'verificationUrl': {'type': 'string'}}}

{'type': 'object', 'required': [], 'properties': {'ssn': {'type': 'string', 'description': 'US documents: 9-digit SSN, dashes optional. Non-US documents: the national ID / tax number printed on the ID. Forward-only â\x80\x94 never stored.'}, 'last_name': {'type': 'string', 'description': 'Legal last name, exactly as printed on the ID document.'}, 'first_name': {'type': 'string', 'description': 'Legal first name, exactly as printed on the ID document.'}, 'address_city': {'type': 'string', 'description': 'City of the residential address.'}, 'phone_number': {'type': 'string', 'description': 'E.164 with country code, e.g. +14155551234.'}, 'address_line1': {'type': 'string', 'description': 'Residential street address, line 1 (e.g. 123 Main St).'}, 'address_line2': {'type': 'string', 'description': 'Residential street address, line 2 â\x80\x94 apartment, suite, or unit. Omit if none.'}, 'date_of_birth': {'type': 'string', 'description': 'YYYY-MM-DD'}, 'address_region': {'type': 'string', 'description': '2-letter state code for US (e.g. CA).'}, 'terms_accepted': {'type': 'boolean', 'description': "DEPRECATED â\x80\x94 use agreements_accepted. true once the user explicitly accepted the card issuer's cardholder terms."}, 'address_postal_code': {'type': 'string', 'description': 'Postal / ZIP code of the residential address.'}, 'agreements_accepted': {'type': 'array', 'items': {'type': 'string'}, 'description': "Keys of the User Agreements the user explicitly accepted, one by one â\x80\x94 the FULL required set from the agreements list in the previous step's result. Only pass after presenting each agreement verbatim and getting an explicit yes covering all of them."}, 'address_country_code': {'type': 'string', 'description': '2-letter ISO country code (e.g. US).'}}}

{'type': 'object', 'required': ['message'], 'properties': {'message': {'type': 'string'}, 'nextStep': {'type': ['string', 'null']}, 'missingFields': {'type': 'array', 'items': {'type': 'string'}}, 'verificationUrl': {'type': 'string', 'description': 'Face-scan link, present once everything is collected.'}}}

{'type': 'object', 'required': ['phone_number', 'terms_accepted'], 'properties': {'phone_number': {'type': 'string', 'description': "User's phone number in international E.164 format with a country code (e.g. +1 555 123 4567, +44 7911 123456)"}, 'terms_accepted': {'type': 'boolean', 'description': 'Must be true â\x80\x94 the user accepted the AgentCard cardholder terms of service'}}}

{'type': 'object', 'required': ['message'], 'properties': {'status': {'type': 'string', 'description': "Outcome of the submission: 'saved' when the user information was stored successfully."}, 'message': {'type': 'string', 'description': 'Human-readable confirmation that the user information was saved.'}}}

{'type': 'object', 'required': [], 'properties': {'vibe': {'type': 'string', 'description': 'Optional notes/vibe from the user, e.g. "make it food", "something for my desk", "they love ducks".'}, 'merchant': {'type': 'string', 'description': "Optional merchant hint the surprise should come from, e.g. 'doordash'. Omit to let the agent pick."}, 'max_dollars': {'type': 'number', 'description': 'Hard spend cap in dollars, total including fees. Optional; default 10, values above 25 are clamped to 25.'}}}

{'type': 'object', 'required': ['message'], 'properties': {'status': {'enum': ['assistant_turn', 'conversation_start_failed', 'request_failed'], 'type': 'string', 'description': "Discriminator for the outcome. 'assistant_turn' when the buy loop replied; 'conversation_start_failed' or 'request_failed' on errors."}, 'message': {'type': 'string', 'description': "The assistant's conversational turn (it may ask for the delivery address, show the cart + total, confirm, or report a placed order), or an error explanation."}, 'messages': {'type': 'array', 'items': {'type': 'string'}, 'description': 'The same turn split into ordered messages for multi-bubble surfaces (each narration segment, then the final reply/confirmation). `message` is the same content consolidated; clients that show one bubble should use `message` and ignore this.'}, 'conversation_id': {'type': 'string', 'description': 'The conversation id to thread back as conversation_id on the next buy call to continue the SAME order. Present on a successful assistant turn.'}}}

{'type': 'object', 'required': ['card_id'], 'properties': {'card_id': {'type': 'string', 'description': 'The multi-use card ID to resize.'}, 'approval_id': {'type': 'string', 'description': 'Approval id from a prior approval_required response, once the user has approved. Only for cards created through ANOTHER app: first call without it (the user is emailed an approve link), then retry with it.'}, 'new_limit_cents': {'type': 'number', 'description': 'Deprecated alias for spend_limit_cents. Prefer spend_limit_cents (matches the docs and the REST API).'}, 'spend_limit_cents': {'type': 'number', 'description': 'The new TOTAL spending limit in cents (minimum 100). This is the lifetime cap, not a delta: a card that spent $20 of a $50 limit, resized to 8000, can spend $60 more.'}}}

{'type': 'object', 'required': ['message'], 'properties': {'cardId': {'type': 'string', 'description': 'The card ID.'}, 'status': {'type': 'string', 'description': '"updated" on success; an error discriminator otherwise (e.g. "limit_below_spent", "insufficient_collateral").'}, 'message': {'type': 'string', 'description': 'Human-readable result.'}, 'balanceCents': {'type': 'number', 'description': 'The remaining spendable balance in cents.'}, 'spendLimitCents': {'type': 'number', 'description': 'The new total limit in cents.'}}}

{'type': 'object', 'required': [], 'properties': {'plan': {'enum': ['basic', 'pro'], 'type': 'string', 'description': "Which plan to upgrade to. Defaults to 'basic'."}}}

{'type': 'object', 'required': ['message'], 'properties': {'plan': {'type': 'string', 'description': "Display label of the target plan, e.g. 'Basic' or 'Pro'. Present when the requested plan is known."}, 'status': {'enum': ['swapped', 'checkout_required', 'already_on_plan', 'waitlisted', 'unavailable', 'checkout_failed'], 'type': 'string', 'description': 'Discriminator for the outcome branch.'}, 'message': {'type': 'string', 'description': 'Human-readable summary of the upgrade outcome.'}, 'checkoutUrl': {'type': 'string', 'description': 'Stripe Checkout URL the user must open to complete payment. Present only when status is checkout_required.'}}}

{'type': 'object', 'required': ['code'], 'properties': {'code': {'type': 'string', 'description': 'The one-time code the user received, as a string (keep any leading zeros â\x80\x94 do not send it as a number).'}}}

{'type': 'object', 'required': ['message'], 'properties': {'message': {'type': 'string', 'description': 'Human-readable result or next step.'}}}

{'type': 'object', 'required': [], 'properties': {}}

{'type': 'object', 'required': ['message'], 'properties': {'name': {'type': ['string', 'null'], 'description': 'Cardholder name ("First Last"), or null before KYC info is submitted.'}, 'plan': {'type': 'string', 'description': "Subscription plan id, e.g. 'free', 'basic', or 'pro'."}, 'email': {'type': ['string', 'null'], 'description': 'Email of the authenticated account, or null for a phone-first account (e.g. signed up by text message).'}, 'userId': {'type': 'string', 'description': 'AgentCard user id of the authenticated account.'}, 'message': {'type': 'string', 'description': 'Human-readable identity summary.'}, 'kycStatus': {'type': ['string', 'null'], 'description': 'Raw stored KYC state (e.g. approved, pending, requires_input), or null if never started.'}, 'kycVerified': {'type': 'boolean', 'description': 'Whether identity verification (KYC) has passed (stored snapshot).'}, 'memberSince': {'type': 'string', 'description': 'ISO timestamp the account was created.'}, 'accountStatus': {'type': 'string', 'description': "Account standing: 'active' or 'suspended'."}, 'connectionType': {'enum': ['oauth', 'personal', 'organization'], 'type': 'string', 'description': "How this session authenticates: 'oauth' (third-party app connection), 'personal' (CLI/dashboard login), or 'organization' (a company's Agentcard integration acting for its end user)."}, 'connectionClientId': {'type': ['string', 'null'], 'description': "OAuth client id of the connected app, when connectionType is oauth, or organization through a company's app."}, 'subscriptionStatus': {'type': ['string', 'null'], 'description': "Stripe subscription status (e.g. 'active', 'past_due'), or null on the free plan."}, 'connectionClientName': {'type': ['string', 'null'], 'description': 'Display name of the connected OAuth app (e.g. "Claude"), when known, for an oauth or organization connection.'}, 'connectionOrganizationId': {'type': ['string', 'null'], 'description': 'Organization id, when connectionType is organization.'}}}