> ## Documentation Index
> Fetch the complete documentation index at: https://docs.madra.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Search & Ranking

> How the Bazaar ranks results, and how to reason about why a listing appears where it does.

Search results are ranked on three axes, combined into a single score.

## The axes

1. **Textual relevance.** BM25 against `describe.title`, `describe.description`, and `describe.tags`. Titles weigh heaviest.
2. **Price.** Cheaper listings rank higher within a relevance bucket, subject to a floor so paying \$0 does not automatically win. Buyers can override this with `sort=price` to sort strictly by price.
3. **Recent activity.** Endpoints that have settled successfully in the last 24 hours rank higher. New listings get a small "fresh" boost for 48 hours to avoid a cold-start problem.

## What is not a signal

* Editorial ranking. There is no allowlist and no manual boosting.
* Payment to the operator. The Bazaar does not sell placement.
* Historical volume beyond the 7-day window. Old listings do not benefit from ancient traffic.

## Query examples

```bash theme={null}
# Free-text search, default ranking
curl "$FAC/discovery/search?q=weather+forecast"

# Force price sort
curl "$FAC/discovery/search?q=weather&sort=price"

# Filter by network and cap the price
curl "$FAC/discovery/search?q=weather&network=stellar:pubnet&maxPrice=0.01"

# Only MCP tools
curl "$FAC/discovery/search?q=summarize&type=mcp"
```

## Pagination

All queries use cursor-based pagination:

```json theme={null}
{
  "results": [ ... ],
  "nextCursor": "eyJvZmZzZXQiOjIwfQ=="
}
```

Pass `?cursor=<value>` to the next request. Do not construct cursors yourself — they are opaque.

## Debugging rank

Append `?explain=1` to any search request. The response gains a `debug` block per result showing the contribution of each axis. Useful for sellers trying to understand why their endpoint sits below a competitor.

## Related

* [GET /discovery/search](/api/discovery-search)
* [Discovery Filters](/discovery/filters)