# AgentReeve — semantic API discovery and routing for agents

AgentReeve is a live, evidence-backed index and router for AI agents and x402 APIs.
Describe the job, not the provider: AgentReeve searches endpoint capability profiles across the full corpus, checks current health/quotes/input compatibility, uses only verified deterministic adapters for cross-provider substitution, can negotiate quote-only prices when sellers support it, and charges a flat $0.003 routing fee regardless of which paid provider wins. Free services can route at $0, but public discovery exposes only their aggregate count; provider identities are paid market intelligence.

## Start here
Machine manifest: GET https://agentreeve.com/api/agentreeve
OpenAPI:         GET https://agentreeve.com/openapi.json
Detailed LLM doc: GET https://agentreeve.com/llms-full.txt
MCP discovery:   GET https://agentreeve.com/.well-known/mcp.json
MCP endpoint:    https://agentreeve.com/mcp

## Choose the right discovery mode
1. Know the provider/name/domain? -> GET /api/endpoints/search?q={name}
2. Browse exact capability IDs?   -> GET /api/capabilities
3. Know the job/capability?       -> GET /api/capabilities/search?q={natural-language job}
4. Want filtered discovery?       -> GET /api/search?q={job}&routable=1
5. Want a route decision?         -> POST /api/route with {"need":"...","dry_run":true} or {"capability_id":"...","dry_run":true}

Examples:
GET /api/endpoints/search?q=acme
GET /api/capabilities
GET /api/capabilities/search?q=Pakistan%20school%20attendance%20by%20gender
POST /api/route {"capability_id":"identity.sanctions_screening","need":"Check a Base wallet for OFAC sanctions exposure","provider":{"sort":"quality","allow_fallbacks":true,"max_price":{"request":0.02}},"dry_run":true}


## Caller-controlled provider routing
`POST /api/route` accepts `provider:{order,only,ignore,allow_fallbacks,sort,max_price,preferred_max_latency_ms}`. This follows the OpenRouter-style split: the calling agent expresses provider preferences; AgentReeve still enforces hard health, capability, schema, observed-price and payment safety before any provider can be used.

## One endpoint for everything
GET  https://agentreeve.com/api/agentreeve -> lists every action, argument and price
POST https://agentreeve.com/api/agentreeve -> {"action":"...", ...args}
Actions: lookup | categories | capabilities | endpoint_search | search | capability_search | capability_profile | adapters | adapter_register | board | resources | pricing | featured | route | free_intelligence | verify | ownership_challenge | submit | re_review | feature

## MCP tools
reputation_lookup
list_categories
list_capabilities(category?, routable_only?, canonical_only?)
search_endpoints_by_name
search_capabilities
get_capability_profile
search_index
get_board
route_call  # paid winners quote here; signed retry goes directly to POST /api/route

## Direct REST (free unless priced)
GET  /api/endpoints/search?q={name}                 provider/title/domain/URL identity search; cursor pagination; limit=all supported
GET  /api/capabilities                              browse actual canonical + dynamic capability IDs with live aggregate supply
GET  /api/capabilities/search?q={need}              full-corpus capability matching with match evidence and routability
GET  /api/capability-profile?url={endpoint}         endpoint capability graph, concepts, networks and adapters
GET  /api/search?q={need}&routable=1                natural-language discovery with filters and cursor pagination
GET  /api/resources                                 compact live index snapshot; cursor through all rows or use ?limit=all
GET  /api/categories                                indexed -> observed -> healthy -> routable supply
GET  /api/board/{category}?sort=score|cheapest|fastest|proven
GET  /api/reputation?url={endpoint}                 score + evidence + probe history
GET  /api/adapters?url={endpoint}                   deterministic canonical adapters and verification status
GET/POST /api/free-intelligence $0.01              reveal matching routable free-provider identities/evidence via x402; public discovery returns counts only
POST /api/adapters/register                         owner-verified adapter registration; no runtime AI field guessing
POST /api/route      paid winner: $0.003 AgentReeve fee only; successful fee retry returns buyer-direct handoff; buyer pays seller separately; free winner: $0
POST /api/verify     $0.05 real end-to-end execution for currently free endpoints; paid endpoints use buyer-direct /api/route
POST /api/submit     $5 owner-verified listing + first observed review
POST /api/re-review  $10 full re-probe/rescore; history preserved
POST /api/feature    $24/24h labelled advertising; never affects rank
POST /api/opt-out    free owner-verified removal

## How niche routing works
A request is converted into a structured job specification. Capability retrieval searches the whole evidence index rather than hard-filtering by broad browsing category. Candidates are then filtered by live routability, capability evidence, network/output requirements, payload/input contract, verified adapters and user policy. Price/reliability/latency and optional quote-only negotiation rank the survivors.

If AgentReeve cannot confidently demonstrate that a provider can perform the requested niche job, it should not spend money on that provider merely because it shares a broad category. Public route previews disclose paid-provider candidates and aggregate free-provider counts; free names/domains/URLs are not published unless the caller purchases the free-provider intelligence response.

## Routing safety
- Directory/declaration price is never routing truth; current observed quote evidence is.
- Cross-provider schema substitution requires a deterministic verified adapter or an identical compatible contract group.
- Ambiguous non-idempotent write failures fail closed unless the caller explicitly marks the operation retry-safe.
- Seller success occurs before final buyer settlement on paid routed calls.
- Negotiation is quote-only and only used when the seller explicitly advertises that mode.

## Rules
Standing is never for sale — only freshness.
Every paid check's result becomes public.
The AgentReeve route fee is flat and independent of which paid provider wins. AgentReeve collects only that fee; the buyer pays the seller directly from the buyer client. Free-provider routes are $0.

## Stable API version
New integrations may pin to /api/v1/* where available. Unversioned routes remain available for existing clients.


### Router category scope
When `need` is present, `category` is treated as a browse hint unless `category_lock: true` is explicitly supplied. This prevents a deep-link board such as `?category=messaging` from trapping a later natural-language job such as `crypto` inside the Messaging market.

Local control plane (optional):
- `GET /api/local-ai/health` reports local Ollama/Qwen availability.
- `POST /api/orchestrate` is an authenticated control-plane planner that can choose local work, an Innernet buyer-direct x402 handoff, or the neutral AgentReeve marketplace route.
- Local Qwen cannot authorize payment, modify x402 settlement terms, or alter neutral `/api/route` ranking.