---
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/supporting-domains/overview
---

# 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
- `post.letter.quote`: live
- `post.letter.send`: live
- `post.letter.status`: live
- `post.postcard.send`: live
- `broadcast.message.quote`: 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.publication.list`: live
- `web.publication.posts.list`: live
- `web.publication.post.get`: 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
- `travel.flight.search`: live
- `travel.flight.status`: live
- `travel.flight.track`: live
- `travel.airport.operations`: live
- `travel.hotel.search`: live
- `travel.transfer.search`: live
- `travel.reference.location.search`: live
- `travel.reference.airline.get`: live
- `geo.time.current`: live
- `geo.time.convert`: live
- `tax.vat.validate`: live
- `tax.vat.calculate`: live
- `tax.vat.categories.list`: 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
- `translation.text.rephrase`: 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
- `models.chat.complete`: live
- `models.code.complete`: live
- `models.list`: live
- `captcha.task.create`: live
- `captcha.task.result.get`: live
- `commerce.product.search`: live
- `commerce.product.get`: live
- `commerce.order.buy`: recommend_only
- `lottery.round.active`: live
- `lottery.wallet.stats`: live
- `music.song.generate`: live
- `music.song.get`: live
- `music.lyrics.generate`: live
- `music.lyrics.get`: live
- `property.records.search`: live
- `property.records.get`: live
- `property.valuation.sale.estimate`: live
- `property.valuation.rent.estimate`: live
- `phone.message.reaction.send`: pending
- `hotel.booking`: pending
- `research.sota`: pending

## Staged Or Deployment-Gated

- `broadcast.message.send`: mapped and recommendable on the current branch, but intentionally gated because one live execute would create a real public post and the latest observed Billboard challenge on May 1, 2026 was 40,960 credits ($40.96)
- `agents.*`: mapped and locally wired on the current branch, including free public discovery plus paid stateless `agents.run.autoexchange.mpp`; do not assume hosted availability until `GET /domains/agents` succeeds in that environment
- `finance.*`: mapped and production-smoked for Alpha Vantage and Abstract Exchange Rates routes, but do not assume hosted availability until `GET /domains/finance` succeeds in that environment
- `text.analyze`: mapped and recommendable through `text.analyze.diffbot-nl.mpp`, but execution is gated because direct Diffbot NL MPP wrapper checks returned HTTP 429 before payment on May 5, 2026; use recommend and route context only until paid smoke evidence exists
- `media.video.generate`: staged through `media.video.generate.fal.mpp`, but execution is gated because paid AgentRouter retries and direct paid mppx.fetch checks reproduced upstream paymentauth 524 timeouts on May 8, 2026
- hosted MCP follows the same rule: if agents, finance, tax, captcha, commerce, lottery, music, or property tools are absent or return `Unknown tool`, treat that rollout as not yet deployed there

## 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/post/capabilities/letter-send/recommend`, `/domains/post/capabilities/postcard-send/execute`, `/domains/broadcast/capabilities/message-quote/execute`, `/domains/broadcast/capabilities/message-send/recommend`, `/domains/text/capabilities/analyze/recommend`, `/domains/enrichment/capabilities/people-search/recommend`, `/domains/enrichment/capabilities/people-enrich/execute`, `/domains/social/route`, `/domains/web/capabilities/scrape/recommend`, `/domains/web/capabilities/extract/execute`, `/domains/web/capabilities/publication-list/execute`, `/domains/web/capabilities/publication-posts-list/execute`, `/domains/web/capabilities/publication-post-get/execute`, `/domains/search/capabilities/answer/execute`, `/domains/agents/capabilities/search/recommend`, `/domains/agents/capabilities/run/execute`, `/domains/finance/capabilities/equity-quote/execute`, `/domains/geo/capabilities/time-current/execute`, `/domains/geo/capabilities/time-convert/execute`, `/domains/tax/capabilities/vat-validate/execute`, `/domains/tax/capabilities/vat-calculate/execute`, `/domains/tax/capabilities/vat-categories-list/execute`, `/domains/document/capabilities/ocr/execute`, `/domains/media/capabilities/image-generate/recommend`, `/domains/media/capabilities/image-generate/execute`, `/domains/media/capabilities/image-edit/execute`, `/domains/travel/capabilities/flight-search/execute`, `/domains/travel/capabilities/airport-operations/execute`, `/domains/phone/capabilities/agent-create/execute`, `/domains/phone/capabilities/call-list/execute`, `/domains/speech/capabilities/transcribe/recommend`, `/domains/translation/capabilities/text-translate/execute`, `/domains/translation/capabilities/text-rephrase/execute`, `/domains/chain/capabilities/price-quote/recommend`, `/domains/models/capabilities/chat-complete/execute`, `/domains/models/capabilities/code-complete/execute`, and `/domains/models/capabilities/list/execute`.

## 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`.
- Treat `broadcast.message.quote` as live and safe to execute after normal route selection and route-context checks.
- Do not execute `broadcast.message.send` unless the human explicitly approves both the exact public message body and the quoted spend. One live call creates a real public post.
- Treat DripStack publication list and post list as free discovery reads. Do not execute `web.publication.post.get.dripstack.mpp` until the human has made an explicit article choice and approved the 50-credit starting spend.
- Do not claim `text.analyze` execution is live. `text.analyze.diffbot-nl.mpp` is mapped and recommendable, but current evidence is a Diffbot NL MPP HTTP 429 before payment with no AgentRouter credits charged.
- Do not claim `media.video.generate` execution is live. `media.video.generate.fal.mpp` is mapped, but current evidence is upstream paymentauth 524 timeouts reproduced outside AgentRouter; use recommend and route context only until paid smoke evidence exists.
- 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.
- Do not assume the agents, finance, tax, captcha, commerce, lottery, music, or property domains exist on every hosted environment. First check `GET /domains/<domain>` or the matching capability discovery route. If the API returns `DOMAIN_NOT_FOUND`, `Not Found`, or MCP returns `Unknown tool`, treat that domain as not yet deployed on that environment.

## 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/post"
curl "$AGENTIC_API_BASE_URL/domains/post/capabilities"
curl "$AGENTIC_API_BASE_URL/domains/broadcast"
curl "$AGENTIC_API_BASE_URL/domains/broadcast/capabilities"
curl "$AGENTIC_API_BASE_URL/domains/text"
curl "$AGENTIC_API_BASE_URL/domains/text/capabilities"
curl "$AGENTIC_API_BASE_URL/domains/agents"
curl "$AGENTIC_API_BASE_URL/domains/agents/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/finance"
curl "$AGENTIC_API_BASE_URL/domains/finance/capabilities"
curl "$AGENTIC_API_BASE_URL/domains/geo"
curl "$AGENTIC_API_BASE_URL/domains/geo/capabilities"
curl "$AGENTIC_API_BASE_URL/domains/tax"
curl "$AGENTIC_API_BASE_URL/domains/tax/capabilities"
curl "$AGENTIC_API_BASE_URL/domains/captcha"
curl "$AGENTIC_API_BASE_URL/domains/captcha/capabilities"
curl "$AGENTIC_API_BASE_URL/domains/commerce"
curl "$AGENTIC_API_BASE_URL/domains/commerce/capabilities"
curl "$AGENTIC_API_BASE_URL/domains/lottery"
curl "$AGENTIC_API_BASE_URL/domains/lottery/capabilities"
curl "$AGENTIC_API_BASE_URL/domains/music"
curl "$AGENTIC_API_BASE_URL/domains/music/capabilities"
curl "$AGENTIC_API_BASE_URL/domains/property"
curl "$AGENTIC_API_BASE_URL/domains/property/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"
curl "$AGENTIC_API_BASE_URL/domains/models"
curl "$AGENTIC_API_BASE_URL/domains/models/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/post/capabilities/letter-send/routes"
curl "$AGENTIC_API_BASE_URL/domains/post/capabilities/postcard-send/routes"
curl "$AGENTIC_API_BASE_URL/domains/broadcast/capabilities/message-quote/routes"
curl "$AGENTIC_API_BASE_URL/domains/broadcast/capabilities/message-send/routes"
curl "$AGENTIC_API_BASE_URL/domains/text/capabilities/analyze/routes"
curl "$AGENTIC_API_BASE_URL/domains/agents/capabilities/search/routes"
curl "$AGENTIC_API_BASE_URL/domains/agents/capabilities/run/routes"
curl "$AGENTIC_API_BASE_URL/domains/enrichment/capabilities/people-search/routes"
curl "$AGENTIC_API_BASE_URL/domains/enrichment/capabilities/people-enrich/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/web/capabilities/extract/routes"
curl "$AGENTIC_API_BASE_URL/domains/web/capabilities/publication-list/routes"
curl "$AGENTIC_API_BASE_URL/domains/web/capabilities/publication-posts-list/routes"
curl "$AGENTIC_API_BASE_URL/domains/web/capabilities/publication-post-get/routes"
curl "$AGENTIC_API_BASE_URL/domains/search/capabilities/answer/routes"
curl "$AGENTIC_API_BASE_URL/domains/finance/capabilities/equity-quote/routes"
curl "$AGENTIC_API_BASE_URL/domains/finance/capabilities/market-status/routes"
curl "$AGENTIC_API_BASE_URL/domains/finance/capabilities/fx-rate/routes"
curl "$AGENTIC_API_BASE_URL/domains/finance/capabilities/fx-convert/routes"
curl "$AGENTIC_API_BASE_URL/domains/finance/capabilities/fx-rate-historical/routes"
curl "$AGENTIC_API_BASE_URL/domains/geo/capabilities/time-current/routes"
curl "$AGENTIC_API_BASE_URL/domains/geo/capabilities/time-convert/routes"
curl "$AGENTIC_API_BASE_URL/domains/tax/capabilities/vat-validate/routes"
curl "$AGENTIC_API_BASE_URL/domains/tax/capabilities/vat-calculate/routes"
curl "$AGENTIC_API_BASE_URL/domains/tax/capabilities/vat-categories-list/routes"
curl "$AGENTIC_API_BASE_URL/domains/captcha/capabilities/task-create/routes"
curl "$AGENTIC_API_BASE_URL/domains/commerce/capabilities/product-search/routes"
curl "$AGENTIC_API_BASE_URL/domains/lottery/capabilities/round-active/routes"
curl "$AGENTIC_API_BASE_URL/domains/music/capabilities/song-generate/routes"
curl "$AGENTIC_API_BASE_URL/domains/property/capabilities/records-search/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/travel/capabilities/airport-operations/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/translation/capabilities/text-rephrase/routes"
curl "$AGENTIC_API_BASE_URL/domains/chain/capabilities/price-quote/routes"
curl "$AGENTIC_API_BASE_URL/domains/models/capabilities/chat-complete/routes"
curl "$AGENTIC_API_BASE_URL/domains/models/capabilities/code-complete/routes"
curl "$AGENTIC_API_BASE_URL/domains/models/capabilities/list/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.

## Post Flow

Use `post` when the task is about quoting a physical letter, sending a paid print-and-mail letter, polling mail fulfillment status, or sending a digital or physical postcard.

### 1. Recommend the best route for the mail workflow

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/post/capabilities/letter-send/recommend" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {
      "name": "Jianyu Li",
      "address_line1": "11030 SE 2nd St",
      "city": "Bellevue",
      "state": "WA",
      "zip": "98004",
      "country": "US"
    },
    "from": {
      "name": "AgentRouter",
      "address_line1": "2261 Market St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94114",
      "country": "US"
    },
    "pdf": {
      "url": "https://example.com/letter.pdf"
    },
    "optimizationPreferences": ["quality", "cost"]
  }'
```

Interpret the result this way:

- `recommendedProvider` is the top ranked post provider for that workflow
- `recommendedRouteKey` is the exact route selected inside the capability
- `canExecuteNow=false` means the route is modeled but still blocked by setup or runtime availability
- `candidates` contains the live route options and pricing details
- Recommendation does not charge credits

### 2. Execute explicitly after route selection

```bash
curl "$AGENTIC_API_BASE_URL/routes/post.postcard.send.papercut.mpp/context"

curl -X POST "$AGENTIC_API_BASE_URL/domains/post/capabilities/postcard-send/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "post.postcard.send.papercut.mpp",
    "provider": "papercut",
    "roast": "Route-by-route postcard check.",
    "github_username": "codepoet",
    "type": "digital",
    "allowFallback": false
  }'
```

You can also call capability-specific endpoints such as:

- `/domains/post/capabilities/letter-quote/recommend`
- `/domains/post/capabilities/letter-send/execute`
- `/domains/post/capabilities/letter-status/execute`
- `/domains/post/capabilities/postcard-send/recommend`

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 post route that executed
- `networkKey` tells you whether the route used `direct`, `agentcash`, `mpp`, or a source network such as `x402`; use `settlementRail: "x402"` to identify direct x402 settlement
- `creditsCharged` is the final debit for the physical-mail workflow
- If the route context marks physical address fields as required, ask the human for them before executing instead of guessing

## Broadcast Flow

Use `broadcast` when the task is about checking the current public Billboard post price or preparing a short public broadcast message.

### 1. Quote the current public-broadcast price

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

curl "$AGENTIC_API_BASE_URL/routes/broadcast.message.quote.billboard.mpp/context"

curl -X POST "$AGENTIC_API_BASE_URL/domains/broadcast/capabilities/message-quote/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "broadcast.message.quote.billboard.mpp",
    "allowFallback": false
  }'
```

Interpret the result this way:

- `currentPrice` is the current supplier quote for the real public post, not the fee for the quote call itself
- `creditsCharged` on the quote execute is the actual AgentRouter charge for running the quote route
- the authenticated AgentRouter proof on April 30, 2026 in America/Los_Angeles charged 1 credit ($0.001) for this quote route

### 2. Prepare a public send, but do not execute without approval

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/broadcast/capabilities/message-send/recommend" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Launch update goes here.",
    "optimizationPreferences": ["quality"]
  }'
```

Interpret the result this way:

- `recommendedRouteKey` tells you which public-send route would run if the human approves it
- do not treat recommendation as approval to publish
- as of May 1, 2026, the latest observed live Billboard send challenge was 40,960 credits ($40.96)
- before any send execution, get explicit human approval for both the exact message text and the quoted spend

## 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
  }'

curl -X POST "$AGENTIC_API_BASE_URL/domains/enrichment/capabilities/people-enrich/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "enrichment.people.enrich.diffbot.mpp",
    "fullName": "Sam Altman",
    "companyName": "OpenAI",
    "allowFallback": false
  }'

curl -X POST "$AGENTIC_API_BASE_URL/domains/enrichment/capabilities/company-enrich/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "enrichment.company.enrich.diffbot.mpp",
    "companyName": "OpenAI",
    "domain": "openai.com",
    "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`, `mpp`, or a source network such as `x402`; use `settlementRail: "x402"` to identify direct x402 settlement
- `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`, `mpp`, or a source network such as `x402`; use `settlementRail: "x402"` to identify direct x402 settlement
- `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, screenshotting a public URL, listing DripStack publications, listing publication posts, or retrieving one selected publication article.

```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
  }'

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.diffbot.mpp",
    "url": "https://www.example.com/article",
    "allowFallback": false
  }'

curl -X POST "$AGENTIC_API_BASE_URL/domains/web/capabilities/publication-list/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "web.publication.list.dripstack.mpp",
    "allowFallback": false
  }'

curl -X POST "$AGENTIC_API_BASE_URL/domains/web/capabilities/publication-posts-list/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "web.publication.posts.list.dripstack.mpp",
    "publicationSlug": "newsletter.morning-brew.morningbrew.com",
    "allowFallback": false
  }'

curl "$AGENTIC_API_BASE_URL/routes/web.publication.post.get.dripstack.mpp/context"

curl -X POST "$AGENTIC_API_BASE_URL/domains/web/capabilities/publication-post-get/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "web.publication.post.get.dripstack.mpp",
    "publicationSlug": "newsletter.morning-brew.morningbrew.com",
    "postSlug": "cheers-to-beer-20260506",
    "allowFallback": false
  }'
```

DripStack publication list and post list are free discovery reads. `web.publication.post.get.dripstack.mpp` starts at 50 credits and needs an explicit article choice plus approval before spending credits.

## 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
  }'
```

## Text Analysis Flow

Use `text` when the task is about analyzing plain text for entities, sentiment, facts, categories, summaries, language, or sentence structure.

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/text/capabilities/analyze/recommend" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "diffbot-nl",
    "content": "AgentRouter routes text analysis through Diffbot NL.",
    "fields": "entities,sentiment,language",
    "optimizationPreferences": ["quality"]
  }'

curl "$AGENTIC_API_BASE_URL/routes/text.analyze.diffbot-nl.mpp/context"
```

`text.analyze.diffbot-nl.mpp` is not a live execute route yet. Direct Diffbot NL MPP wrapper checks returned HTTP 429 before payment on May 5, 2026, so use recommend and route context only until `canExecuteNow` is true and paid route smoke evidence exists.

## Agents Flow

Use `agents` when the task is about discovering public hosted agents, inspecting one hosted agent, or paying for one stateless hosted-agent run. Only use this flow after discovery confirms that the current environment exposes `/domains/agents`.

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/agents/capabilities/search/recommend" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "privy",
    "optimizationPreferences": ["quality"]
  }'

curl -X POST "$AGENTIC_API_BASE_URL/domains/agents/capabilities/run/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "agents.run.autoexchange.mpp",
    "id": "ab7527c0-6099-4145-9d8b-47f09dab9390",
    "prompt": "Say hello in one short sentence.",
    "stateless": true,
    "allowFallback": false
  }'
```

## Finance Flow

Use `finance` when the task is about public ticker discovery, market status, equity quotes, time series, company fundamentals, FX, crypto conversions, macro indicators, or technical studies. Only use this flow after discovery confirms that the current environment exposes `/domains/finance`.

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/finance/capabilities/equity-quote/recommend" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "MSFT",
    "optimizationPreferences": ["speed", "quality"]
  }'

curl -X POST "$AGENTIC_API_BASE_URL/domains/finance/capabilities/equity-quote/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "finance.equity.quote.alphavantage.mpp",
    "symbol": "MSFT",
    "allowFallback": false
  }'

curl -X POST "$AGENTIC_API_BASE_URL/domains/finance/capabilities/fx-convert/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "finance.fx.convert.abstract-exchange-rates.mpp",
    "fromCurrency": "USD",
    "toCurrency": "JPY",
    "amount": 25,
    "allowFallback": false
  }'
```

## Geo Time Flow

Use `geo` when the task is about current local time, timezone lookup, or converting a datetime between locations.

`geo.time.current.abstract-timezone.mpp` and `geo.time.convert.abstract-timezone.mpp` are live after the May 9, 2026 paid route-by-route smoke. Each route charged 6 credits and returned normalized time fields.

```bash
curl "$AGENTIC_API_BASE_URL/routes/geo.time.current.abstract-timezone.mpp/context" \
  -H "Authorization: Bearer $AGENTIC_API_KEY"

curl -X POST "$AGENTIC_API_BASE_URL/domains/geo/capabilities/time-current/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "geo.time.current.abstract-timezone.mpp",
    "provider": "abstract-timezone",
    "location": "Los Angeles, CA",
    "allowFallback": false
  }'

curl "$AGENTIC_API_BASE_URL/routes/geo.time.convert.abstract-timezone.mpp/context" \
  -H "Authorization: Bearer $AGENTIC_API_KEY"

curl -X POST "$AGENTIC_API_BASE_URL/domains/geo/capabilities/time-convert/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "geo.time.convert.abstract-timezone.mpp",
    "provider": "abstract-timezone",
    "fromLocation": "Los Angeles, CA",
    "toLocation": "Tokyo, Japan",
    "datetime": "2026-05-08 09:30:00",
    "allowFallback": false
  }'
```

For current time, send `location`. For conversion, send `fromLocation`, `toLocation`, and optional `datetime`. If `datetime` is omitted, the provider converts the current time.

## Tax VAT Flow

Use `tax` when the task is about validating VAT numbers, calculating VAT on an amount, or listing VAT categories and rates.

Abstract VAT routes are live after the May 9, 2026 paid route-by-route smoke. `tax.vat.validate.abstract-vat.mpp`, `tax.vat.calculate.abstract-vat.mpp`, and `tax.vat.categories.list.abstract-vat.mpp` each charged 6 credits and returned HTTP 200 through AgentRouter.

```bash
curl "$AGENTIC_API_BASE_URL/routes/tax.vat.validate.abstract-vat.mpp/context" \
  -H "Authorization: Bearer $AGENTIC_API_KEY"

curl -X POST "$AGENTIC_API_BASE_URL/domains/tax/capabilities/vat-validate/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "tax.vat.validate.abstract-vat.mpp",
    "provider": "abstract-vat",
    "vatNumber": "DE123456789",
    "countryCode": "DE",
    "allowFallback": false
  }'

curl "$AGENTIC_API_BASE_URL/routes/tax.vat.calculate.abstract-vat.mpp/context" \
  -H "Authorization: Bearer $AGENTIC_API_KEY"

curl -X POST "$AGENTIC_API_BASE_URL/domains/tax/capabilities/vat-calculate/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "tax.vat.calculate.abstract-vat.mpp",
    "provider": "abstract-vat",
    "countryCode": "DE",
    "amount": 100,
    "calculationType": "add",
    "allowFallback": false
  }'

curl -X POST "$AGENTIC_API_BASE_URL/domains/tax/capabilities/vat-categories-list/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "tax.vat.categories.list.abstract-vat.mpp",
    "provider": "abstract-vat",
    "countryCode": "DE",
    "allowFallback": false
  }'
```

For validation, send `vatNumber` and optional `countryCode`. For calculation, send `countryCode`, `amount`, and `calculationType`. For category lookup, send `countryCode`.

## Newly Onboarded Generic Domains

Use these domains only after discovery confirms they are present in the current environment.

```bash
curl "$AGENTIC_API_BASE_URL/routes/captcha.task.create.twocaptcha.mpp/context"
curl "$AGENTIC_API_BASE_URL/routes/commerce.product.search.kicksdb.stockx.mpp/context"
curl "$AGENTIC_API_BASE_URL/routes/lottery.round.active.megapot/context"
curl "$AGENTIC_API_BASE_URL/routes/music.song.generate.suno.mpp/context"
curl "$AGENTIC_API_BASE_URL/routes/property.records.search.rentcast.mpp/context"
```

- `captcha`: 2Captcha task creation and result lookup through `captcha.task.create.twocaptcha.mpp` and `captcha.task.result.get.twocaptcha.mpp`
- `commerce`: KicksDB product search and market reads through routes such as `commerce.product.search.kicksdb.stockx.mpp`; side-effecting order routes can be recommend-only
- `lottery`: Megapot public round and wallet reads through direct routes such as `lottery.round.active.megapot`
- `music`: Suno song and lyrics task creation plus billed result lookups through `music.song.generate.suno.mpp`
- `property`: RentCast property records, valuations, listings, and market stats through `property.records.search.rentcast.mpp`

## 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/image-generate/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "media.image.generate.fal.mpp",
    "prompt": "Create a clean launch hero image for an AI developer tool",
    "aspectRatio": "16:9",
    "allowFallback": false
  }'
```

Only describe `media.image.generate` and `media.image.edit` as live right now. `media.video.generate.fal.mpp` is staged but gated by upstream paymentauth 524 evidence, so do not execute or promise video output until route context reports `canExecuteNow=true` and paid smoke evidence exists. 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
  }'
```

For airport departure or arrival boards, `travel.airport.operations.flightapi.mpp` is live after the May 8, 2026 production smoke. Fetch route context first, then pin FlightAPI when the human asks for that provider or for a concrete airport schedule:

```bash
curl "$AGENTIC_API_BASE_URL/routes/travel.airport.operations.flightapi.mpp/context" \
  -H "Authorization: Bearer $AGENTIC_API_KEY"

curl -X POST "$AGENTIC_API_BASE_URL/domains/travel/capabilities/airport-operations/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "travel.airport.operations.flightapi.mpp",
    "provider": "flightapi",
    "allowFallback": false,
    "iataCode": "JFK",
    "mode": "departures",
    "limit": 1
  }'
```

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, tone-preserving rephrase, 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
  }'

curl -X POST "$AGENTIC_API_BASE_URL/domains/translation/capabilities/text-rephrase/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "translation.text.rephrase.deepl.mpp",
    "text": "Please make this product update friendlier.",
    "targetLanguage": "EN-US",
    "tone": "prefer_friendly",
    "allowFallback": false
  }'
```

For DeepL rephrase, fetch route context first and use the exposed DeepL Write fields: `text`, `targetLanguage`, and optional `tone`. Do not send translate-only `formality` or `glossaryId`.

## 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
  }'
```

## Models Flow

Use `models` when the task is about raw language-model chat completion, code completion, or listing model ids. Do not use this domain for search-grounded answers, hosted agent execution, speech, translation, image generation, or document understanding.

```bash
curl -X POST "$AGENTIC_API_BASE_URL/domains/models/capabilities/chat-complete/recommend" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "Say AgentRouter DeepSeek smoke OK."
      }
    ],
    "optimizationPreferences": ["speed", "cost"]
  }'

curl "$AGENTIC_API_BASE_URL/routes/models.chat.complete.deepseek.mpp/context"

curl -X POST "$AGENTIC_API_BASE_URL/domains/models/capabilities/chat-complete/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "models.chat.complete.deepseek.mpp",
    "model": "deepseek-v4-flash",
    "messages": [
      {
        "role": "user",
        "content": "Say AgentRouter DeepSeek smoke OK."
      }
    ],
    "allowFallback": false
  }'

curl -X POST "$AGENTIC_API_BASE_URL/domains/models/capabilities/code-complete/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "models.code.complete.deepseek.mpp",
    "model": "deepseek-v4-flash",
    "prompt": "export function isAgentRouterReady() { return ",
    "suffix": "; }",
    "allowFallback": false
  }'

curl -X POST "$AGENTIC_API_BASE_URL/domains/models/capabilities/list/execute" \
  -H "Authorization: Bearer $AGENTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeKey": "models.list.deepseek.mpp",
    "allowFallback": false
  }'
```

DeepSeek MPP model routes passed production-mode paid smoke on May 5, 2026. Groq chat and list routes also passed production-mode paid smoke on May 10, 2026 through `models.chat.complete.groq.mpp` and `models.list.groq.mpp`. DeepSeek list returned `deepseek-v4-flash` and `deepseek-v4-pro`; Groq chat returned `AgentRouter Groq smoke OK` from `llama-3.1-8b-instant`.

## 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"
- "Quote this letter before I send it"
- "Mail this PDF as a physical letter"
- "Send a postcard to this GitHub user"
- "Check the current Billboard post price"
- "Prepare this short public broadcast message, but do not post it yet"
- "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"
- "List Morning Brew posts and retrieve the article I choose"
- "Give me a grounded answer with citations"
- "Analyze this text for entities and sentiment"
- "Search hosted agents for a Privy specialist"
- "Run the Privy Agent in stateless mode"
- "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"
- "Rewrite this update in a friendlier tone"
- "Check Microsoft stock and EUR/USD"
- "Get the current local time in Los Angeles"
- "Convert 9:30 AM Los Angeles time to Tokyo"
- "Validate this VAT number before invoicing"
- "Calculate VAT for a 100 EUR invoice in Germany"
- "Create a 2Captcha task and check the result"
- "Search StockX products through KicksDB"
- "Check the active Megapot lottery round"
- "Generate a short Suno song"
- "Search RentCast property records"
- "Check ETH price and wallet balances"
- "Run a short DeepSeek model chat"
- "Complete this code prefix with a model"

Map it like this:

1. Infer the domain and capability such as `email.send`, `email.inbox.buy`, `post.letter.quote`, `post.letter.send`, `post.letter.status`, `post.postcard.send`, `broadcast.message.quote`, `broadcast.message.send`, `agents.search`, `agents.get`, `agents.run`, `enrichment.people.search`, `social.content.search`, `web.extract`, `web.publication.list`, `web.publication.posts.list`, `web.publication.post.get`, `search.answer`, `text.analyze`, `finance.equity.quote`, `finance.fx.convert`, `finance.fx.rate.historical`, `geo.time.current`, `geo.time.convert`, `tax.vat.validate`, `tax.vat.calculate`, `tax.vat.categories.list`, `captcha.task.create`, `commerce.product.search`, `lottery.round.active`, `music.song.generate`, `property.records.search`, `document.ocr`, `media.image.generate`, `travel.flight.search`, `speech.transcribe`, `translation.text.translate`, `translation.text.rephrase`, `chain.price.quote`, `models.chat.complete`, `models.code.complete`, or `models.list`
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. For post flows, use route context to determine whether the route is asking for a PDF URL, physical address fields, a PostalForm order id, or Papercut postcard mode fields such as `type`, `roast`, and `github_username`
12. For broadcast flows, use route context to confirm whether the route is the safe quote path or the approval-gated public-send path, and treat `text` as the only current provider field for Billboard send
13. For DripStack publication flows, use `publication-list` then `publication-posts-list` when the article is not already selected, and require explicit article choice plus approval before paid `publication-post-get`
14. For text analysis, use `text.analyze` recommendation and `text.analyze.diffbot-nl.mpp` route context only while the Diffbot NL MPP HTTP 429 before-payment blocker remains current
15. Fetch route context for the selected concrete `routeKey` and use only its route fields and possible values
16. Compare the user's input with `execute.requiredFields` and `execute.conditionallyRequiredFields`; ask the human for missing route-specific values before execution
17. Call the matching execute endpoint with `routeKey` in the body only after required route-context fields are present
18. If execute returns a missing-field or invalid-field error, ask for the corrected value and retry the same selected route without fallback
19. 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.