Get Started

Quickstart

Go from API key to your first routed request
View as Markdown

This quickstart shows the default AgentRouter developer flow:

  1. authenticate once
  2. choose your integration surface
  3. discover the catalog
  4. recommend a route
  5. execute the capability
  6. inspect wallet and usage
1

Get your API key

Create or copy your AgentRouter API key from:

https://www.agentrouter.to/agentic-api/install

Then set your environment:

export AGENTIC_API_BASE_URL=https://api.agentrouter.to/api/agentic-api
export AGENTIC_API_KEY=aak_...

All authenticated examples below use Authorization: Bearer $AGENTIC_API_KEY.

2

Choose your integration surface

Pick the surface that matches how the agent or application will run:

Use CLI when a human operator or developer wants to inspect the live catalog, reproduce a workflow in the terminal, or run smoke checks in scripts.

npm install @agentrouter/agentrouter
npx agentrouter domains list
3

Discover the catalog

List the top-level domains:

curl "$AGENTIC_API_BASE_URL/domains"

Then inspect one domain:

curl "$AGENTIC_API_BASE_URL/domains/email/capabilities"

If you need the exact request shape for one capability, read its contract:

curl "$AGENTIC_API_BASE_URL/domains/email/capabilities/send/contract"
4

Recommend a route

When you have not pinned one provider yet, recommend first.

Example: ask AgentRouter to choose the best email send route based on cost and quality.

curl -X POST "$AGENTIC_API_BASE_URL/domains/email/capabilities/send/recommend" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "docs_quickstart",
    "optimizationPreferences": ["cost", "quality"],
    "tracking": true
  }'

Typical response shape:

{
  "success": true,
  "productKey": "email.send",
  "recommendedProvider": "resend",
  "recommendedRouteKey": "email.send.resend",
  "recommendedRouteMode": "managed",
  "canExecuteNow": true,
  "blockingRequirements": [],
  "nextActions": [],
  "candidates": [
    {
      "provider": "resend",
      "routeKey": "email.send.resend",
      "priceCredits": 10
    }
  ]
}
5

Execute the capability

Once you know the route you want, execute the capability.

curl -X POST "$AGENTIC_API_BASE_URL/domains/email/capabilities/send/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "maya@example.com",
    "subject": "Hello from AgentRouter",
    "html": "<p>Hello</p>",
    "provider": "resend",
    "allowFallback": true
  }'

Typical response shape:

{
  "success": true,
  "status": "sent",
  "provider": "resend",
  "routeKey": "email.send.resend",
  "creditsCharged": 10,
  "providerMessageId": "msg_123"
}
6

Check wallet and usage

AgentRouter bills in credits:

1000 credits = $1 USD

Read the current wallet balance:

curl "$AGENTIC_API_BASE_URL/wallet" \
  -H "Authorization: Bearer $AGENTIC_API_KEY"

Read recent usage:

curl "$AGENTIC_API_BASE_URL/usage?limit=20" \
  -H "Authorization: Bearer $AGENTIC_API_KEY"

Local Development Only

Outside production, you can initialize a dev wallet:

curl -X POST "$AGENTIC_API_BASE_URL/dev/init" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "agentic-dev-user",
    "balanceCredits": 100
  }'

Use this only for local or non-production testing.