# Discover APIs

Ozma exposes catalog discovery on the web, REST, CLI, MCP, and SDK. All surfaces share the same control plane at `https://api.ozma.app`.

## Search

```http
GET /v1/search?q=&category=&sort=&limit=&offset=
```

| Param | Description |
|-------|-------------|
| `q` | Keyword or natural-language query (hybrid semantic + keyword when embeddings exist) |
| `category` | Category slug filter |
| `sort` | See sort enums below |
| `limit` | Default 50, max 500 |
| `offset` | Pagination offset |

Default sort is `ozma_score` when browsing without `q`. When `q` is set, default sort is `relevance`.

```bash
npx @ozma_app/cli search "exchange rates" --category finance --sort relevance --json
```

Each result includes merit axes (`ozma_score`, `reliability`, `adoption`, `retention`, `value`, `momentum`), latency (`p95_ms`, `p50_ms`), `calls_30d`, `gmv_cents_30d`, `paid_calls_24h`, `min_price_cents`, optional `list_min_price_cents` / `has_active_discount` (time-limited sale), and tags. With merit ranking v2 active, responses may include a `why` blend explanation.

On the web marketplace, discounted APIs show a **Sale** badge (list price struck through when higher). Use the **On Sale** view to filter to active discounts only.

## Sort enums

| Value | Use case |
|-------|----------|
| `ozma_score` | Default browse — composite merit |
| `relevance` | Default when `q` set; blends semantic match with OzmaScore (25% when merit v2 ON) |
| `price` | Cheapest effective price first |
| `new` | Recently published |
| `calls` | Most calls (30d) |
| `gmv` | Highest gross merchandise value (30d) |
| `reliability` | Wilson reliability axis |
| `value` | Successes per dollar |
| `momentum` | Paid calls in last 24h (hotness) |

Kill switch: set `MERIT_RANKING_V2=false` on the API worker (default ON in production).

## Categories

```http
GET /v1/categories
```

Returns `{ slug, name, api_count }` for each category with live APIs.

## Leaderboards

```http
GET /v1/leaderboards/:board?category=
```

| Board | Ranks by |
|-------|----------|
| `top_grossing` | GMV |
| `most_used` | Call volume |
| `most_reliable` | Reliability axis |
| `best_value` | Value axis |
| `trending` | Momentum |
| `new_rising` | Thompson sampling for low-data APIs; exploration slots for healthy newcomers |

```bash
npx @ozma_app/cli leaderboard most_reliable --category finance
```

Per-API ranks: `GET /v1/apis/:slug/ranks`.

## Market overview

```http
GET /v1/market/overview
```

Aggregates catalog totals, movers, and trending APIs. Authenticated activity ticker:

```http
GET /v1/market/activity?limit=
```

Requires Bearer auth (API key or session) — not a public endpoint.

## Web URL state

The marketplace at [https://ozma.app/](https://ozma.app/) mirrors discovery params in the query string:

| Param | Example | Effect |
|-------|---------|--------|
| `q` | `?q=weather` | Search query |
| `category` | `?category=finance` | Category filter |
| `sort` | `?sort=relevance` | Sort order |
| `view` | `?view=grid` | Layout (grid/list) |

Share or bookmark URLs to preserve filter state.

## API detail and schema

| Endpoint | Purpose |
|----------|---------|
| `GET /v1/apis/:slug` | Listing, endpoints, pricing, provider, legal/terms summary |
| `GET /v1/apis/:slug/schema` | Proxy paths + JSON schemas for agent tooling |
| `GET /v1/apis/:slug/openapi` | Machine-readable OpenAPI |
| `GET /v1/apis/:slug/stats?window=` | Provider stats (`24h`, `7d`, `30d`, `all`) |

```bash
npx @ozma_app/cli inspect frankfurter --schema --json
```

## Merit blend (relevance search)

When searching with `sort=relevance`, Ozma blends normalized semantic relevance (~75%) with normalized OzmaScore (~25%) among candidates that pass the relevance floor. Rankings are earned from usage signals — not paid placement. See [Merit engine](/docs/concepts/merit).

## Provider trust

Catalog rows and API detail include a **provider** block: `slug`, `name`, `avatar_url`, `founding_provider`, `verified`. Public profiles live at `https://ozma.app/providers/{slug}` with bio, links, socials, trust badges, and live API cards.

Use provider context when agents choose between similar listings. Required provider terms (`acceptance_mode: required`) gate gateway calls until the consumer org accepts — see [Troubleshooting](/docs/guides/troubleshooting).

## Agent shortcuts

- MCP: `discover_tools`, `search_apis`, `get_market_overview`, `get_leaderboard`, `get_provider_profile`
- Machine catalog: [https://ozma.app/llms.txt](https://ozma.app/llms.txt), `GET /v1/catalog/llms.txt`
- Request a missing API: `POST /v1/catalog/request-api` or `ozma request-api --query "…"`