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 may call an external provider and returns the updated item. Link cards advertise authorize when eligible. AgentCard cards are created with PUT and request approval when their aliases are used at checkout; they do not expose authorize. 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

Perform an operation advertised by a vault item

cURL

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 '
{
  "type": "authorize"
}
'

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

type · enum<string> · required

Available options: authorize

Response

200

application/json

Authorization completed or resumed, or fill execution outcomes returned

Option 1

Option 2

Option 3

Authorization returns 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>