API reference

Discover

POST /v1/discover: search capabilities and raw endpoints by job description. Free, never runs a paid call.

POST /v1/discover

Search the catalog by describing the job in plain language. Free, public (no key required), and it never executes a paid call. One ranked list covers both tiers: routed capabilities and raw provider endpoints.

Request

{"query": "find a verified email for a person", "limit": 10}

Field	Type	Required	Notes
`query`	string	yes	plain-language description of the job; short noun phrases work best
`limit`	integer	no	1–50, default 10
`kind`	string	no	`capability` or `endpoint`; both when omitted
`provider`	string	no	restrict to one provider's capabilities and endpoints

Response

{
  "items": [
    {
      "capability": "contact.find",
      "title": "Find a work email",
      "description": "Turn a name and a company domain into a verified work email.",
      "status": "coming_soon",
      "providers": ["...", "..."],
      "live_providers": [],
      "platforms": [],
      "starting_price": {"amount": "0.05", "currency": "USD"},
      "health": {"status": "stable", "latency_ms_p50": 900},
      "kind": "capability",
      "score": 1.0,
      "hint": "routergrowth inspect -c contact.find"
    },
    {
      "kind": "endpoint",
      "provider": "dataforseo",
      "endpoint": "/v3/serp/google/organic/live/advanced",
      "method": "POST",
      "title": "Serp: Google Organic Live Advanced",
      "status": "live",
      "cost": {"model": "per_task", "estimate": "0.003", "currency": "USD", "note": "..."},
      "health": {"status": "healthy", "latency_ms_p50": 1400},
      "wrapped_by": ["seo.serp", "web.search"],
      "score": 0.71,
      "hint": "routergrowth inspect -p dataforseo -e /v3/serp/google/organic/live/advanced"
    }
  ],
  "hints": [
    "dataforseo /v3/serp/google/organic/live/advanced is wrapped by seo.serp, web.search: normalized output, a quote before the run, failover. Prefer the capability unless you need the raw fields.",
    "Raw endpoints return the provider's own payload and settle after the run on the provider's measured cost, never above your max_cost. inspect one before running it."
  ]
}

Field	Notes
`status`	`live` or `coming_soon`; never present a coming-soon capability's sandbox output as real data
`live_providers`	providers with a real adapter and an active account, routable in production
`starting_price`	the cheapest offer that can run now (a planned provider's rate card counts only while nobody serves the capability)
`kind`	`capability` or `endpoint`
`health`	the verdict: `healthy`, `stable`, `degraded`, `outage` or `unknown`, with the typical (p50) latency in milliseconds
`wrapped_by`	endpoints only: capabilities whose live adapter calls this endpoint
`score`	relevance, normalized to the top hit
`hint`	the CLI command to inspect the item
`hints`	top-level: what to do next (which capability wraps an endpoint, how raw calls bill, what to try when nothing matched)

Ranking is BM25 over names, titles, descriptions, tags and providers with synonym and prefix expansion. Capabilities outrank endpoints on equal relevance, live outranks not-yet-live, and a live capability that wraps an endpoint always ranks above it. An empty items array means nothing matches: the hints say what to try; the catalog and each provider's endpoint list (GET /v1/catalog/providers/{provider}/endpoints) are the full inventories.

Inspect the winning candidate before running it.

Previous
API overview Next
Inspect

Reading this as an agent? This page as markdown: /docs/api/discover.md · every page: /docs/llms.txt