Create or retrieve an identical vault item by immutable key

Create an item under a key unique within its vault, or retrieve the existing item when its specification matches. An identical card PUT returns the existing card in any lifecycle state without polling the provider, reauthorizing, replacing aliases, or resetting recovery. Conflicting specifications return 409. Provider-specific authorization requirements and retry behavior are described in the item’s request schema. Do not use credential items to store, collect, or fill credit card data, including card numbers (PANs), security codes (CVV/CVC), or expiration dates. Use wallet and card item types for credit cards and payment checkout instead.

PUT /vaults/{id_or_name}/items/{key}

cURL

agentcard_card

curl --request PUT \
  --url https://api.onkernel.com/vaults/{id_or_name}/items/{key} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "spec": {
    "amount": 2599,
    "card_id": "vc_example",
    "currency": "usd",
    "merchant": "Example Store",
    "provider": "agentcard",
    "wallet": "agentcard-wallet"
  },
  "type": "card"
}
'

200

agentcard_card

{
  "available_expansions": [],
  "available_operations": [
    {
      "description": "Prepare this unused AgentCard card before the first Square Pay action. POST to this item's operations endpoint with a body like {\"type\":\"prepare_checkout\",\"checkout\":{\"browser_id\":\"<browser-session-id>\",\"merchant_origin\":\"https://shop.example.com\",\"environment\":\"production\"}}. Use the active browser session with this vault bound. merchant_origin is the top-level merchant document's origin, not the Square iframe. environment must be production or sandbox and describes Square, not the AgentCard credential mode. 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. Preparation is single-use, including after failure or expiry. Do not automatically retry; reconcile uncertain outcomes with the merchant.",
      "type": "prepare_checkout"
    }
  ],
  "created_at": "2026-01-01T12:00:00Z",
  "id": "card_agentcard_example",
  "key": "agentcard-card",
  "spec": {
    "amount": 2599,
    "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-01T12:00:00Z"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id_or_name · string · required

key · string · required

Required string length: 1 - 255

Body

application/json

Option 1

Option 2

Option 3

spec · object · required

Option 1

Option 2

Show child attributes

type · enum<string> · required

Available options: wallet

Response

200

application/json

Existing matching item; card retries preserve identity and state

Option 1

Option 2

Option 3

available_expansions · object[] · required

Show child attributes

available_operations · object[] · required

Show child attributes

created_at · string<date-time> · required

id · string · required

key · string · required

Immutable item key assigned when the item is created.

spec · object · required

Option 1

Option 2

Show child attributes

state · object · required

Option 1

Option 2

Show child attributes

type · enum<string> · required

Available options: wallet

updated_at · string<date-time> · required

action · object

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 7

Show child attributes

expanded · object

Live, non-persisted data requested through the item GET expand parameter.

Show child attributes

expires_at · string<date-time>