---
title: "Search the catalogue by natural-language intent"
method: GET
path: "/api/v1/search/semantic"
---

# Search the catalogue by natural-language intent

`GET /api/v1/search/semantic`

## Request

- Base URL: `https://factreason.com`
- URL: `https://factreason.com/api/v1/search/semantic`
- Auth: HTTP bearer

Paid: $0.003 per successful query (tier `semantic_search`). Misses, HTTP 304 revalidations and rate-limited requests are never billed.

## Query parameters

- `q` string, required
- `limit` integer

## Response `200`

Authorized result, or an unbilled miss with `found: false` and nearest matches

## Other responses

- `304`: Cached revalidation. Never billed.
- `402`: Payment required. Carries x402 requirements and key-creation routes only — never any part of the requested record, and identical for a hit and a miss.
- `429`: Rate limited. Never billed; honour `Retry-After`.

---

[API](https://skmtc.dev/factreason/apis/factreason-agent-api.md) · [All operations](https://skmtc.dev/factreason/apis/factreason-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/factreason/apis/factreason-agent-api/revisions/dcf95bb905ea?raw)