> ## Documentation Index > Fetch the complete documentation index at: https://monid.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Semantic endpoint search (ranked cards) > The shared discover pipeline projected as endpoint cards in ranked order — the semantic twin of `GET /public/v1/endpoints?q=`. Same ranking, health and outage hiding as `POST /v1/discover`. Cards carry `categories` node-id tags for client-side grouping, `metrics` (health) when available, and the composed `score`. Endpoint workflow hints come from `POST /v1/inspect`. ## OpenAPI ````yaml https://monid.ai/openapi.json post /v1/discover/endpoints openapi: 3.1.0 info: title: Monid API version: 0.1.0 description: >- Agentic payment platform for data — agents discover and buy data on demand. Authenticated `/v1/*` routes accept a Monid API key or Clerk JWT as a Bearer token. All errors return `{ code, message }`. List endpoints use cursor pagination; consult each operation schema for its last-page cursor encoding. servers: - url: https://api.monid.ai description: Production - url: https://monid.ai description: Public registry alias (public/v1 only) security: [] paths: /v1/discover/endpoints: post: tags: - Discover summary: Semantic endpoint search (ranked cards) description: >- The shared discover pipeline projected as endpoint cards in ranked order — the semantic twin of `GET /public/v1/endpoints?q=`. Same ranking, health and outage hiding as `POST /v1/discover`. Cards carry `categories` node-id tags for client-side grouping, `metrics` (health) when available, and the composed `score`. Endpoint workflow hints come from `POST /v1/inspect`. parameters: - $ref: '#/components/parameters/AgentModelHeader' - $ref: '#/components/parameters/AgentHarnessHeader' - $ref: '#/components/parameters/AgentSessionIdHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DiscoverEndpointsRequest' responses: '200': description: Ranked endpoint cards content: application/json: schema: $ref: '#/components/schemas/DiscoverEndpointsResponse' '400': description: Bad request — input failed validation content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized — missing or invalid credentials content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden — caller has no workspace or no access content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- Rate limited (errorCode `RATE_LIMITED`, message `Rate limited. Retry after Ns.`) — the `Retry-After` header carries whole seconds until the caller may retry; `RateLimit-Limit/-Remaining/-Reset` describe the binding limit as numbers only (also sent on allowed responses that matched a rule; responses that matched no rule, or an `unlimited` exemption, carry none of them). Applies to every authenticated `/v1` route (per API key / user / workspace); POST /v1/run additionally enforces per-provider/endpoint run limits. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' security: - Bearer: [] components: parameters: AgentModelHeader: name: X-Monid-Agent-Model in: header required: false description: >- Model driving the calling agent. Optional; a value that is empty, longer than 256 characters or not printable ASCII is ignored (never an error). schema: type: string maxLength: 256 example: claude-opus-5-5 AgentHarnessHeader: name: X-Monid-Agent-Harness in: header required: false description: >- Agent harness or client making the call (e.g. a coding agent, an agent framework). Optional; a value that is empty, longer than 256 characters or not printable ASCII is ignored (never an error). schema: type: string maxLength: 256 example: claude-code AgentSessionIdHeader: name: X-Monid-Agent-Session-Id in: header required: false description: >- Caller-side session identifier, so the calls of one agent session (discover → inspect → run → polling) can be correlated. Optional; a value that is empty, longer than 256 characters or not printable ASCII is ignored (never an error). schema: type: string maxLength: 256 example: 01JABCDEF0123456789XYZ schemas: DiscoverEndpointsRequest: type: object properties: q: type: string minLength: 1 maxLength: 1000 description: Natural-language search query. example: twitter posts limit: type: integer exclusiveMinimum: 0 description: >- Max results (default 5). Capped at the discover over-fetch pool size (`api-config` `discover.overfetchSize`, 200). example: 5 category: type: string maxLength: 60 pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$ description: >- Optional category node id to narrow the ranked results (ids from `GET /public/v1/categories`; a top id covers its group). example: twitter minScore: type: number minimum: 0 maximum: 2 description: >- Per-call override for the post-rerank score floor — same semantics as the legacy POST /v1/discover body field. example: 0.2 includeUnavailable: type: boolean default: false description: >- Endpoints currently in outage are hidden by default (the page is back-filled from the next ranked candidates). Set true to include them — marked `metrics.status: "outage"` and ranked last. example: false supportsX402: type: boolean description: >- 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: type: string minLength: 1 maxLength: 100 description: >- 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. example: eip155:8453 readonly: type: boolean description: >- 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: type: array items: type: string enum: - creates - updates - deletes minItems: 1 description: >- 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. example: - creates - deletes required: - q DiscoverEndpointsResponse: type: object properties: items: type: array items: $ref: '#/components/schemas/DiscoverEndpointCard' description: Ranked endpoint cards (best match first). total: type: integer minimum: 0 description: >- Above-floor semantic matches (after the outage filter and the optional category narrowing), before `limit` truncation. required: - items - total Error: type: object properties: code: type: integer description: HTTP status code, duplicated in the body. example: 400 message: type: string description: Human-readable error description. example: Bad Request hints: type: object additionalProperties: anyOf: - type: string - type: object properties: kind: type: string enum: - command - discover - inspect - run - getRun - stop - releaseResource - topup command: type: string query: type: string provider: type: string endpoint: type: string runId: type: string resourceId: type: string stripe: type: string dashboard: type: string docs: type: string comment: type: string required: - kind description: >- Optional next actions, rendered for the calling client like run-response hints (e.g. the paid TinyFish version on a free-quota 429 — spending permission required). errorCode: type: string enum: - RATE_LIMITED - X402_WORKSPACE_RESOURCES - X402_WORKSPACE_ONLY - X402_ACCRUING_COST - X402_EXCEEDS_SETTLEMENT_WINDOW - X402_VALIDITY_WINDOW_TOO_SHORT - X402_UNBOUNDED_PRICE - X402_PROMOTION - INSUFFICIENT_SCOPE - WALLET_INSUFFICIENT_FUNDS - IDENTITY_PROVIDER_UNKNOWN - IDENTITY_LINK_REQUIRES_SESSION - IDENTITY_LINK_STATE_INVALID - IDENTITY_VERIFICATION_FAILED - IDENTITY_PROVIDER_UNAVAILABLE - IDENTITY_ALREADY_LINKED - IDENTITY_USER_ALREADY_LINKED - IDENTITY_LINK_RATE_LIMITED - IDENTITY_REQUIRED - PROMO_IDENTITY_REDEEMED - PROMO_REDEEM_REQUIRES_SESSION - PROMO_CODE_REDEEMED_BY_WORKSPACE - PROMO_CODE_REDEEMED_BY_USER description: >- OPTIONAL machine-readable discriminant from the documented `ApiErrorCode` registry. Absent on legacy errors; clients MUST treat unknown values as absent. required: - code - message DiscoverEndpointCard: allOf: - $ref: '#/components/schemas/PublicEndpointInfo' - type: object properties: metrics: type: object properties: status: type: string enum: - healthy - stable - degraded - outage - unknown description: >- Operational status. healthy = 100% green in the fresh window (minutes); outage = failing right now; degraded = chronically elevated errors (days); stable = clean recent history, no live signal; unknown = no data at all (rare). runTimeMs: type: object properties: p50: type: number description: Median end-to-end run time (ms) — typical. p95: type: number description: 95th-percentile end-to-end run time (ms) — tail. description: >- Typical end-to-end run time, measured over the freshest recent window with enough completed runs to be meaningful. Omitted when no window has enough measured runs. required: - status description: >- Recent operational health (server-computed from run analytics). Omitted when analytics is unavailable. score: type: number description: >- Final composed reranker score. Opaque sort context — not a fixed-range relevance probability. required: - score PublicEndpointInfo: type: object properties: provider: type: string description: Provider slug. example: exa providerDisplayName: type: string description: Resolved provider display name (curation > slug). providerDisplayDescription: type: string description: Resolved provider display blurb. endpoint: type: string description: Endpoint path. example: /search displayName: type: string description: Resolved endpoint display label. Always populated. displayDescription: type: string description: Resolved endpoint display blurb. May be empty. price: $ref: '#/components/schemas/PublicPrice' tags: type: array items: type: string description: >- User-facing tags (e.g. `["verified", "no-markup"]`). `no-markup` = priced at the provider's standard rate with no platform fee added. Always an array; empty when no tags are set on the indexed wrapper. categories: type: array items: type: string description: >- 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. promotion: type: object properties: campaignId: type: string label: type: string description: Badge text, e.g. "50% OFF · Limited time". discountPercent: type: integer baseEndpoint: type: string description: >- The regular-price endpoint this promotion discounts; absent on a standalone promotion (not a copy of another endpoint). limits: type: object properties: perMinute: type: integer perHour: type: integer perDay: type: integer required: - perMinute - perHour - perDay description: Per-workspace call limits on this promotion endpoint. listPrice: allOf: - $ref: '#/components/schemas/PublicPrice' - description: >- The regular price of `baseEndpoint` (strike-through); absent when there is no base. required: - campaignId - label - discountPercent - limits description: >- Present ONLY on a limited-time promotion endpoint (`/promo/...`): a discounted copy of `baseEndpoint` — or a standalone offer without one — with stricter per-workspace limits, available while the campaign lasts. supportedX402Networks: type: array items: type: string description: >- 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. required: - provider - providerDisplayName - endpoint - displayName - displayDescription - price - tags - categories - supportedX402Networks PublicPrice: type: object properties: type: type: string amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency flatFee: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency period: type: object properties: unit: type: string enum: - MINUTE - DAY - MONTH count: type: integer exclusiveMinimum: 0 required: - unit - count per: anyOf: - type: object properties: unit: type: string enum: - MINUTE - DAY - MONTH count: type: integer exclusiveMinimum: 0 required: - unit - count - type: number unit: type: string enum: - token - character - second - image - credit - result - gb-month - step - byte - url - page default: anyOf: - type: object properties: type: type: string enum: - PER_CALL amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency required: - type - amount - type: object properties: type: type: string enum: - PER_RESULT amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency flatFee: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency required: - type - amount - type: object properties: type: type: string enum: - METERED amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency per: type: object properties: unit: type: string enum: - MINUTE - DAY - MONTH count: type: integer exclusiveMinimum: 0 required: - unit - count required: - type - amount - per - type: object properties: type: type: string enum: - PER_UNIT amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency per: type: number unit: type: string enum: - token - character - second - image - credit - result - gb-month - step - byte - url - page required: - type - amount - per - unit selectors: type: array items: type: object properties: label: type: string key: type: string in: type: string enum: - body - queryParam - pathParam - output offset: type: integer minimum: 0 required: - label - key - in variants: type: array items: type: object properties: when: type: object additionalProperties: anyOf: - type: string - type: number - type: boolean price: anyOf: - type: object properties: type: type: string enum: - PER_CALL amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency required: - type - amount - type: object properties: type: type: string enum: - PER_RESULT amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency flatFee: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency required: - type - amount - type: object properties: type: type: string enum: - METERED amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency per: type: object properties: unit: type: string enum: - MINUTE - DAY - MONTH count: type: integer exclusiveMinimum: 0 required: - unit - count required: - type - amount - per - type: object properties: type: type: string enum: - PER_UNIT amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency per: type: number unit: type: string enum: - token - character - second - image - credit - result - gb-month - step - byte - url - page required: - type - amount - per - unit label: type: string required: - when - price tiers: type: array items: type: object properties: label: type: string when: type: object additionalProperties: anyOf: - type: string - type: number - type: boolean selector: type: object properties: label: type: string key: type: string in: type: string enum: - body - queryParam - pathParam - output offset: type: integer minimum: 0 required: - label - key - in price: anyOf: - type: object properties: type: type: string enum: - PER_CALL amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency required: - type - amount - type: object properties: type: type: string enum: - PER_RESULT amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency flatFee: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency required: - type - amount - type: object properties: type: type: string enum: - METERED amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency per: type: object properties: unit: type: string enum: - MINUTE - DAY - MONTH count: type: integer exclusiveMinimum: 0 required: - unit - count required: - type - amount - per - type: object properties: type: type: string enum: - PER_UNIT amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency per: type: number unit: type: string enum: - token - character - second - image - credit - result - gb-month - step - byte - url - page required: - type - amount - per - unit required: - label - price required: - type - amount description: User-facing price (markup applied). securitySchemes: Bearer: type: http scheme: bearer description: >- Monid API key (`Authorization: Bearer mk_...`) or Clerk-issued JWT. Each operation lists the ONE scope an API key needs. `{resource}:*` grants every action on that resource; `*` grants everything; Clerk sessions hold `*`. Operations with an empty list need no scope. Scope catalog: `GET /v1/api-keys/scopes`. x-aep-authentication-method: api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.