--- title: "Semantic endpoint search (ranked cards)" method: POST path: "/v1/discover/endpoints" tags: ["Discover"] --- # Semantic endpoint search (ranked cards) `POST /v1/discover/endpoints` The shared discover pipeline projected as public endpoint cards in ranked order — the semantic twin of `GET /public/v1/endpoints?q=`. Cards carry `categories` node-id tags for client-side grouping. ## Request body - DiscoverEndpointsRequest - `q` string, required — Natural-language search query. - `limit` integer — Max results. Capped at the discover over-fetch pool size (`service.discover.overfetch_size`). - `category` string — Optional category node id to narrow the ranked results (ids from `GET /public/v1/categories`; a top id covers its group). - `minScore` number — Per-call override for the post-rerank score floor — same semantics as the legacy POST /v1/discover body field. - `supportsX402` boolean — Filter by static eligibility for x402 payment (`POST /x402/v1/run`): `true` keeps only payable endpoints, `false` only non-payable ones. Omit for all endpoints. Network availability and request/payment validation are checked at execution time. - `x402Network` string — Narrow to endpoints payable via x402 on this customer-payment network (CAIP-2 id, e.g. `eip155:8453`). Implies `supportsX402=true`; an unknown/unconfigured id returns an empty page. - `readonly` boolean — Filter by whether running the endpoint can change your workspace resources (phone numbers, files, asset libraries): `true` keeps only endpoints that cannot create, modify or delete them, `false` only endpoints that can. Omit for all endpoints. This describes RESOURCE effects only — a readonly endpoint may still perform real-world actions and is still billed. ## Response `200` Ranked endpoint cards - DiscoverEndpointsResponse - `items` PublicEndpointInfo[], required — Ranked endpoint cards (best match first). - `provider` string, required — Provider slug. - `providerDisplayName` string, required — Resolved provider display name (curation > slug). - `providerDisplayDescription` string — Resolved provider display blurb. - `endpoint` string, required — Endpoint path. - `displayName` string, required — Resolved endpoint display label. Always populated. - `displayDescription` string, required — Resolved endpoint display blurb. May be empty. - `price` PublicPrice, required — User-facing price (markup applied). - `type` string, required - `amount` object, required - `value` number, required - `currency` 'USD', required - `flatFee` object - `value` number, required - `currency` 'USD', required - `period` object - `unit` 'MINUTE' | 'DAY' | 'MONTH', required - `count` integer, required - `per` union - object - `unit` 'MINUTE' | 'DAY' | 'MONTH', required - `count` integer, required - number - `unit` 'token' | 'character' | 'second' | 'image' | 'credit' | 'result' | 'gb-month' | 'step' - `default` union - object - `type` 'PER_CALL', required - `amount` object, required - `value` number, required - `currency` 'USD', required - object - `type` 'PER_RESULT', required - `amount` object, required - `value` number, required - `currency` 'USD', required - `flatFee` object - `value` number, required - `currency` 'USD', required - object - `type` 'METERED', required - `amount` object, required - `value` number, required - `currency` 'USD', required - `per` object, required - `unit` 'MINUTE' | 'DAY' | 'MONTH', required - `count` integer, required - object - `type` 'PER_UNIT', required - `amount` object, required - `value` number, required - `currency` 'USD', required - `per` number, required - `unit` 'token' | 'character' | 'second' | 'image' | 'credit' | 'result' | 'gb-month' | 'step', required - `selectors` object[] - `label` string, required - `key` string, required - `in` 'body' | 'queryParam' | 'pathParam' | 'output', required - `offset` integer - `variants` object[] - `when` object, required - `price` union, required - object - `type` 'PER_CALL', required - `amount` object, required - … - object - `type` 'PER_RESULT', required - `amount` object, required - … - `flatFee` object - … - object - `type` 'METERED', required - `amount` object, required - … - `per` object, required - … - object - `type` 'PER_UNIT', required - `amount` object, required - … - `per` number, required - `unit` 'token' | 'character' | 'second' | 'image' | 'credit' | 'result' | 'gb-month' | 'step', required - `label` string - `tiers` object[] - `label` string, required - `when` object - `selector` object - `label` string, required - `key` string, required - `in` 'body' | 'queryParam' | 'pathParam' | 'output', required - `offset` integer - `price` union, required - object - `type` 'PER_CALL', required - `amount` object, required - … - object - `type` 'PER_RESULT', required - `amount` object, required - … - `flatFee` object - … - object - `type` 'METERED', required - `amount` object, required - … - `per` object, required - … - object - `type` 'PER_UNIT', required - `amount` object, required - … - `per` number, required - `unit` 'token' | 'character' | 'second' | 'image' | 'credit' | 'result' | 'gb-month' | 'step', required - `tags` string[], required — User-facing tags (e.g. `["verified"]`). Always an array; empty when no tags are set on the indexed wrapper. - `categories` string[], required — Depth-2 category paths — authored functional paths AND derived provider placement paths (e.g. `["social-media/twitter", "scrapers/apify"]`), treated uniformly. Bare top-level ancestors are excluded. Empty when the endpoint is outside the category catalog. - `supportedX402Networks` string[], required — Customer-payment networks (CAIP-2 ids, e.g. `["eip155:8453", "eip155:143"]`) this endpoint can be paid for through `POST /x402/v1/run`. Empty when the endpoint is not x402-eligible (workspace-resource coupling, cost accrual, settlement-window fit, or visibility). Static protocol/policy compatibility — network availability and request/payment validation are checked at execution time. - `total` integer, required — Above-floor semantic matches (after the optional category narrowing), before `limit` truncation. ## Other responses - `400` — Bad request — input failed validation - `401` — Unauthorized — missing or invalid credentials - `403` — Forbidden — caller has no workspace or no access - `500` — Internal server error ## Changes - **2026-09-23** `fadab791136c` — 8 warning, 1 info - added the new `X402_UNBOUNDED_PRICE` enum value to the `errorCode` response property for the response status `400` - added the new `X402_UNBOUNDED_PRICE` enum value to the `errorCode` response property for the response status `401` - added the new `X402_UNBOUNDED_PRICE` enum value to the `errorCode` response property for the response status `403` - added the new `X402_UNBOUNDED_PRICE` enum value to the `errorCode` response property for the response status `500` - …5 more - **2026-09-18** `cb05b702253d` — 4 warning - added the new `gb-month` enum value to the `items/items/price/default/anyOf[subschema #4]/unit` response property for the response status `200` - added the new `gb-month` enum value to the `items/items/price/tiers/items/price/anyOf[subschema #4]/unit` response property for the response status `200` - added the new `gb-month` enum value to the `items/items/price/unit` response property for the response status `200` - added the new `gb-month` enum value to the `items/items/price/variants/items/price/anyOf[subschema #4]/unit` response property for the response status `200` - …earlier changes not shown [Full history](https://skmtc.dev/monid/apis/monid-api/changes/v1/discover/endpoints/post.md) --- [API](https://skmtc.dev/monid/apis/monid-api.md) · [All operations](https://skmtc.dev/monid/apis/monid-api/llms.txt) · [OpenAPI document](https://skmtc.dev/monid/apis/monid-api/revisions/fadab791136c?raw)