---
name: AgentRouter
version: 0.1.0
description: Routed API access for agents with recommendation, explicit execution, and centralized wallet credits (1000 credits = $1 USD).
homepage: https://www.agentrouter.to/agentic-api
---

# AgentRouter Skill

Routed API access for agents.

This skill teaches an agent how to use AgentRouter through natural language tasks while keeping the real execution path on HTTP endpoints.

## Skill URL

Use this file:

`https://www.agentrouter.to/SKILL.md`

## Compatibility

This skill can be added to any agent that can do both of the following:

- Read markdown instructions or a rule file
- Make HTTP requests directly, or run a shell command such as `curl`

Typical compatible clients:

- Codex CLI
- Claude Code
- Gemini CLI
- OpenClaw
- Cursor
- Windsurf
- Claude Desktop with tool access
- Other agents that support rule files, system prompts, or MCP-style workflows

## What Is Live

- `email.send`: live
- `email.inbox.buy`: live
- `enrichment.people.search`: live
- `enrichment.people.enrich`: live
- `enrichment.company.search`: live
- `enrichment.company.enrich`: live
- `enrichment.contact.enrich`: live
- `enrichment.email.find`: live
- `enrichment.email.verify`: live
- `social.profile.lookup`: live
- `social.profile.search`: live
- `social.content.search`: live
- `social.content.list`: live
- `social.content.get`: live
- `social.comments.list`: live
- `social.comments.replies`: live
- `social.network.connections`: live
- `social.ephemeral.list`: live
- `web.fetch`: live
- `web.scrape`: live
- `web.extract`: live
- `web.crawl`: live
- `web.map`: live
- `web.browser.session.create`: live
- `web.browser.session.status`: live
- `web.browser.session.extend`: live
- `web.browser.session.terminate`: live
- `web.screenshot`: live
- `search.web`: live
- `search.news`: live
- `search.images`: live
- `search.video`: live
- `search.answer`: live
- `search.context`: live
- `search.similar`: live
- `search.research`: live
- `document.ocr`: live
- `document.equation.parse`: live
- `document.layout.extract`: live
- `document.handwriting.parse`: live
- `media.image.generate`: live
- `media.image.edit`: live
- `media.video.generate`: live
- `travel.flight.search`: live
- `travel.hotel.search`: live
- `travel.transfer.search`: live
- `travel.reference.location.search`: live
- `travel.flight.track`: live
- `phone.agent.create`: live
- `phone.agent.list`: live
- `phone.agent.get`: live
- `phone.agent.update`: live
- `phone.agent.delete`: live
- `phone.agent.number.attach`: live
- `phone.agent.conversations.list`: live
- `phone.agent.calls.list`: live
- `phone.voice.list`: live
- `phone.number.provision`: live
- `phone.number.list`: live
- `phone.number.release`: live
- `phone.number.messages.list`: live
- `phone.number.calls.list`: live
- `phone.conversation.list`: live
- `phone.conversation.get`: live
- `phone.conversation.update`: live
- `phone.conversation.messages.list`: live
- `phone.call.list`: live
- `phone.call.get`: live
- `phone.call.outbound`: live
- `phone.webhook.upsert`: live
- `phone.webhook.get`: live
- `phone.webhook.delete`: live
- `phone.webhook.deliveries.list`: live
- `phone.webhook.test`: live
- `phone.agent.webhook.upsert`: live
- `phone.agent.webhook.get`: live
- `phone.agent.webhook.delete`: live
- `phone.agent.webhook.deliveries.list`: live
- `phone.agent.webhook.test`: live
- `phone.usage.summary`: live
- `phone.usage.daily`: live
- `phone.usage.monthly`: live
- `speech.transcribe`: live
- `speech.speak`: live
- `speech.models.list`: live
- `translation.languages.list`: live
- `translation.text.translate`: live
- `chain.rpc.call`: live
- `chain.token.search`: live
- `chain.token.get`: live
- `chain.price.quote`: live
- `chain.price.history`: live
- `chain.wallet.balances`: live
- `chain.wallet.transactions`: live
- `chain.wallet.pnl`: live
- `chain.entity.search`: live
- `chain.analytics.query`: live
- `phone.message.reaction.send`: pending
- `hotel.booking`: pending
- `research.sota`: pending

## Base URL

Use one of these:

- Local development: `http://localhost:3000/agentic-api`
- Deployed environment: `https://api.agentrouter.to/api/agentic-api`

If the base URL is not known, ask the human for it before making requests.

## Pricing Units

- `1000 credits = $1 USD`
- For example, `creditsCharged: 10` means `$0.01 USD`

## Local Runtime Defaults

For this local test setup, default to the local backend unless the human explicitly overrides it:

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

The local backend currently accepts `Authorization: Bearer $AGENTIC_API_KEY` directly on authenticated endpoints such as `/wallet`, `/domains/email/capabilities/send/recommend`, `/domains/enrichment/capabilities/people-search/recommend`, `/domains/social/route`, `/domains/web/capabilities/scrape/recommend`, `/domains/search/capabilities/answer/execute`, `/domains/document/capabilities/ocr/execute`, `/domains/media/capabilities/image-generate/recommend`, `/domains/travel/capabilities/flight-search/execute`, `/domains/phone/capabilities/agent-create/execute`, `/domains/phone/capabilities/call-list/execute`, `/domains/speech/capabilities/transcribe/recommend`, `/domains/translation/capabilities/text-translate/execute`, and `/domains/chain/capabilities/price-quote/recommend`.

## Hard Rules

- Never claim a send, booking, or research lookup succeeded unless the API returned success.
- Never invent wallet balances, prices, providers, or execution IDs.
- If `AGENTIC_API_KEY` is missing, ask the human to sign in at `/agentic-api/install`, enable AgentRouter, and copy the setup block before attempting execution.
- For natural-language tasks, always infer the domain and capability, then call the capability recommendation endpoint before route context or execution.
- Do not treat `recommendedRouteKey`, `bestExecutableRouteKey`, or the first candidate as user approval. They are route options, not permission to execute.
- Present viable route/provider candidates to the human and ask which route to use unless the human already named a concrete `routeKey`, or named a provider/route preference that recommendation resolves to exactly one viable candidate.
- If the human names a provider but not a concrete `routeKey`, include that provider preference in recommendation; do not skip recommendation or execute before route selection.
- Before execution, fetch `GET /routes/:routeKey/context` for the selected route and use the route-specific fields and possible values exposed there.
- Do not call route context with a capability key such as `phone.number.provision`; use a concrete recommended routeKey such as `phone.number.provision.inkbox`.
- Compare the user's request with route context `execute.requiredFields` and `execute.conditionallyRequiredFields`. Ask the human for missing route-specific information before execution instead of guessing.
- Execute with `routeKey` in the JSON body.
- If the user explicitly names a provider, honor it in the execution request.
- Default to `allowFallback=false`. Only set `allowFallback=true` after the human explicitly allows fallback or says reliability is more important than strict provider choice.
- If execute returns a missing-field, invalid-field, Bad Request, `userActionRequired`, or `fallbackAllowed=false` error, surface the provider/API error details, ask the human for the missing or corrected fields, and retry the same selected route. Do not fallback to another provider for these errors.
- In this local setup, prefer `Authorization: Bearer $AGENTIC_API_KEY` over `x-agentic-user-id`.
- In deployed environments, send `Authorization: Bearer $AGENTIC_API_KEY` for all authenticated AgentRouter calls.
- Treat `AGENTIC_AGENT_ID` as optional metadata only. It is not the wallet identity.
- In local development only, if the wallet is empty or unknown, you may call `POST /dev/init` and use `x-agentic-user-id`.
- Do not claim outbound phone calls succeeded unless `phone.call.outbound` returned success.
- Do not attempt `phone.message.send` yet. Outbound US SMS still depends on 10DLC registration and the public send contract is not finalized.
- Treat `phone.webhook.*` and `phone.agent.webhook.*` as tenant-scoped AgentRouter routing resources, not raw supplier webhook mutation.
- Treat `phone.usage.*` as tenant-scoped usage and billing reads computed from AgentRouter ledgers, not shared supplier account totals.
- Do not attempt hotel booking execution yet. Explain that hotel booking is pending.
- Do not attempt research execution yet. Explain that `research.sota` is pending.

## Product Discovery

Before first use in a session, read:

```bash
curl "$AGENTIC_API_BASE_URL/domains"
```

Then read:

```bash
curl "$AGENTIC_API_BASE_URL/domains/email"
curl "$AGENTIC_API_BASE_URL/domains/email/capabilities"
curl "$AGENTIC_API_BASE_URL/domains/enrichment"
curl "$AGENTIC_API_BASE_URL/domains/enrichment/capabilities"
curl "$AGENTIC_API_BASE_URL/domains/social"
curl "$AGENTIC_API_BASE_URL/domains/social/capabilities"
curl "$AGENTIC_API_BASE_URL/domains/web"
curl "$AGENTIC_API_BASE_URL/domains/web/capabilities"
curl "$AGENTIC_API_BASE_URL/domains/search"
curl "$AGENTIC_API_BASE_URL/domains/search/capabilities"
curl "$AGENTIC_API_BASE_URL/domains/document"
curl "$AGENTIC_API_BASE_URL/domains/document/capabilities"
curl "$AGENTIC_API_BASE_URL/domains/media"
curl "$AGENTIC_API_BASE_URL/domains/media/capabilities"
curl "$AGENTIC_API_BASE_URL/domains/travel"
curl "$AGENTIC_API_BASE_URL/domains/travel/capabilities"
curl "$AGENTIC_API_BASE_URL/domains/phone"
curl "$AGENTIC_API_BASE_URL/domains/phone/capabilities"
curl "$AGENTIC_API_BASE_URL/domains/speech"
curl "$AGENTIC_API_BASE_URL/domains/speech/capabilities"
curl "$AGENTIC_API_BASE_URL/domains/translation"
curl "$AGENTIC_API_BASE_URL/domains/translation/capabilities"
curl "$AGENTIC_API_BASE_URL/domains/chain"
curl "$AGENTIC_API_BASE_URL/domains/chain/capabilities"
```

Use these responses to confirm which domain capabilities are live, which routes are temporarily unavailable, and which capability-scoped endpoints are available right now.

When you need exact route metadata for one capability, read:

```bash
curl "$AGENTIC_API_BASE_URL/domains/email/capabilities/send/routes"
curl "$AGENTIC_API_BASE_URL/domains/email/capabilities/inbox-buy/routes"
curl "$AGENTIC_API_BASE_URL/domains/enrichment/capabilities/people-search/routes"
curl "$AGENTIC_API_BASE_URL/domains/enrichment/capabilities/company-enrich/routes"
curl "$AGENTIC_API_BASE_URL/domains/social/capabilities/content-search/routes"
curl "$AGENTIC_API_BASE_URL/domains/social/capabilities/profile-lookup/routes"
curl "$AGENTIC_API_BASE_URL/domains/web/capabilities/scrape/routes"
curl "$AGENTIC_API_BASE_URL/domains/search/capabilities/answer/routes"
curl "$AGENTIC_API_BASE_URL/domains/document/capabilities/ocr/routes"
curl "$AGENTIC_API_BASE_URL/domains/media/capabilities/image-generate/routes"
curl "$AGENTIC_API_BASE_URL/domains/travel/capabilities/flight-search/routes"
curl "$AGENTIC_API_BASE_URL/domains/phone/capabilities/agent-create/routes"
curl "$AGENTIC_API_BASE_URL/domains/phone/capabilities/number-provision/routes"
curl "$AGENTIC_API_BASE_URL/domains/phone/capabilities/conversation-list/routes"
curl "$AGENTIC_API_BASE_URL/domains/phone/capabilities/call-list/routes"
curl "$AGENTIC_API_BASE_URL/domains/phone/capabilities/webhook-get/routes"
curl "$AGENTIC_API_BASE_URL/domains/phone/capabilities/usage-summary/routes"
curl "$AGENTIC_API_BASE_URL/domains/speech/capabilities/transcribe/routes"
curl "$AGENTIC_API_BASE_URL/domains/translation/capabilities/text-translate/routes"
curl "$AGENTIC_API_BASE_URL/domains/chain/capabilities/price-quote/routes"
```

## Route Context And Execution

Before executing a specific concrete routeKey selected from recommendation, fetch its public route context:

```bash
curl "$AGENTIC_API_BASE_URL/routes/<routeKey>/context"
```

You can also use the capability-scoped form:

```bash
curl "$AGENTIC_API_BASE_URL/domains/<domain>/capabilities/<capability>/routes/<routeKey>/context"
```

Interpret route context this way:

- route context is not the natural-language entrypoint; call recommendation first and use the concrete routeKey selected from the recommendation result
- `recommendedRouteKey`, `bestExecutableRouteKey`, and the first candidate are recommendations only; present options and get route selection before execution unless the human already made an exact route/provider choice
- a capability key such as `phone.number.provision` is not a routeKey and must not be sent to `/routes/:routeKey/context`
- `execute.fields` is the request surface for that concrete route
- `execute.requiredFields` lists fields that must be present in the execute body
- `execute.conditionallyRequiredFields` lists fields that may be required depending on the user's requested mode; read the field notes before deciding
- `possibleValues` lists the route/provider values the agent should send
- read each possible value's `label` and `description` to map natural language to the exact value
- do not invent values that are not documented in the route context
- if required or conditionally required information is missing from the conversation, ask the human for it before executing
- to lock execution to a route, call the capability `execute` endpoint and include `routeKey` in the JSON body
- on validation or missing-input execution errors, keep the same selected route, ask for corrected input, and do not automatically try a different provider

Example:

```bash
curl "$AGENTIC_API_BASE_URL/routes/travel.flight.search.stabletravel.googleflights.agentcash/context"

curl -X POST "$AGENTIC_API_BASE_URL/domains/travel/capabilities/flight-search/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "travel.flight.search.stabletravel.googleflights.agentcash",
    "departure_id": "JFK",
    "arrival_id": "LAX",
    "outbound_date": "2026-05-01",
    "type": "2",
    "travel_class": "1",
    "adults": 1,
    "allowFallback": false
  }'
```

## Email Flow

## Required Environment

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

Optional:

```bash
AGENTIC_AGENT_ID=codex-main
```

### 1. Check wallet when needed

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

Local development fallback only:

```bash
curl -X POST http://localhost:3000/agentic-api/dev/init \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "agentic-dev-user"
  }'
```

### 2. Recommend a provider when no provider is specified

```bash
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": "alpha_agent",
    "optimizationPreferences": ["cost", "quality"],
    "sender": {
      "mode": "platform_managed",
      "replyTo": "ops@example.com"
    }
  }'
```

Interpret the result this way:

- `recommendedProvider` is the top ranked provider
- `recommendedRouteKey` is the exact route selected inside the capability
- `recommendedRouteMode` tells you whether the route is `managed`, `byo`, or `redirect`
- `canExecuteNow=false` means the cheapest route exists but still needs setup, owned-resource, or wallet steps
- `bestExecutableRouteKey` is the best route that can execute immediately
- `bestWorkflowRecommendation` tells you when AgentRouter can first acquire a needed inbox or other owned resource through credits, then execute the lower-cost route afterward
- `candidates` contains prices, scores, and reasons
- Present the viable `candidates` to the human; do not execute the top-ranked free or cheapest route until a route is selected
- Recommendation does not charge credits

### 3. Execute explicitly

```bash
curl "$AGENTIC_API_BASE_URL/routes/email.send.resend/context"

curl -X POST "$AGENTIC_API_BASE_URL/domains/email/capabilities/send/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "email.send.resend",
    "to": "test@example.com",
    "subject": "Hello",
    "html": "<p>Hello</p>",
    "sender": {
      "mode": "platform_managed",
      "replyTo": "ops@example.com"
    },
    "provider": "resend",
    "allowFallback": false
  }'
```

Interpret the result this way:

- `provider` is the provider that actually executed the request
- `requestedProvider` is the provider you asked for
- `fallbackUsed=true` means the router executed through a different provider
- `creditsCharged` is the final debit
- If execution fails with a missing or invalid field, ask the human for the corrected value and retry `email.send.resend`; do not switch to another provider unless the human chooses a different route

## Phone Flow

Use the phone domain for managed telephony resources:

1. Recommend the route for the target phone capability
2. If multiple viable route/provider candidates are returned, show those options and ask the human which route to use
3. Fetch route context for the selected concrete `routeKey`
4. Create an owned phone agent with `POST /domains/phone/capabilities/agent-create/execute`
5. Provision a managed number with `POST /domains/phone/capabilities/number-provision/execute`
6. Attach that number to the agent if the provision call did not already attach it
7. Read conversations and calls through the owned phone resources
8. Configure tenant-scoped project or agent routing through `phone.webhook.*` and `phone.agent.webhook.*` when the workflow needs managed internal dispatch or delivery audit
9. Read tenant usage and billing through `phone.usage.summary`, `phone.usage.daily`, and `phone.usage.monthly`

Example create:

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/phone/capabilities/agent-create/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "phone.agent.create.agentphone",
    "name": "AgentRouter Front Desk",
    "voiceMode": "webhook",
    "beginMessage": "Thanks for calling AgentRouter. How can I help today?",
    "voice": "alloy"
  }'
```

Example number provision:

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/phone/capabilities/number-provision/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "phone.number.provision.inkbox",
    "agentHandle": "front-desk-agent",
    "numberType": "local",
    "state": "WA",
    "incomingCallAction": "auto_accept",
    "clientWebsocketUrl": "wss://example.com/agent-phone"
  }'
```

Example managed project routing read:

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/phone/capabilities/webhook-get/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "phone.webhook.get.agentphone"
  }'
```

Example tenant usage summary:

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/phone/capabilities/usage-summary/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "phone.usage.summary.agentphone"
  }'
```

Interpret phone execution results this way:

- `agentId`, `numberId`, `conversationId`, and `callId` are the managed phone resource ids
- `provider` is currently `agentphone`
- `routeKey` stays capability-first, for example `phone.number.provision.agentphone`
- `phone.webhook.*` and `phone.agent.webhook.*` are managed AgentRouter routing records, even though live supplier ingress still lands on one shared AgentRouter endpoint
- `phone.usage.*` reflects tenant-scoped call, message, and number billing recorded by AgentRouter
- shared upstream webhook secrets are redacted in normalized responses

### 4. Buy an inbox when the task needs one

Recommend first:

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/email/capabilities/inbox-buy/recommend" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "optimizationPreferences": ["cost"]
  }'
```

Execute the purchase:

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/email/capabilities/inbox-buy/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "email.inbox.buy.stableemail",
    "username": "alpha-agent",
    "forwardTo": "ops@example.com",
    "allowFallback": false
  }'
```

Interpret the result this way:

- `routeKey` is the exact capability route that executed
- `status=completed` means the inbox purchase finished
- `address` is the inbox address you can use in later flows
- `creditsCharged` is the fixed debit for the inbox purchase
- If the API returns `code=AGENTMAIL_MPP_CONFLICT` or an error like `Inbox is taken`, do not retry the same username. Tell the human the inbox name is unavailable and ask for a different username or domain.

## Enrichment Flow

Use enrichment when the task is about:

- finding people by role, company, geography, or industry
- enriching a known person or company record
- resolving contact details from a LinkedIn URL or person profile
- finding a likely work email
- verifying whether an email is deliverable

### 1. Route the task when the human request is ambiguous

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/enrichment/route" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "Find the work email for the VP Engineering at Example Corp",
    "companyName": "Example Corp",
    "title": "VP Engineering",
    "optimizationPreferences": ["cost", "quality"]
  }'
```

Interpret the result this way:

- `capabilityId` is the enrichment capability to use next
- `capabilityKey` is the canonical internal identifier
- `confidence` tells you how strong the routing match is
- `candidates` lists fallback capability guesses if the task is ambiguous

### 2. Recommend the best route inside one capability

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/enrichment/capabilities/people-search/recommend" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "VP Engineering",
    "location": "San Francisco",
    "industry": "AI Infrastructure",
    "optimizationPreferences": ["cost", "quality"]
  }'
```

You can also call capability-specific recommend endpoints such as:

- `/domains/enrichment/capabilities/people-enrich/recommend`
- `/domains/enrichment/capabilities/company-search/recommend`
- `/domains/enrichment/capabilities/company-enrich/recommend`
- `/domains/enrichment/capabilities/contact-enrich/recommend`
- `/domains/enrichment/capabilities/email-find/recommend`
- `/domains/enrichment/capabilities/email-verify/recommend`

Interpret the result this way:

- `recommendedProvider` is the top ranked provider
- `recommendedRouteKey` is the exact route selected inside the capability
- `recommendedRouteMode` tells you whether the route is `managed`, `byo`, or `redirect`
- `canExecuteNow=false` means the route is modeled but not currently executable
- `blockingRequirements` and `nextActions` explain why
- `candidates` contains price, route, and reasoning details
- Present viable candidates and get route selection before execution unless the human already made an exact route/provider choice
- Recommendation does not charge credits

### 3. Execute explicitly after recommendation

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/enrichment/capabilities/contact-enrich/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "enrichment.contact.enrich.clado.mpp",
    "linkedinUrl": "https://www.linkedin.com/in/example",
    "optimizationPreferences": ["quality"],
    "provider": "clado",
    "allowFallback": false
  }'
```

Interpret the result this way:

- `provider` is the provider that actually executed the request
- `requestedProvider` is the provider you asked for
- `routeKey` is the exact route that executed
- `networkKey` tells you whether the route used `direct`, `agentcash`, or `mpp`
- `fallbackUsed=true` means execution switched to another route
- `creditsCharged` is the final debit
- `executionStatus=completed` means the execution succeeded

## Social Flow

Use social when the task is about:

- looking up a known profile or page
- searching social profiles, pages, groups, or users
- searching current public posts by keyword, hashtag, tag, or music
- listing profile feeds, subreddit feeds, comments, replies, followers, or following
- reading platform-native ephemeral content such as Instagram stories or highlights

Current live social platforms in this rollout are:

- Instagram
- TikTok
- Facebook
- Reddit

Platform coverage is route-specific, not universal. For example:

- `social.profile.search` is live for TikTok, Facebook, and Reddit
- there is currently no live Instagram `social.profile.search` route
- if the handle is already known, use `social.profile.lookup`
- if the handle is not known on Instagram, `social.content.search.instagram.keyword` can be used as a heuristic fallback to inspect post authors, but it is not equivalent to a first-class profile search route

### 1. Route the task when the human request is ambiguous

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/social/route" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "List Instagram highlights for nike",
    "platform": "instagram",
    "handle": "nike",
    "ephemeralType": "highlights"
  }'
```

Interpret the result this way:

- `capabilityId` is the social capability to use next
- `capabilityKey` is the canonical internal identifier
- `confidence` tells you how strong the routing match is
- `candidates` lists fallback capability guesses if the task is ambiguous

### 2. Recommend the best route inside one capability

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/social/capabilities/content-search/recommend" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "tiktok",
    "query": "foundation models",
    "optimizationPreferences": ["speed"]
  }'
```

You can also call capability-specific recommend endpoints such as:

- `/domains/social/capabilities/profile-lookup/recommend`
- `/domains/social/capabilities/profile-search/recommend`
- `/domains/social/capabilities/content-list/recommend`
- `/domains/social/capabilities/content-get/recommend`
- `/domains/social/capabilities/comments-list/recommend`
- `/domains/social/capabilities/comments-replies/recommend`
- `/domains/social/capabilities/network-connections/recommend`
- `/domains/social/capabilities/ephemeral-list/recommend`

Interpret the result this way:

- `recommendedProvider` is the top ranked provider
- `recommendedRouteKey` is the exact route selected inside the capability
- `recommendedRouteMode` tells you whether the route is `managed`, `byo`, or `redirect`
- `canExecuteNow=false` means the route is modeled but not currently executable
- `blockingRequirements` and `nextActions` explain why
- `candidates` contains price, route, and reasoning details
- Present viable candidates and get route selection before execution unless the human already made an exact route/provider choice
- Recommendation does not charge credits

### 3. Execute explicitly after recommendation

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/social/capabilities/profile-lookup/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "instagram",
    "routeKey": "social.profile.lookup.instagram.stablesocial",
    "handle": "nike",
    "allowFallback": false
  }'
```

Interpret the result this way:

- `provider` is the provider that actually executed the request
- `requestedProvider` is the provider you asked for
- `routeKey` is the exact route that executed
- `networkKey` tells you whether the route used `agentcash` or `mpp`
- `fallbackUsed=true` means execution switched to another route
- `creditsCharged` is the final debit
- `executionStatus=completed` means the execution succeeded
- AgentRouter handles the StableSocial async trigger-plus-poll flow for you

For example, to find recent Reddit posts about Garry Tan:

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/social/route" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "Find recent Reddit posts about Garry Tan, the CEO of Y Combinator.",
    "platform": "reddit",
    "query": "Garry Tan Y Combinator"
  }'

curl -X POST "$AGENTIC_API_BASE_URL/domains/social/capabilities/content-search/recommend" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "reddit",
    "query": "Garry Tan Y Combinator",
    "optimizationPreferences": ["quality", "cost"]
  }'

curl -X POST "$AGENTIC_API_BASE_URL/domains/social/capabilities/content-search/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "reddit",
    "routeKey": "social.content.search.reddit.keyword.stablesocial.agentcash",
    "query": "Garry Tan Y Combinator",
    "allowFallback": false
  }'
```

## Generic Domain Routing

For generic domains, the rule is:

1. infer the domain from the user goal
2. infer the capability inside that domain
3. always call the capability `recommend` endpoint before route context or execution
4. present viable route/provider options to the human and let them choose unless the human already named a concrete route, or named a provider/route preference that recommendation resolves to exactly one viable candidate
5. fetch `GET /routes/:routeKey/context` for the selected concrete routeKey and build input from route fields and `possibleValues`
6. compare the conversation with `execute.requiredFields` and `execute.conditionallyRequiredFields`; ask the human for missing route-specific information
7. call the matching `execute` endpoint with `routeKey` in the JSON body only after required route-context fields are present
8. on validation or missing-input execution errors, retry the same selected route after corrected input; do not fallback automatically
9. report the actual `routeKey`, `provider`, `networkKey`, and `creditsCharged`

Use the following routing guidance.

## Web Flow

Use `web` when the task is about fetching, scraping, extracting, crawling, mapping, browsing, or screenshotting a public URL.

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/web/capabilities/scrape/recommend" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.stripe.com/api",
    "optimizationPreferences": ["cost", "quality"]
  }'

curl -X POST "$AGENTIC_API_BASE_URL/domains/web/capabilities/extract/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "web.extract.firecrawl.mpp",
    "url": "https://docs.stripe.com/api",
    "fields": {
      "auth": "How does authentication work?"
    },
    "allowFallback": false
  }'
```

## Search Flow

Use `search` when the task is about web, news, image, or video search, grounded answers, similar-page discovery, or multi-hop research.

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/search/capabilities/answer/recommend" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What changed in the AI infrastructure market this week?",
    "optimizationPreferences": ["quality", "speed"]
  }'

curl -X POST "$AGENTIC_API_BASE_URL/domains/search/capabilities/answer/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "search.answer.brave.mpp",
    "query": "What changed in the AI infrastructure market this week?",
    "allowFallback": false
  }'
```

## Document Flow

Use `document` when the task is about OCR, handwriting parsing, equation extraction, or document layout understanding.

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/document/capabilities/ocr/recommend" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceUrl": "https://example.com/invoice.png",
    "optimizationPreferences": ["quality"]
  }'

curl -X POST "$AGENTIC_API_BASE_URL/domains/document/capabilities/layout-extract/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "document.layout.extract.mathpix.mpp",
    "sourceUrl": "https://example.com/invoice.png",
    "allowFallback": false
  }'
```

## Media Flow

Use `media` when the task is about image generation, image editing, or video generation.

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/media/capabilities/image-generate/recommend" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a clean launch hero image for an AI developer tool",
    "optimizationPreferences": ["quality"]
  }'

curl -X POST "$AGENTIC_API_BASE_URL/domains/media/capabilities/video-generate/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "media.video.generate.stablestudio.agentcash",
    "prompt": "Create a 4 second launch teaser for an AI developer tool",
    "durationSeconds": 4,
    "allowFallback": false
  }'
```

Only describe `media.image.generate`, `media.image.edit`, and `media.video.generate` as live right now. Do not claim background removal, replacement, upscale, or interpolation are live.

## Travel Flow

Use `travel` when the task is about flight, hotel, activity, transfer, airport, or flight-operations search.

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/travel/capabilities/flight-search/recommend" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": "SFO",
    "destination": "YVR",
    "departureDate": "2026-06-01",
    "returnDate": "2026-06-05",
    "optimizationPreferences": ["cost"]
  }'

curl -X POST "$AGENTIC_API_BASE_URL/domains/travel/capabilities/flight-search/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "travel.flight.search.stabletravel.googleflights.agentcash",
    "departure_id": "SFO",
    "arrival_id": "YVR",
    "outbound_date": "2026-06-01",
    "return_date": "2026-06-05",
    "type": "1",
    "travel_class": "1",
    "adults": 1,
    "allowFallback": false
  }'
```

Do not claim booking, cancellation, or order-follow-up routes are live unless the backend was started with the explicit travel side-effect enable flag.

## Speech Flow

Use `speech` when the task is about speech transcription, speech synthesis, or listing supported speech models.

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/speech/capabilities/transcribe/recommend" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audioUrl": "https://example.com/demo.mp3",
    "optimizationPreferences": ["quality"]
  }'

curl -X POST "$AGENTIC_API_BASE_URL/domains/speech/capabilities/speak/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "speech.speak.deepgram.mpp",
    "text": "Ship the update tonight.",
    "voice": "alloy",
    "allowFallback": false
  }'
```

## Translation Flow

Use `translation` when the task is about language translation or supported-language discovery.

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/translation/capabilities/text-translate/recommend" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Launch is delayed until tomorrow morning.",
    "targetLanguage": "de",
    "optimizationPreferences": ["quality"]
  }'

curl -X POST "$AGENTIC_API_BASE_URL/domains/translation/capabilities/text-translate/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "translation.text.translate.deepl.mpp",
    "text": "Launch is delayed until tomorrow morning.",
    "targetLanguage": "de",
    "allowFallback": false
  }'
```

Do not describe `translation.text.rephrase` as live on the current staged surface.

## Chain Flow

Use `chain` when the task is about token data, price data, wallet analytics, onchain entities, analytics queries, or raw JSON-RPC calls.

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/chain/capabilities/price-quote/recommend" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "ETH price",
    "chain": "ethereum",
    "optimizationPreferences": ["cost"]
  }'

curl -X POST "$AGENTIC_API_BASE_URL/domains/chain/capabilities/wallet-balances/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "chain.wallet.balances.allium.mpp",
    "chain": "ethereum",
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "allowFallback": false
  }'
```

## Natural Language Mapping

When the human says something like:

- "Send a welcome email to maya@example.com"
- "Use the cheapest reliable email provider"
- "Send via AgentMail"
- "Buy an inbox for my agent"
- "Find the VP Engineering at AI companies in San Francisco"
- "Enrich this company: stripe.com"
- "Find the work email for Jane Doe at OpenAI"
- "Verify whether jane@company.com is deliverable"
- "Look up the Instagram profile for nike"
- "Search TikTok posts about foundation models"
- "List Reddit comments for this post"
- "Get Instagram highlights for this handle"
- "Scrape this docs page and extract the auth section"
- "Give me a grounded answer with citations"
- "OCR this invoice and return the line items"
- "Generate a launch image and teaser video"
- "Find flights from SFO to YVR next month"
- "Transcribe this call recording"
- "Translate this message into German"
- "Check ETH price and wallet balances"

Map it like this:

1. Infer the domain and capability such as `email.send`, `email.inbox.buy`, `enrichment.people.search`, `social.content.search`, `web.extract`, `search.answer`, `document.ocr`, `media.image.generate`, `travel.flight.search`, `speech.transcribe`, `translation.text.translate`, or `chain.price.quote`
2. If the enrichment task is ambiguous, call `POST /domains/enrichment/route` first
3. If the social task is ambiguous, call `POST /domains/social/route` first
4. Always call the matching capability `recommend` endpoint before route context or execution
5. Present viable route/provider candidates to the human and let them choose unless the human already named a concrete route, or named a provider/route preference that recommendation resolves to exactly one viable candidate
6. Do not auto-select a route only because it is free, cheapest, first, `recommendedRouteKey`, or `bestExecutableRouteKey`
7. If the best route requires an owned inbox, wallet, or live route that is not currently executable, explain the blocker and the next setup action instead of pretending it is executable now
8. If `bestWorkflowRecommendation` exists for email flows, tell the human that AgentRouter can help acquire and bind the needed inbox or owned resource through credits before using the cheaper route
9. If an inbox-acquire execution fails because the requested inbox name is taken or unavailable, do not blindly retry the same username. Tell the human to choose another inbox name and retry with that new username.
10. For social flows, specify platform plus the route-defining identifiers such as `handle`, `profileId`, `postId`, `commentId`, `communityName`, `query`, `hashtag`, `tag`, `connectionType`, or `ephemeralType`
11. Fetch route context for the selected concrete `routeKey` and use only its route fields and possible values
12. Compare the user's input with `execute.requiredFields` and `execute.conditionallyRequiredFields`; ask the human for missing route-specific values before execution
13. Call the matching execute endpoint with `routeKey` in the body only after required route-context fields are present
14. If execute returns a missing-field or invalid-field error, ask for the corrected value and retry the same selected route without fallback
15. Return the actual route or provider used, credit charge, and status

## Hotel Booking Behavior

If the human asks for hotel search or booking:

- Recognize that this maps to future hotel booking support
- Explain that hotel booking is not executable yet
- Do not fabricate provider discovery or booking confirmations through the real API

## Research Behavior

If the human asks for research APIs such as:

- state-of-the-art lookup by task and dataset
- best paper by year
- structured benchmark timelines for datasets like CIFAR-100

Then:

- Recognize that this maps to future `research.sota` support
- Explain that research execution is not live yet
- You may mention `WizWand` as the pending provider path
- Do not fabricate JSON outputs, yearly rankings, or benchmark results through the real API

## Preferred Response Style

When reporting a successful execution, include:

- What product you used
- Which provider was recommended or selected
- Which provider actually executed the request
- Credits charged
- Whether fallback happened

When reporting a blocked task, explain the missing capability clearly and suggest the next supported step.