Making calls

Every catalog action shares one endpoint shape and one response envelope. Learn it once and every service page in this reference is just params and prices.

The endpoint

POST https://vaaya.ai/api/run/{service}/{action}
Authorization: Bearer vaaya_sk_...
Content-Type: application/json

{ ...the action's params... }

The params body is specific to each action — every service page documents them, and GET /api/run/{service}/{action} returns the machine-readable schema.

The response envelope

{
  "ok": true,
  "data": { ... },
  "charged_cents": 1,
  "balance_remaining_cents": 1843,
  "transaction_id": "tx_..."
}

ok — whether the upstream call succeeded. On false, charged_cents is 0.
data — the upstream result, passed through.
charged_cents — what this call actually cost you.
balance_remaining_cents — your credit balance after the call.
transaction_id — the receipt; every call is itemized at /balance.

Cost guards

Pass max_cost_cents in the body of any call to set a ceiling. It is a guard, not the charge — the call is rejected up front (nothing runs, nothing is billed) if the price would exceed it. Set it at or slightly above the listed price so a vendor-side price change can never surprise you.

Idempotent retries

Send an Idempotency-Key header to make retries safe: a repeated key replays the original result instead of re-running (and re-billing) the call. Use it on any call you might retry after a timeout.

curl -X POST https://vaaya.ai/api/run/exa/search \
  -H "Authorization: Bearer $VAAYA_API_KEY" \
  -H "Idempotency-Key: 9f2c1a" \
  -H "Content-Type: application/json" \
  -d '{"query": "site reliability postmortem examples"}'

Async actions

A few expensive actions are asynchronous: the first call returns a handle (a run_id or job_id) immediately, and you poll a companion status action — polling is free. The pattern is documented on each service page where it applies (deep research tasks, long renders, crawls).