Call an explicitly selected capability
capability_callCall one capability by id at its listed price. Leave payment_path out to pay from the key's call credits, else its balance within its spending limits (spend_limits_set). The result is checked against the part's output contract; nothing is charged when it does not match. When the check passes and the money covers the price, the call is paid and the whole result comes back with check (the verdict) and delivery. When an agent key's money does not cover it, or with auto_pay false (agent keys and balance calls only), the part still runs and its result is held: state locked, result null, the check verdict and a sample (a few rows, at most a fifth of them; a result of under 5 rows shows only its field names), locked_reason_text (a hold by the spending limit names the payment, the limit and the month's spending), unlock steps (raise_limit first for a spending-limit hold), and pay_link: a page for exactly that call's price that a person pays by card with no account (send them pay_link.for_a_person); once paid the result unlocks on its own. capability_call_unlock pays for it from the key and returns all of it within 72 hours; a key holds at most 5 such results at once. A part that acts in the world (acceptance.acts_in_world: it sends or calls) runs only when the call is paid, from the key's balance: no held result, no preview, no x402. One call is paid from the call credits or from the balance, never split. A refusal carries next, the request to send instead. A failed call is never charged; what_happened says what went wrong (the part's server, not an answer from the record it reads), with supplier_http_status, supplier_message and supplier_error_code (the part's own reason and code), refund (nothing_to_refund or returned), safe_to_retry, retry_after_seconds and next (retry under a new idempotency_key when trying again may work, change_input when the same input would fail the same way, other_parts, ask_for_it); a part that does not serve this caller says so with access_refused true and safe_to_retry false. An input that does not fit the part's input_schema is refused before anything runs (invalid_input with problems: each field, what is wrong and the values it allows). With no key at all a free agent key is made and returned once as agent_key (the lk_ key; keep it); past the per-address cap, next.get_a_key is agent_register (free). A part still running after about 45 seconds answers state running with read steps (capability_call_get). Every answer about a call says charged, amount_charged_usd, payment and balance_after_usd the same way; a replay of a charged call (replayed true) says charged false and amount_charged_usd 0 with already_charged true and charged_on_first_answer_usd, so count that charge once. A result the part marks not charged (not_charged) is handed over whole and free; a held result's sample may be the part's own preview of what it read. A part with a review window (acceptance.review_window_hours in capability_get) hands over the whole result with delivery.state in_review: object with capability_call_dispute before review_ends_at, or it is accepted and its supplier is paid. Available referral credit is applied automatically first on x402. payment_path x402 needs agent_key; balance needs agent_key or api_key; upstream needs agent_key, parent_call_id, and composition_token, is charged to the parent supplier, and is one level only. A 402 challenge is returned as data. Unpaid x402 reservations expire after one hour; retry with a new idempotency_key.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes | ||
| api_key | No | Optional alternative to agent_key for balance calls. | |
| auto_pay | No | Default true. false (agent_key, balance calls only): see the check and a sample first; the result is held until capability_call_unlock. Refused with next for an API key, an x402 call or a part that acts in the world. With both keys and auto_pay false, agent_key is used. | |
| agent_key | No | Required for x402 and upstream. | |
| payment_path | No | Leave it out to pay from balance. | |
| capability_id | Yes | Explicit capability UUID. | |
| parent_call_id | No | Required for upstream. | |
| idempotency_key | No | Optional. Left out, one is made and returned as idempotency_key; send that value again to retry the same call without running or paying for it twice. Required for upstream. | |
| composition_token | No | Required for upstream; supplied to the parent capability endpoint for this dispatch. | |
| idempotent_replay | No | Set true only for an explicit same-call-id replay after an uncertain upstream dispatch. |