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

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

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

Vaults

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

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

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

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

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

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

Show child attributes

expanded

object

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

Show child attributes

expires_at

string<date-time>

Apps

Audit Logs

Managed Auth

Authentication

Browser Pools

Browsers

Browser Computer Controls

Browser Filesystem

Browser Logs

Browser Playwright

Browser Processes

Browser Replays

Browser Telemetry

Browser WebMCP

Deployments

Extensions

Invocations

API Keys

Organization

Projects

Profiles

Proxies

Vaults

Perform an operation advertised by a vault item

Authorizations

Path Parameters

Body

Response