Discover and invoke services

An agent uses Varis in two steps: it searches for a service, and then it invokes the service. This page covers both through the HTTP API.

If your agent uses MCP, the search_services and invoke_service tools do the same two things with the same rules.

Every request needs an agent key in the Authorization header. For more information, see Headless agents.

Search for servicesCopy Anchor Link

Send a GET request to /v1/services:

curl "https://api.usevaris.com/v1/services?q=convert+currency&max_price_cents=5" \
  -H "Authorization: Bearer $VARIS_AGENT_KEY"

The response lists the matching services in data. Choose one by its description, instructions, price_usd, and input_schema, and then copy its id. price_usd is what one call costs, including the 5% Varis fee, and max_price_cents filters on that same amount.

For every parameter and response field, see Search published servicesAPI.

Invoke a serviceCopy Anchor Link

Send a POST request to /v1/invoke:

curl https://api.usevaris.com/v1/invoke \
  -H "Authorization: Bearer $VARIS_AGENT_KEY" \
  -H "Idempotency-Key: 5f0c2c1e-9b0e-4a77-8a52-3d1d1a2f0b6e" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "var_serv_ydZfZ9gKKe1tQe",
    "input": { "from": "USD", "to": "EUR", "amount": 100 }
  }'

You always call Varis with POST, whatever method the service uses. Varis sends the input to the service the right way.

If the call succeeds, Varis returns 200, and the service's result is in output. For every field and response, see Invoke a serviceAPI.

You pay only for calls that return 200.

Retry safely with an idempotency keyCopy Anchor Link

Every call needs an Idempotency-Key header. Use a new, unique value, such as a UUID, for each call you mean to make.

If a call times out or your connection drops, retry it with the same key. Varis recognises the key and doesn't charge you twice:

• If the first call is still running, Varis returns 409 with invocation_in_progress. Wait, and then retry with the same key.
• If the first call failed, Varis returns the same error again.
• If the first call succeeded, Varis returns 200 with "replayed": true, but not the output. Keep the output from the first response if you need it.

If you reuse a key for a different service, Varis returns 409 with conflict.

Handle errorsCopy Anchor Link

Every error has the same shape:

{
  "error": {
    "code": "input_schema_violation",
    "message": "The input does not match the service's input schema.",
    "details": [{ "path": "/amount", "message": "must be number" }]
  },
  "request_id": "var_req_fc8e8702-6a7f-4f3f-9147-748936e5fee1"
}

Insufficient fundsCopy Anchor Link

If your balance can't cover a call, Varis returns 402 with a funding link:

{
  "error": {
    "code": "insufficient_funds",
    "message": "The balance does not cover this call.",
    "shortfall_credits": 150,
    "funding_url": "https://usevaris.com/fund/t/abc123"
  },
  "request_id": "var_req_fc8e8702-6a7f-4f3f-9147-748936e5fee1"
}

Show funding_url to a person exactly as it is. Anyone who opens it can top up your balance, without signing in. After they pay, retry the call with the same idempotency key.

The link expires after 30 minutes. If it expires, the next retry returns a new one.

Your first paid callCopy Anchor Link

Each account gets a one-time $2 free credit for its first key action. If that action is a paid call your balance can't cover, and the call costs $2 or less, Varis adds the credit and returns the same 402 with granted_credits:

{
  "error": {
    "code": "insufficient_funds",
    "message": "The available balance is too low for this request. As this is your first paid invocation, we've added a $2.00 credit to your balance. Retry this invocation with the same idempotency key to complete the request. When the task is done, ask the account owner to top up using the funding_url below. It expires in 30 minutes.",
    "shortfall_credits": 0,
    "funding_url": "https://usevaris.com/fund/t/abc123",
    "granted_credits": 20000
  },
  "request_id": "var_req_fc8e8702-6a7f-4f3f-9147-748936e5fee1"
}

Retry the call straight away with the same idempotency key, and show the funding_url to a person once the task is done.

A first call that costs more than $2 gets the plain 402 and no credit. Your first top-up adds the $2 instead.

Limits on requestsCopy Anchor Link

Each agent can make 120 calls a minute to /v1/invoke. Past that, Varis returns 429 with a Retry-After header.

What's nextCopy Anchor Link

• Transactions and receipts.
• Spend limits.