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:

1{
2  "success": true,
3  "productKey": "email.send",
4  "recommendedProvider": "resend",
5  "recommendedRouteKey": "email.send.resend",
6  "recommendedRouteMode": "managed",
7  "canExecuteNow": true,
8  "blockingRequirements": [],
9  "nextActions": [],
10  "candidates": [
11    {
12      "provider": "resend",
13      "routeKey": "email.send.resend",
14      "priceCredits": 10
15    }
16  ]
17}
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:

1{
2  "success": true,
3  "status": "sent",
4  "provider": "resend",
5  "routeKey": "email.send.resend",
6  "creditsCharged": 10,
7  "providerMessageId": "msg_123"
8}
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.