---
title: "Semantic search grouped by provider"
method: POST
path: "/v1/discover/providers"
tags: ["Discover"]
---

# Semantic search grouped by provider

`POST /v1/discover/providers`

The shared discover pipeline's match set aggregated by provider — the semantic twin of `GET /public/v1/providers?q=` (same entry shape; counts are within the bounded semantic match set).

## Request body

- DiscoverProvidersRequest
  - `q` string, required — Natural-language search query.
  - `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.
  - `effects` string[] — Keep only endpoints whose run can have AT LEAST ONE of the named effects on your workspace resources (phone numbers, files, asset libraries): `creates`, `updates`, `deletes`. Omit for all endpoints. Takes precedence over `readonly` (`readonly=true` is the alias for "no write effects"). Resource effects only — an endpoint with no effect may still perform real-world actions and is still billed.

## Response `200`

Provider entries with semantic match counts

- object
  - `items` PublicProviderEntry[], required
    - `provider` string, required — Provider slug.
    - `displayName` string, required — Resolved display label (curation > slug).
    - `displayDescription` string
    - `url` string, uri — Provider's public website. Absent when the provider declares none — never null, never empty. NOT the endpoint-level documentation URL (`docUrl`), which stays private to `POST /v1/inspect`.
    - `endpointCount` integer, required — Number of currently-enabled endpoints.
  - `cursor` string — Opaque cursor for the next page. Absent on the last page.

## 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-25** `5abada71ceae` — 52 warning, 1 info
  - added the new `IDENTITY_ALREADY_LINKED` enum value to the `errorCode` response property for the response status `400`
  - added the new `IDENTITY_ALREADY_LINKED` enum value to the `errorCode` response property for the response status `401`
  - added the new `IDENTITY_ALREADY_LINKED` enum value to the `errorCode` response property for the response status `403`
  - added the new `IDENTITY_ALREADY_LINKED` enum value to the `errorCode` response property for the response status `500`
  - …49 more
- **2026-09-23** `fadab791136c` — 4 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`
  - …1 more
- **2026-09-11** `9874d9e34fcf` — 6 info
  - added the new optional request property `supportsX402`
  - added the new optional request property `x402Network`
  - added the optional property `errorCode` to the response with the `400` status
  - added the optional property `errorCode` to the response with the `401` status
  - …2 more
- …earlier changes not shown

[Full history](https://skmtc.dev/monid/apis/monid-api/changes/v1/discover/providers/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/99cc8f5bdff4?raw)