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

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.

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

GET /v1/categories

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

Leaderboards

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

npx @ozma_app/cli leaderboard most_reliable --category finance

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

Market overview

GET /v1/market/overview

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

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/ 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)

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.

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.

Agent shortcuts

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