Admit a run against an immutable version and funded grant
const url = 'https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/environments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/runs';const options = { method: 'POST', headers: { 'Idempotency-Key': 'example', 'X-Katara-CSRF': '1', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '"example"'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/environments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/runs \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: example' \ --header 'X-Katara-CSRF: 1' \ --data '"example"'Available when the corresponding service is configured. Preserve the same idempotency key after an uncertain response. The returned operation resource_id identifies the committed version or run; run acceptance does not mean execution succeeded.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Header Parameters
Section titled “Header Parameters”Browser cookie mutations require value 1 and an allowed Origin. Session bearer clients may omit this header.
Required for cookie-authenticated changes. Use the UUID of the account that loaded the application. A different current cookie account returns account_changed before the handler runs. Session bearer and API key clients do not require this header.
Base64 of a signed x402 payment answering this request’s challenge. Only for a run on a budget paid per run with x402, started with an API key that an owner allowed to pay with x402. One payment starts one run; sending it again returns the same run.
Request Bodyrequired
Section titled “Request Bodyrequired”Model, tools, schemas and limits come from the immutable agent version. Paid Test Compute requires the exact consent funding the grant budget; the API checks it against current payer authority.
object
object
object
Explicit destination for run artifacts. Store and key versions must still be active at admission and byte access. Choose retention from 60 seconds to 365 days; no silent default or destination substitution.
object
object
Responses
Section titled “Responses”Successful request
object
Examplegenerated
{ "operation_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "resource_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "completed": true}X402_payment_required: the run’s budget is paid per run with x402 and the request carried no payment. The body, and base64 in the PAYMENT-REQUIRED header, is the run’s challenge: one entry per scheme, upto first, each for the run’s maximum. Sign one and send the same request again with the payment in the PAYMENT-SIGNATURE header. payment_invalid: the payment did not verify, has expired or answers another request’s challenge. x402_insufficient_funds: the wallet does not cover this run with the other runs it is paying for.
An x402 version 2 challenge for one run: one entry per scheme, upto first, each for the run’s maximum.
object
object
object
Scheme details and the binding of this challenge to its run request, signed back with the payment.
object
object
object
Example
{ "x402Version": 2, "resource": { "mimeType": "application/json" }, "accepts": [ { "scheme": "upto" } ]}Headers
Section titled “Headers”Base64 of the x402 challenge, as in the body.
X402_key_required: a run paid with x402 is started with an API key. x402_not_enabled: x402 payment is off for the key, or the paying wallet is not one it lists.
Account_changed: reload and review with the signed-in account; wallet_insufficient_funds, wallet_payment_failed, wallet_unpaid_limit: a run on a wallet budget was refused because of its wallet. x402_budget_in_use: another paid run holds the x402 budget. x402_payment_required: the budget is paid per run and cannot be used without a payment.
X402_wallet_run_limit: the wallet is already paying for as many runs as it may at once.
default
Section titled “default”Request error
object
object
Stable; branch on it. Any operation can answer invalid_request, with param naming the refused field when there is one; human_session_required, when an API key, service account or workload calls an operation only a signed-in person may perform; reauthentication_required, when a person’s sign-in is too old for the operation; permission_denied; route_not_found and method_not_allowed, when no operation matches the path or method; and feature_unavailable, when the operation’s service is not enabled on this deployment.
The request field a refusal is about, such as the agent_id or run_id query parameter; null when the refusal is not about one field.
Example
{ "error": { "action": "sign_in" }}