Headless agents

A headless agent is anything that calls Varis without a person signing in: a script, a backend service, a scheduled job, or an agent you build yourself.

A headless agent authenticates with an agent key, which you create in the dashboard.

If you use an AI assistant such as Claude or ChatGPT, connect it with OAuth instead. For more information, see Connect an AI assistant.

Create an agentCopy Anchor Link

1. In the dashboard, go to Agents.
2. Click Create agent.
3. Enter a Name that tells you what the agent is, such as Pricing bot.
4. Under Limits, set Per request and Per day. For more information, see Spend limits.
5. Click Create agent.
6. Copy the agent key, and store it somewhere safe, such as your secret manager.

Varis shows the agent key only once. If you lose it, create a new agent.

If you leave both limits empty, Varis asks you to confirm.

Keep your agent key safeCopy Anchor Link

An agent key starts with var_ak_. Anyone who has it can spend your balance, within the agent's limits.

• Store it in an environment variable or a secret manager, not in your code.
• Use one agent per script or service, so that you can revoke one without affecting the others.
• If a key leaks, revoke its agent straight away.

Use your agent keyCopy Anchor Link

Send the agent key in the Authorization header of every request:

{
  "Authorization": `Bearer ${AGENT_KEY}`
  }

Replace AGENT_KEY with your agent key.

You can call Varis in two ways with the same key.

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

curl https://api.usevaris.com/v1/invoke \
  -H "Authorization: Bearer $VARIS_AGENT_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "SERVICE_ID",
    "input": { "from": "USD", "to": "EUR", "amount": 100 }
  }'

Manage an agentCopy Anchor Link

To manage an agent, go to Agents, and then open the agent's menu.

• Update limits: change the agent's Per request and Per day limits.
• Update categories: let the agent call services in All categories or only in Specific categories.
• Revoke: turn the agent off. Its key stops working immediately, and you can't turn it back on.

Click an agent to see every call it made and what each one cost.

Limits on requestsCopy Anchor Link

Each agent can make 120 calls a minute to POST /v1/invoke, and 300 requests a minute to the MCP server. Past that, Varis returns 429 with a Retry-After header. Wait that many seconds, and then retry with the same idempotency key. A limited call costs nothing.

What's nextCopy Anchor Link

• Discover and invoke services.
• Spend limits.