---
title: "Semantic search over the x402 catalog"
method: POST
path: "/v1/semantic-search"
---

# Semantic search over the x402 catalog

`POST /v1/semantic-search`

## Request

- Base URL: `https://x402-trust.com`
- URL: `https://x402-trust.com/v1/semantic-search`
- Auth: none declared

Meaning-based search: describe the capability you need in plain words, get the up to 25 closest endpoints ranked by cosine similarity, then trust score. Discovery only: no verdicts or flags (POST /v1/x402-trust carries those). Per-IP rate limited (429 on excess).

## Request body

- object
  - `query` string, required: Free-text search query (2-500 chars). Describe the capability you need in plain words.
  - `limit` number: Max matches to return (1-25, default 25).

## Response `200`

query + count + ranked matches (id, resource, score, grade, similarity, description, endpointPage; score/grade null when unscored)

- object

## Other responses

- `400`: query missing or not 2-500 characters
- `429`: per-IP rate limit exceeded
- `503`: embedding service or similarity index unavailable, retry shortly

---

[API](https://skmtc.dev/x402-trust/apis/x402-trust-trust-reliability-data-for-the-x402-ecosystem.md) · [All operations](https://skmtc.dev/x402-trust/apis/x402-trust-trust-reliability-data-for-the-x402-ecosystem/llms.txt) · [OpenAPI document](https://skmtc.dev/x402-trust/apis/x402-trust-trust-reliability-data-for-the-x402-ecosystem/revisions/2a53d895d466?raw)