Making calls

Every catalog action uses the same endpoint shape and the same response envelope. Each service page documents its 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 tells you whether the upstream call succeeded. When it is false, charged_cents is 0.
data is the upstream result, passed through.
charged_cents is what the call actually cost.
balance_remaining_cents is your credit balance after the call.
transaction_id is the receipt. Every call is itemized at /balance.

Cost guards

Pass max_cost_cents in the body of any call to set a price ceiling. It is a guard, not the charge. If the price would exceed it, the call is rejected before anything runs and nothing is billed. Set it at or slightly above the listed price. Vaaya reads and removes the field. It is never sent to the provider.

Idempotent retries

Send an Idempotency-Key header to make retries safe. A repeated key replays the original result instead of re-running 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

Some expensive actions are asynchronous. The first call returns a handle immediately, and you poll a companion status action. Polling is free. Each service page documents the pattern where it applies.