> ## Documentation Index > Fetch the complete documentation index at: https://tbd-6fc993ce-hypeship-process-execution-guide.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Update a card specification > Requested cards accept a replacement specification. Pending issuance requests may update provider-supported fields on their existing request, subject to atomic provider approval checks; omitted optional fields remain unchanged and explicit empty lists clear them. Wallet/provider binding and unsupported fields cannot change after authorization starts. An uncertain update enters recovery_required and must not be retried. Checkout cards may be edited between authorizations. ## OpenAPI ````yaml https://api.onkernel.com/spec.json patch /vaults/{id_or_name}/items/{key} 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}: parameters: - in: path name: id_or_name required: true schema: type: string - in: path name: key required: true schema: maxLength: 255 minLength: 1 type: string patch: tags: - Vaults summary: Update a card specification description: >- Requested cards accept a replacement specification. Pending issuance requests may update provider-supported fields on their existing request, subject to atomic provider approval checks; omitted optional fields remain unchanged and explicit empty lists clear them. Wallet/provider binding and unsupported fields cannot change after authorization starts. An uncertain update enters recovery_required and must not be retried. Checkout cards may be edited between authorizations. operationId: patchVaultItem requestBody: content: application/json: examples: agentcard: $ref: '#/components/examples/ExampleAgentCardCardEdit' link: $ref: '#/components/examples/ExampleLinkCardEdit' schema: $ref: '#/components/schemas/VaultItemUpdateRequest' required: true responses: '200': content: application/json: examples: agentcard: $ref: '#/components/examples/ExampleAgentCardCardUpdated' link: $ref: '#/components/examples/ExampleLinkCardUpdated' schema: $ref: '#/components/schemas/VaultItem' description: Vault item updated '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalError' security: - bearerAuth: [] components: examples: ExampleAgentCardCardEdit: summary: Set the reusable checkout card to USD 30.00 between authorizations value: spec: amount: 3000 card_id: vc_example currency: usd merchant: Example Store provider: agentcard wallet: agentcard-wallet ExampleLinkCardEdit: summary: Set an unapproved Link card request to USD 30.00 value: spec: amount: 3000 context: >- The order total changed to USD 30.00 including shipping and taxes for one notebook. Update this unapproved request rather than creating a second payment. currency: usd merchant_name: Example Store merchant_url: https://store.example.com payment_method_id: pm_example provider: link wallet: link-wallet ExampleAgentCardCardUpdated: summary: >- Updated checkout amount retains the same card identity and synthetic aliases value: available_expansions: [] available_operations: [] created_at: '2026-01-01T12:00:00Z' id: card_agentcard_example key: agentcard-card spec: amount: 3000 card_id: vc_example currency: usd merchant: Example Store provider: agentcard wallet: agentcard-wallet state: aliases: cvc: '123' exp_month: '12' exp_year: '2030' number: '4242424242424242' provider: agentcard status: ready type: card updated_at: '2026-01-02T12:00:00Z' ExampleLinkCardUpdated: summary: Updated Link request retains its key and ID value: available_expansions: [] available_operations: - description: Request cardholder approval for this payment. type: authorize created_at: '2026-01-01T12:00:00Z' id: card_link_example key: link-card spec: amount: 3000 context: >- The order total changed to USD 30.00 including shipping and taxes for one notebook. Update this unapproved request rather than creating a second payment. currency: usd merchant_name: Example Store merchant_url: https://store.example.com payment_method_id: pm_example provider: link wallet: link-wallet state: provider: link status: requested type: card updated_at: '2026-01-02T12:00:00Z' schemas: VaultItemUpdateRequest: additionalProperties: false properties: spec: $ref: '#/components/schemas/CardVaultItemSpec' required: - spec type: object VaultItem: discriminator: mapping: card: $ref: '#/components/schemas/CardVaultItem' wallet: $ref: '#/components/schemas/WalletVaultItem' propertyName: type oneOf: - $ref: '#/components/schemas/WalletVaultItem' - $ref: '#/components/schemas/CardVaultItem' CardVaultItemSpec: discriminator: mapping: agentcard: $ref: '#/components/schemas/AgentCardCardVaultItemSpec' link: $ref: '#/components/schemas/LinkCardVaultItemSpec' propertyName: provider oneOf: - $ref: '#/components/schemas/LinkCardVaultItemSpec' - $ref: '#/components/schemas/AgentCardCardVaultItemSpec' 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 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 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 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 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 CardVaultItemState: discriminator: mapping: agentcard: $ref: '#/components/schemas/AgentCardCardState' link: $ref: '#/components/schemas/LinkCardState' propertyName: provider oneOf: - $ref: '#/components/schemas/LinkCardState' - $ref: '#/components/schemas/AgentCardCardState' 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' 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 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 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 type: string AgentCardCardState: additionalProperties: false properties: aliases: $ref: '#/components/schemas/VaultCardAliases' authorization: $ref: '#/components/schemas/AgentCardCheckoutAuthorization' masks: $ref: '#/components/schemas/VaultItemMasks' provider: enum: - agentcard type: string status: description: >- 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 - pending_approval - 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 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 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 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 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 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 InternalError: content: application/json: schema: $ref: '#/components/schemas/Error' description: Internal Server Error securitySchemes: bearerAuth: scheme: bearer type: http ````