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.

POST /vaults/{id_or_name}/items/{key}/operations

cURL

agentcard_prepare_checkout

curl --request POST \
  --url https://api.onkernel.com/vaults/{id_or_name}/items/{key}/operations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "checkout": {
    "browser_id": "browser-session-id",
    "environment": "production",
    "merchant_origin": "https://shop.example.com"
  },
  "type": "prepare_checkout"
}
'

200

{
  "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"
}

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

Body

application/json

Option 1

Option 2

Option 3

Option 4

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.

type · enum<string> · required

Available options: authorize

Response

200

application/json

Authorization or preparation completed or resumed, or fill execution outcomes returned

Option 1

Option 2

Option 3

Option 4

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.

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>