# Discover

```text
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](/docs/api/endpoints).

## Request

```json
{"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

```json
{
  "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", "success_rate": 0.98, "latency_ms_p50": 900, "latency_ms_p95": 2100, "sample_size": 412, "source": "measured"},
      "kind": "capability",
      "score": 1.0,
      "hint": "jell 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", "...": "..."},
      "wrapped_by": ["seo.serp", "web.search"],
      "score": 0.71,
      "hint": "jell 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 platform-funded offer |
| `kind` | `capability` or `endpoint` |
| `health` | the measured verdict: `healthy`, `stable`, `degraded`, `outage` or `unknown`, with success rate, p50/p95 latency and sample size |
| `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](/catalog) and each provider's endpoint list (`GET /v1/catalog/providers/{provider}/endpoints`) are the full inventories.

## Next

[Inspect](/docs/api/inspect) the winning candidate before running it.