> ## Documentation Index > Fetch the complete documentation index at: https://tbd-6fc993ce-hypeship-managed-auth-region.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Perform an operation advertised by a vault item > Retrieve the item first and invoke only an operation listed in `available_operations`, following its natural-language description. Availability is rechecked at execution time; unavailable operations return 409. Authorization and preparation may call an external provider and return updated state. Link cards advertise authorize without checkout context. Eligible unused AgentCard cards advertise prepare_checkout, which requires checkout context and obtains device approval before native Square Pay. Keep the returned approval page open, poll until ready_to_submit, then submit before preparation.expires_at. Unused preparations expire automatically and cannot be reused. If spend-request creation is rate limited, returns HTTP 429 with code `spend_request_rate_limited`; stop and back off before retrying. Fill returns a value-free execution result. Validation failures before writing return 400 (invalid request or targets), 403 (access or destination denied), 404 (resource not found), or 409 (item or browser not ready). Once writing starts, known partial failures and indeterminate field outcomes return 200 with status `failed` or `unknown`, not an automatic-retry signal. A transport error may leave the outcome unknown; do not automatically retry. ## OpenAPI ````yaml https://api.onkernel.com/spec.json post /vaults/{id_or_name}/items/{key}/operations openapi: 3.1.0 info: description: Developer tools and cloud infrastructure for AI agents to use web browsers title: Kernel API version: 0.1.0 servers: - description: API Server url: https://api.onkernel.com security: - bearerAuth: [] tags: - description: Create and manage browser sessions. name: Browsers - description: Control mouse, keyboard, and screen on the browser instance. name: Browser Computer Controls - description: Execute Playwright code against the browser instance. name: Browser Playwright - description: Discover and invoke native page tools across the browser instance. name: Browser WebMCP - description: Read, write, and manage files on the browser instance. name: Browser Filesystem - description: Execute and manage processes on the browser instance. name: Browser Processes - description: Record and manage browser session video replays. name: Browser Replays - description: Stream logs from the browser instance. name: Browser Logs - description: >- Stream live telemetry events from a browser session, and manage the destinations sessions export them to. name: Browser Telemetry - description: Create, list, retrieve, and delete browser profiles. name: Profiles - description: Create and manage proxy configurations for routing browser traffic. name: Proxies - description: Create, list, retrieve, and delete browser extensions. name: Extensions - description: Create and manage browser pools for acquiring and releasing browsers. name: Browser Pools - description: Inspect the identity and authorization context for the current request. name: Authentication - description: >- Create and manage auth connections for automated credential capture and login. name: Managed Auth - description: Create and manage credentials for authentication. name: Credentials - description: Configure external credential providers like 1Password. name: Credential Providers - description: List applications and versions. name: Apps - description: Create and manage app deployments and stream deployment events. name: Deployments - description: Invoke actions and stream or query invocation status and events. name: Invocations - description: Read and manage organization-level limits. name: Organization - description: | Create and manage projects for resource isolation within an organization. When projects are disabled for the organization, project operations return `404` with code `projects_disabled`. name: Projects - description: Create and manage API keys for organization and project-scoped access. name: API Keys - description: Read audit log records for the authenticated organization. name: Audit Logs - description: Resolve browser and proxy recommendations for bot-protected sites. name: Config Registry paths: /vaults/{id_or_name}/items/{key}/operations: post: tags: - Vaults summary: Perform an operation advertised by a vault item description: > Retrieve the item first and invoke only an operation listed in `available_operations`, following its natural-language description. Availability is rechecked at execution time; unavailable operations return 409. Authorization and preparation may call an external provider and return updated state. Link cards advertise authorize without checkout context. Eligible unused AgentCard cards advertise prepare_checkout, which requires checkout context and obtains device approval before native Square Pay. Keep the returned approval page open, poll until ready_to_submit, then submit before preparation.expires_at. Unused preparations expire automatically and cannot be reused. If spend-request creation is rate limited, returns HTTP 429 with code `spend_request_rate_limited`; stop and back off before retrying. Fill returns a value-free execution result. Validation failures before writing return 400 (invalid request or targets), 403 (access or destination denied), 404 (resource not found), or 409 (item or browser not ready). Once writing starts, known partial failures and indeterminate field outcomes return 200 with status `failed` or `unknown`, not an automatic-retry signal. A transport error may leave the outcome unknown; do not automatically retry. operationId: postVaultItemOperation parameters: - in: path name: id_or_name required: true schema: type: string - in: path name: key required: true schema: type: string requestBody: content: application/json: examples: agentcard_prepare_checkout: summary: >- Prepare an unused AgentCard card that advertises this operation value: checkout: browser_id: browser-session-id environment: production merchant_origin: https://shop.example.com type: prepare_checkout link_authorize: summary: Authorize a Link card that advertises this operation value: type: authorize schema: $ref: '#/components/schemas/VaultItemOperationRequest' required: true responses: '200': content: application/json: examples: link_authorize: $ref: '#/components/examples/ExampleLinkApproval' schema: $ref: '#/components/schemas/VaultItemOperationResponse' description: >- Authorization or preparation completed or resumed, or fill execution outcomes returned '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' security: - bearerAuth: [] components: schemas: VaultItemOperationRequest: discriminator: mapping: authorize: $ref: '#/components/schemas/AuthorizeVaultItemOperationRequest' collect: $ref: '#/components/schemas/CollectVaultItemOperationRequest' fill: $ref: '#/components/schemas/FillVaultItemOperationRequest' prepare_checkout: $ref: '#/components/schemas/PrepareCheckoutVaultItemOperationRequest' propertyName: type oneOf: - $ref: '#/components/schemas/AuthorizeVaultItemOperationRequest' - $ref: '#/components/schemas/CollectVaultItemOperationRequest' - $ref: '#/components/schemas/PrepareCheckoutVaultItemOperationRequest' - $ref: '#/components/schemas/FillVaultItemOperationRequest' VaultItemOperationResponse: description: >- Authorization and preparation return the existing item shape. Fill returns a value-free execution result; it does not persist transient field outcomes on the item. oneOf: - $ref: '#/components/schemas/VaultItem' - $ref: '#/components/schemas/FillVaultItemOperationResult' AuthorizeVaultItemOperationRequest: additionalProperties: false description: >- Authorize a Link card using its existing purchase specification. Use only after explicit user approval and when the item advertises authorize. Do not automatically retry provider failures or indeterminate outcomes. Checkout context is not accepted. properties: type: enum: - authorize type: string x-go-type: VaultItemOperationType required: - type type: object CollectVaultItemOperationRequest: additionalProperties: false description: > Return the credential item with its collection action. Supported for ready and pending_collection credential items. Always render the same form from every form-supported field; totp fields have no form input and are omitted. No caller-selected field subsets or form overrides are accepted. Reuse an active Kernel-hosted session or renew an expired session atomically. Customer-hosted forms use their own backend and ordinary item GET/PATCH. Opening the form does not clear values or change readiness or item version. To observe edits on a ready item, record its version and poll GET without wait until the version changes, then reconcile the returned state. Version changes may also come from PATCH; they do not identify a particular form submission. Customer-hosted apps use their own submission callback, including for unchanged forms. The wait parameter waits for readiness, not edits. properties: type: enum: - collect type: string required: - type type: object FillVaultItemOperationRequest: additionalProperties: false description: > Fill selected fields from one ready credential or ready, unexpired Link card into a browser linked to its vault. Only invoke when the item advertises `fill`. Browser and vault must belong to the same project. Kernel checks access and allowed destinations before filling; providing a page URL does not authorize a destination. Find exactly one open page matching `page_url`. Credential items may omit `page_url` to require exactly one open page; cards require an HTTPS page URL. Credentials have no destination allowlist. TOTP fields generate a current code immediately before writing; their seeds never enter the browser. For each selector, search the main frame and all descendant frames for editable inputs or selects matched directly or contained within matching elements. Each selector must resolve to one unique editable element across all frames; zero or multiple candidates fail. Count each element once, even if multiple matching containers contain it. Validate all bindings before filling. Select elements match an option by its value, not its label. If the page navigates or a target disappears during filling, stop rather than selecting a different page or element. Fill in request order and stop on the first failure. This operation is not atomic: previously filled fields are not rolled back. Never submit the form or click buttons, though input/change events may trigger site behavior. Fill is the preferred browser-checkout path. Aliases remain an alternative for explicitly chosen egress-substitution integrations. Do not automatically retry or fall back to aliases after a failed or indeterminate operation. Secret values are never returned or included in operation logs, traces, audit events, or error details. This does not prevent an agent with unrestricted browser access from reading values from the page or other browser observation surfaces. example: browser_id: browser-session-id fields: - field: number selector: '#card-number' - field: exp_month selector: '#expiry-month' - field: exp_year selector: '#expiry-year' - field: cvc selector: '#security-code' page_url: https://shop.example/checkout type: fill properties: browser_id: description: Browser session ID, not a reusable browser name. minLength: 1 type: string fields: description: >- Field bindings for this step. No two bindings may resolve to the same element. items: $ref: '#/components/schemas/VaultFillField' maxItems: 32 minItems: 1 type: array page_url: description: >- Exact current top-level page URL, including path, query, and fragment. Must match exactly one open page in the browser; zero or multiple matches fail. No prefix or glob matching. Required for cards, which must use HTTPS without embedded credentials. Optional for credentials, where omission requires exactly one open page. format: uri pattern: ^\S+$ type: string x-go-type-skip-optional-pointer: true timeout_ms: default: 10000 description: Total operation deadline in milliseconds, not a per-field timeout. maximum: 30000 minimum: 1 type: integer type: enum: - fill type: string required: - type - browser_id - fields type: object PrepareCheckoutVaultItemOperationRequest: additionalProperties: false description: >- Prepare an unused AgentCard card for Square checkout. Deliver the returned approval URL and keep the approval page open. Poll the item until ready_to_submit, then submit native Pay before preparation.expires_at. Readiness lasts at most 30 seconds. Unused preparations expire automatically. Preparations are single-use even after failure or expiry; do not automatically retry and reconcile uncertain outcomes with the merchant. properties: checkout: $ref: '#/components/schemas/VaultCheckoutContext' type: enum: - prepare_checkout type: string x-go-type: VaultItemOperationType required: - type - checkout type: object VaultItem: discriminator: mapping: card: $ref: '#/components/schemas/CardVaultItem' credential: $ref: '#/components/schemas/CredentialVaultItem' wallet: $ref: '#/components/schemas/WalletVaultItem' propertyName: type oneOf: - $ref: '#/components/schemas/WalletVaultItem' - $ref: '#/components/schemas/CardVaultItem' - $ref: '#/components/schemas/CredentialVaultItem' FillVaultItemOperationResult: additionalProperties: false properties: fields: description: >- Exactly one result per request binding, in request order. After the first failed or unknown field, all remaining fields are not_attempted. items: $ref: '#/components/schemas/VaultFillFieldResult' maxItems: 32 minItems: 1 type: array status: description: >- Completed only when all fields were filled. Failed when execution stopped with known outcomes. Unknown when any field's outcome cannot be determined. None of these statuses confirms payment or merchant acceptance. enum: - completed - failed - unknown type: string type: enum: - fill type: string required: - type - status - fields type: object Error: properties: code: description: Application-specific error code (machine-readable) example: bad_request type: string details: description: Additional error details (for multiple errors) items: $ref: '#/components/schemas/ErrorDetail' type: array inner_error: $ref: '#/components/schemas/ErrorDetail' message: description: Human-readable error description for debugging example: 'Missing required field: app_name' type: string required: - code - message type: object VaultFillField: additionalProperties: false properties: field: description: >- A declared credential field name or a supported card field. Unset credential fields cannot be filled. minLength: 1 type: string format: description: >- Required only for a card's combined expiration field. Forbidden for other card fields and all credential fields. enum: - MM/YY - MM/YYYY type: string selector: minLength: 1 type: string required: - field - selector type: object VaultCheckoutContext: additionalProperties: false description: >- Required when preparing an unused AgentCard card for Square. Consent is bound to this browser and declared merchant origin, not a tab. Wait for the item's ready_to_submit status before native Pay and submit within its readiness deadline. Unused preparations expire automatically; every preparation is single-use, including after failure or expiry. properties: browser_id: description: Active browser session with this vault bound to it. type: string environment: description: Square environment, independent of the AgentCard credential mode. enum: - production - sandbox type: string merchant_origin: description: >- Canonical HTTPS origin of the top-level merchant document, not the Square iframe. HTTP localhost is accepted for tests. type: string required: - browser_id - merchant_origin - environment type: object CardVaultItem: additionalProperties: false properties: action: $ref: '#/components/schemas/VaultItemAction' available_expansions: items: $ref: '#/components/schemas/AvailableVaultItemExpansion' type: array available_operations: items: $ref: '#/components/schemas/AvailableVaultItemOperation' type: array created_at: format: date-time type: string expires_at: format: date-time type: string id: type: string key: description: Immutable item key assigned when the item is created. type: string spec: $ref: '#/components/schemas/CardVaultItemSpec' state: $ref: '#/components/schemas/CardVaultItemState' type: enum: - card type: string updated_at: format: date-time type: string required: - id - key - type - spec - state - available_operations - available_expansions - created_at - updated_at type: object CredentialVaultItem: additionalProperties: false properties: action: $ref: '#/components/schemas/CredentialCollectionAction' available_expansions: items: $ref: '#/components/schemas/AvailableVaultItemExpansion' maxItems: 0 type: array available_operations: description: >- Advertises collect for ready and pending_collection items. Browser fill is advertised only when separately implemented and eligible. items: $ref: '#/components/schemas/AvailableVaultItemOperation' type: array created_at: format: date-time type: string id: type: string key: description: Immutable item key assigned when the item is created. type: string spec: $ref: '#/components/schemas/CredentialVaultItemSpec' state: $ref: '#/components/schemas/CredentialVaultItemState' type: enum: - credential type: string updated_at: format: date-time type: string version: description: >- Starts at 1 and increments on PATCH and successful hosted submission, but not collection-link renewal. minimum: 1 type: integer required: - id - key - type - version - spec - state - available_operations - available_expansions - created_at - updated_at type: object WalletVaultItem: additionalProperties: false properties: action: $ref: '#/components/schemas/VaultItemAction' available_expansions: items: $ref: '#/components/schemas/AvailableVaultItemExpansion' type: array available_operations: items: $ref: '#/components/schemas/AvailableVaultItemOperation' type: array created_at: format: date-time type: string expanded: $ref: '#/components/schemas/VaultItemExpanded' expires_at: format: date-time type: string id: type: string key: description: Immutable item key assigned when the item is created. type: string spec: $ref: '#/components/schemas/WalletVaultItemSpec' state: $ref: '#/components/schemas/WalletVaultItemState' type: enum: - wallet type: string updated_at: format: date-time type: string required: - id - key - type - spec - state - available_operations - available_expansions - created_at - updated_at type: object VaultFillFieldResult: additionalProperties: false properties: error_code: description: >- Present only for failed or unknown fields. Never includes secret values, DOM content, or raw browser errors. enum: - target_changed - element_not_found - ambiguous_selector - element_not_editable - option_not_found - timeout - execution_failed type: string index: description: Zero-based index into the request fields array. maximum: 31 minimum: 0 type: integer status: description: >- Filled means the fill action completed, not that the website retained or accepted the value. enum: - filled - failed - not_attempted - unknown type: string required: - index - status type: object ErrorDetail: properties: code: description: Lower-level error code providing more specific detail example: invalid_input type: string message: description: Further detail about the error example: Provided version string is not semver compliant type: string type: object VaultItemAction: discriminator: mapping: card_enrollment: $ref: '#/components/schemas/CardEnrollmentAction' collect: $ref: '#/components/schemas/CollectAction' embedded_ceremony: $ref: '#/components/schemas/EmbeddedCeremonyAction' link_oauth: $ref: '#/components/schemas/LinkOAuthAction' mfa: $ref: '#/components/schemas/MfaAction' push_approval: $ref: '#/components/schemas/PushApprovalAction' spend_approval: $ref: '#/components/schemas/SpendApprovalAction' propertyName: name oneOf: - $ref: '#/components/schemas/LinkOAuthAction' - $ref: '#/components/schemas/SpendApprovalAction' - $ref: '#/components/schemas/PushApprovalAction' - $ref: '#/components/schemas/CollectAction' - $ref: '#/components/schemas/MfaAction' - $ref: '#/components/schemas/EmbeddedCeremonyAction' - $ref: '#/components/schemas/CardEnrollmentAction' AvailableVaultItemExpansion: additionalProperties: false description: >- Live data that can currently be requested by passing its type to the item GET expand parameter. properties: description: type: string type: $ref: '#/components/schemas/VaultItemExpansionType' required: - type - description type: object AvailableVaultItemOperation: additionalProperties: false description: >- An operation that is currently valid for this item. Read the description before invoking it through the item operations endpoint. properties: description: type: string type: $ref: '#/components/schemas/VaultItemOperationType' required: - type - description type: object CardVaultItemSpec: discriminator: mapping: agentcard: $ref: '#/components/schemas/AgentCardCardVaultItemSpec' link: $ref: '#/components/schemas/LinkCardVaultItemSpec' propertyName: provider oneOf: - $ref: '#/components/schemas/LinkCardVaultItemSpec' - $ref: '#/components/schemas/AgentCardCardVaultItemSpec' CardVaultItemState: discriminator: mapping: agentcard: $ref: '#/components/schemas/AgentCardCardState' link: $ref: '#/components/schemas/LinkCardState' propertyName: provider oneOf: - $ref: '#/components/schemas/LinkCardState' - $ref: '#/components/schemas/AgentCardCardState' CredentialCollectionAction: additionalProperties: false description: > One schema-derived form for the item, available in ready or pending_collection state. Render every form-supported field as editable; omit totp fields and preserve their stored seeds. Prefill non-sensitive values, and allow existing sensitive values to be preserved or replaced without ever revealing them. No field subsets or per-request form configuration exist. Validate required fields against the resulting values, including preserved secrets. Submit changed values only, using the version used to render the form. Scoped hosted submission rejects totp edits; seed writes require the ordinary authenticated item API. Customer forms likewise omit totp from their payloads. Save edits atomically. A successful hosted submission increments the version, marks ready, and consumes the session; an empty edit may complete collection while preserving values. A customer form uses PATCH for changed values and does not send an empty PATCH when nothing changed. Kernel-hosted bearer sessions require no Kernel account and are bound to the item version. Expired, superseded, consumed, or deleted-item sessions cannot submit. Authenticated item GET renews expired active sessions for ready or pending items; pending items always receive an action. A ready item with no active session omits the action until collect is invoked. Concurrent renewals return the same link. Renewal changes neither values nor item version. An expired link cannot renew itself. The hosted form handles its collection protocol; callers only open the returned URL and do not extract or submit its token through the public API. For customer-hosted forms, use @onkernel/vault-react and an authenticated customer backend calling the ordinary item GET/PATCH API. Kernel does not store customer collection URLs or authenticate the customer's end users. Treat URLs and submitted values as secrets and exclude them from logs, traces, and errors. properties: expires_at: description: >- Expiry of the Kernel-hosted collection link (30 minutes after issuance). format: date-time type: string name: enum: - collect type: string url: description: >- Time-scoped hosted form URL (vault.kernel.sh in production). Open this URL as returned; treat it as a secret. format: uri type: string required: - name - url - expires_at type: object CredentialVaultItemSpec: additionalProperties: false properties: description: description: >- Recognizable site or service name displayed verbatim as the form title, without suffixes such as sign-in credentials. Display text only, not an enforced destination policy. maxLength: 16384 type: string fields: additionalProperties: $ref: '#/components/schemas/CredentialVaultFieldDefinition' maxProperties: 32 minProperties: 1 type: object required: - fields type: object CredentialVaultItemState: additionalProperties: false properties: fields: additionalProperties: $ref: '#/components/schemas/CredentialVaultFieldState' description: Exactly one entry for each declared field. minProperties: 1 type: object status: description: >- Ready means all required fields have values, not that a login succeeded. Optional fields may remain unset. enum: - pending_collection - ready type: string required: - status - fields type: object VaultItemExpanded: additionalProperties: false description: >- Live, non-persisted data requested through the item GET expand parameter. properties: payment_methods: items: $ref: '#/components/schemas/VaultPaymentMethod' type: array type: object WalletVaultItemSpec: discriminator: mapping: agentcard: $ref: '#/components/schemas/AgentCardWalletVaultItemSpec' link: $ref: '#/components/schemas/LinkWalletVaultItemSpec' propertyName: provider oneOf: - $ref: '#/components/schemas/LinkWalletVaultItemSpec' - $ref: '#/components/schemas/AgentCardWalletVaultItemSpec' WalletVaultItemState: discriminator: mapping: agentcard: $ref: '#/components/schemas/AgentCardWalletState' link: $ref: '#/components/schemas/LinkWalletState' propertyName: provider oneOf: - $ref: '#/components/schemas/LinkWalletState' - $ref: '#/components/schemas/AgentCardWalletState' CardEnrollmentAction: additionalProperties: false properties: name: enum: - card_enrollment type: string url: format: uri type: string required: - name - url type: object CollectAction: additionalProperties: false properties: name: enum: - collect type: string required: - name type: object EmbeddedCeremonyAction: additionalProperties: false properties: name: enum: - embedded_ceremony type: string required: - name type: object LinkOAuthAction: additionalProperties: false properties: name: enum: - link_oauth type: string url: format: uri type: string required: - name - url type: object MfaAction: additionalProperties: false properties: name: enum: - mfa type: string required: - name type: object PushApprovalAction: additionalProperties: false properties: name: enum: - push_approval type: string required: - name type: object SpendApprovalAction: additionalProperties: false properties: name: enum: - spend_approval type: string url: format: uri type: string required: - name - url type: object VaultItemExpansionType: enum: - payment_methods type: string VaultItemOperationType: enum: - authorize - collect - prepare_checkout - fill type: string AgentCardCardVaultItemSpec: additionalProperties: false description: >- AgentCard reusable live payment card. Test-mode card creation is not supported. Each checkout creates an approval-gated authorization for spec.merchant / spec.amount. The card stays ready after each authorization. properties: amount: description: Integer amount in minor currency units. format: int64 maximum: 9007199254740991 minimum: 1 type: integer card_id: description: >- AgentCard vaulted card to pay with. Omitted, the cardholder picks on the approval screen. pattern: ^vc_[A-Za-z0-9_]+$ type: string currency: maxLength: 3 minLength: 3 pattern: ^[A-Za-z]{3}$ type: string merchant: description: Merchant name shown on the cardholder's approval screen. maxLength: 120 minLength: 1 type: string provider: enum: - agentcard type: string wallet: description: Wallet item key used to authorize checkouts. type: string required: - provider - wallet - merchant - amount - currency type: object LinkCardVaultItemSpec: additionalProperties: false description: Live payment card. Test-mode card creation is not supported. properties: amount: description: Integer amount in minor currency units. maximum: 500000 minimum: 1 type: integer context: minLength: 100 type: string currency: maxLength: 3 minLength: 3 pattern: ^[A-Za-z]{3}$ type: string expires_at: format: int64 type: integer line_items: items: $ref: '#/components/schemas/LinkLineItem' type: array merchant_name: maxLength: 255 minLength: 1 type: string merchant_url: format: uri type: string metadata: additionalProperties: type: string type: object payment_method_id: description: >- Payment-method ID returned by the referenced wallet's payment-method listing. The provider decides whether the selected funding method can satisfy the card request. minLength: 1 type: string provider: enum: - link type: string totals: items: $ref: '#/components/schemas/LinkTotal' type: array wallet: description: Wallet item key used to mint this card. type: string required: - provider - wallet - payment_method_id - amount - currency - merchant_name - merchant_url - context type: object AgentCardCardState: additionalProperties: false properties: aliases: $ref: '#/components/schemas/VaultCardAliases' authorization: $ref: '#/components/schemas/AgentCardCheckoutAuthorization' masks: $ref: '#/components/schemas/VaultItemMasks' preparation: $ref: '#/components/schemas/AgentCardCheckoutPreparation' provider: enum: - agentcard type: string status: description: >- ready_to_submit is device readiness for at most 30 seconds. consumed means the prepared attempt has settled, not that an order succeeded. stopped cannot be reused. outcome_unknown requires merchant reconciliation and blocks new requests. recovery_required means the original checkout outcome is unresolved. Automatic reuse is blocked. Known authorization IDs must be reconciled through provider observations or support. When no authorization ID was returned, an explicitly confirmed item deletion may abandon the unresolved attempt so the caller can create a replacement; deletion does not prove that the original attempt failed. It does not mean declined or expired. enum: - requested - ready - preparing - ready_to_submit - pending_approval - consumed - stopped - outcome_unknown - degraded - recovery_required type: string status_reason: type: string required: - provider - status type: object LinkCardState: additionalProperties: false properties: aliases: $ref: '#/components/schemas/VaultCardAliases' domains: items: type: string type: array masks: $ref: '#/components/schemas/VaultItemMasks' provider: enum: - link type: string status: description: >- recovery_required means an original provider operation has an unresolved outcome. Do not retry, delete, or replace it. Known references may be observed safely, but unknown creation without an ID and uncertain card-material retrieval require manual reconciliation with the provider or support. There is no reset or caller-asserted reconciliation operation. enum: - requested - pending_authorization - ready - consumed - expired - declined - recovery_required type: string status_reason: type: string required: - provider - status type: object CredentialVaultFieldDefinition: additionalProperties: false properties: required: description: >- Whether a nonempty value is required for readiness and form submission. type: boolean sensitive: description: >- Whether the value is omitted from every item response. Reserve true for secrets such as passwords, API tokens, and TOTP seeds. Ordinary usernames and email addresses should be false so the form can display and prefill them. type: boolean type: $ref: '#/components/schemas/CredentialVaultFieldType' required: - type - required - sensitive type: object CredentialVaultFieldState: additionalProperties: false properties: has_value: type: boolean value: description: >- Present exactly when has_value is true and the field is not sensitive. Reflects the latest developer or human edit. For totp, has_value indicates a stored seed; neither the seed nor a generated code is returned. minLength: 1 type: string required: - has_value type: object VaultPaymentMethod: additionalProperties: false properties: capabilities: $ref: '#/components/schemas/VaultPaymentMethodCapabilities' display: $ref: '#/components/schemas/VaultPaymentMethodDisplay' id: type: string is_default: type: boolean provider: description: Provider that issued this payment-method ID. type: string type: description: Provider-neutral payment-method type normalized to lowercase. type: string required: - id - provider - type - is_default - display - capabilities type: object AgentCardWalletVaultItemSpec: additionalProperties: false description: >- AgentCard wallet. Omit provider_config to use Kernel-managed credentials, or select a customer-owned configuration. Mode (sandbox vs live) is determined by the selected credential; there is no per-item test flag. Without user_id, creation returns a hosted enrollment action and Kernel polls until the user connects. user_id may only reference a user already enrolled by a wallet in this organization under the same configuration. properties: provider: enum: - agentcard type: string provider_config: $ref: '#/components/schemas/VaultProviderConfigReference' description: >- Select an AgentCard configuration. The wallet's configuration cannot be changed after creation. user_id: pattern: ^usr_[A-Za-z0-9_]+$ type: string required: - provider type: object LinkWalletVaultItemSpec: additionalProperties: false properties: authorization: $ref: '#/components/schemas/LinkOAuthAuthorization' provider: enum: - link type: string required: - provider - authorization type: object AgentCardWalletState: additionalProperties: false properties: provider: enum: - agentcard type: string status: enum: - pending_authorization - connected - degraded type: string status_reason: type: string user_id: description: AgentCard user id linked to this wallet. Present once connected. type: string required: - provider - status type: object LinkWalletState: additionalProperties: false properties: provider: enum: - link type: string status: enum: - pending_authorization - connected - declined - reconnect_required - degraded type: string status_reason: type: string required: - provider - status type: object LinkLineItem: additionalProperties: false properties: description: type: string image_url: type: string name: type: string product_url: type: string quantity: minimum: 1 type: integer sku: type: string totals: items: $ref: '#/components/schemas/LinkTotal' type: array unit_amount: description: Unit amount in minor currency units. type: integer url: type: string required: - name type: object LinkTotal: additionalProperties: false properties: amount: description: Total amount in minor currency units. type: integer display_text: type: string type: type: string required: - type - display_text - amount type: object VaultCardAliases: additionalProperties: false properties: cvc: pattern: ^\d{3}$ type: string exp_month: pattern: ^\d{2}$ type: string exp_year: pattern: ^\d{4}$ type: string number: pattern: ^\d{16}$ type: string readOnly: true required: - number - cvc - exp_month - exp_year type: object AgentCardCheckoutAuthorization: additionalProperties: false description: >- The in-flight or most recent checkout authorization. Present while a checkout is pending approval and after it settles. properties: actual_cents: format: int64 type: integer amount: description: Display amount shown on the approval screen. type: string amount_authority: enum: - display_only - stripe_payment_intent type: string amount_cents: format: int64 type: integer amount_verified: type: boolean approval_url: format: uri type: string browser_id: description: Browser session that submitted the checkout. type: string charged_amount_cents: format: int64 type: integer charged_currency: type: string charged_kind: enum: - captured - authorized - none type: string created_at: format: date-time type: string currency: type: string expected_cents: format: int64 type: integer expires_at: format: date-time type: string id: type: string merchant: type: string psp: type: string psp_error_code: type: string reason: type: string replay_attempted: type: boolean replay_delivered: description: Whether the processor response was delivered to the browser. type: boolean replay_status: description: HTTP status of the replayed processor response. type: integer status: enum: - awaiting_approval - approved - declined - expired type: string required: - id - status - psp - merchant - amount_cents - currency - created_at type: object VaultItemMasks: additionalProperties: type: string properties: brand: type: string last4: maxLength: 4 minLength: 4 type: string type: object AgentCardCheckoutPreparation: additionalProperties: false description: >- One-use Square checkout preparation. Keep the approval page open through token handoff. The amount is display-only and does not constrain the merchant's eventual charge. properties: approval_url: format: uri type: string browser_id: type: string created_at: format: date-time type: string environment: enum: - production - sandbox type: string expires_at: description: >- When ready, the absolute deadline to submit the first native request; no later than provider readiness expiry or 30 seconds after Kernel first observes readiness. Polling never extends this deadline. format: date-time type: string id: type: string merchant_origin: type: string status: description: >- Preparation consumed means egress claimed the preparation and it cannot be reused. It does not mean the attempt settled. Use the enclosing item's status as the lifecycle indicator; item consumed means the attempt settled, not that an order or charge succeeded. enum: - creating - awaiting_approval - ready - consumed - cancelled - expired - unknown type: string required: - status - browser_id - merchant_origin - environment - created_at type: object CredentialVaultFieldType: description: > Text, email, and password have form inputs; totp does not and is omitted from both Kernel-hosted and customer React forms. Password and totp must be sensitive. A totp value is an RFC 4648 Base32 generator seed (case-insensitive, optional trailing padding), not an otpauth URI or current code. Reject invalid or empty decoded seeds. Browser fill generates an RFC 6238 code at execution time using HMAC-SHA1, 6 digits, and a 30-second period. Preserve leading zeros; never fill the seed. Custom algorithms, digits, periods, and form enrollment are unsupported. enum: - text - email - password - totp type: string VaultPaymentMethodCapabilities: additionalProperties: false description: >- Provider-reported advisory capabilities. A missing capability is unknown, not ineligible; only eligible=false is an explicit negative signal. properties: single_use_card: $ref: '#/components/schemas/VaultPaymentMethodCapability' type: object VaultPaymentMethodDisplay: additionalProperties: false properties: brand: type: string label: type: string last4: type: string type: object VaultProviderConfigReference: additionalProperties: false description: >- Select a provider config by ID or name. Responses return the ID. Renaming a config does not change existing wallet bindings; a wallet cannot switch to a different config after creation. oneOf: - required: - id - required: - name properties: id: minLength: 1 type: string name: pattern: ^[a-zA-Z0-9._-]{1,255}$ type: string type: object LinkOAuthAuthorization: additionalProperties: false properties: client: $ref: '#/components/schemas/LinkOAuthClient' method: enum: - oauth type: string required: - method - client type: object VaultPaymentMethodCapability: additionalProperties: false properties: eligible: type: boolean reasons: items: type: string type: array required: - eligible - reasons type: object LinkOAuthClient: discriminator: mapping: customer_managed: $ref: '#/components/schemas/CustomerManagedOAuthClient' kernel_managed: $ref: '#/components/schemas/KernelManagedOAuthClient' propertyName: type oneOf: - $ref: '#/components/schemas/KernelManagedOAuthClient' - $ref: '#/components/schemas/CustomerManagedOAuthClient' CustomerManagedOAuthClient: additionalProperties: false properties: provider_config: $ref: '#/components/schemas/VaultProviderConfigReference' type: enum: - customer_managed type: string required: - type - provider_config type: object KernelManagedOAuthClient: additionalProperties: false properties: type: enum: - kernel_managed type: string required: - type type: object examples: ExampleLinkApproval: summary: >- Link authorization creates or resumes a spend awaiting cardholder approval value: action: name: spend_approval url: https://example.com/spend-approval available_expansions: [] available_operations: - description: >- Resume this existing spend request without creating another payment. type: authorize created_at: '2026-01-01T12:00:00Z' expires_at: '2026-01-01T13:00:00Z' id: card_link_example key: link-card spec: amount: 2599 context: >- Purchase one notebook for USD 25.99 including shipping and taxes. This is a new order at Example Store, not a retry of an earlier payment. currency: usd merchant_name: Example Store merchant_url: https://store.example.com payment_method_id: pm_example provider: link wallet: link-wallet state: domains: - store.example.com provider: link status: pending_authorization type: card updated_at: '2026-01-01T12:01:00Z' responses: BadRequest: content: application/json: schema: $ref: '#/components/schemas/Error' description: Bad Request – invalid input Unauthorized: content: application/json: schema: $ref: '#/components/schemas/Error' description: Unauthorized – missing or invalid authorization token Forbidden: content: application/json: schema: $ref: '#/components/schemas/Error' description: Forbidden – insufficient permissions or plan NotFound: content: application/json: schema: $ref: '#/components/schemas/Error' description: Resource not found Conflict: content: application/json: schema: $ref: '#/components/schemas/Error' description: Conflict – resource already exists TooManyRequests: content: application/json: schema: $ref: '#/components/schemas/Error' description: Too Many Requests – rate limit exceeded headers: Retry-After: description: Seconds to wait before retrying schema: type: integer InternalError: content: application/json: schema: $ref: '#/components/schemas/Error' description: Internal Server Error securitySchemes: bearerAuth: scheme: bearer type: http ````