discover

Free lexical search over up to 5 eligible endpoints, scored by relevance, evidence, availability, price and freshness.

Works in

Search up to 5 eligible endpoints by task, capability, category, provider, endpoint, input-schema, output-schema, schema, or hybrid mode (auto infers one). Free and read-only. Each result carries bounded relevance, evidence, availability, price and freshness components, plus its category; unknown evidence stays distinct from zero and is never scored as bad. Never returns a mock endpoint. For more than 5 results, or a whole category, use search_catalog instead.

Inputs

Argument	Type	Required	Default	Limits	Meaning
`mode`	string	No	`"auto"`	`auto`, `task`, `capability`, `category`, `provider`, `endpoint`, `input-schema`, `output-schema`, `schema`, `hybrid`	How to interpret `query`/`taskDescription`.
`ranking`	string	No	-	`relevance`, `price`, `reliability`, `community`, `balanced`	Alias of `prefer`.
`prefer`	string	No	-	`cheapest`, `reliable`, `fastest`, `balanced`	Orders providers inside a job.
`query`	string	No	-	1-500 chars	Search text.
`capability`	string	No	-	pattern `^[a-z][a-z0-9-]*(?:\.[a-z0-9-]+)+$`	A job id, for `capability` mode.
`category`	string	No	-	pattern `^[a-z][a-z0-9-]*$`	A category id, for `category` mode.
`taskDescription`	string	No	-	1-500 chars	Task text, for `task` mode.
`provider`	string	No	-	min 1 char	Provider id or name.
`endpointId`	string	No	-	min 1 char	An exact endpoint id, for `endpoint` mode.
`maxPrice`	number	No	-	0+	Drop candidates priced above this.
`allowedProviders`	string[]	No	-	-	Only these providers.
`blockedProviders`	string[]	No	-	-	Never these providers.
`eligibilities`	string[]	No	-	`internal-validation`, `byok`, `partner-required`, `prohibited`	Restrict by eligibility.
`executionModes`	string[]	No	-	`sync`, `async`	Restrict by execution mode.
`minimumScore`	number	No	-	0-1	Applied before `resultLimit`.
`resultLimit`	integer	No	5	1-5	Candidates returned.
`detail`	string	No	`"full"`	`title` \| `full`	`title` returns rank, endpointId, provider, name, capability, category, estimatedPrice, priceBasis, costPerSuccessUsd, async, works and sourceCapability.
`includeUnavailable`	boolean	No	-	-	Include candidates with no route to run right now.

works is {rate, runs, p50Ms, thin}: the measured success rate, decided runs, p50 latency, and thin when under 5 runs. credential (full detail only) says whose key a run uses. sourceCapability is the raw slug an endpoint was registered under; capability is the job it does. No endpoint for the named job returns an empty candidates array with a no_supply_for_job warning in meta.warnings.

Example call

{
  "mode": "capability",
  "capability": "web.search",
  "resultLimit": 3
}

Example answer

Abridged: a full candidate also carries reliability, reason, match, ranking and score.

{
  "candidates": [
    {
      "rank": 1,
      "endpointId": "context-dev-web-search",
      "provider": "Context.dev",
      "name": "Context API / Web Search",
      "capability": "web.search",
      "category": "search",
      "estimatedPrice": 0.00025,
      "priceBasis": "perResult",
      "eligibility": "byok"
    },
    {
      "rank": 2,
      "endpointId": "octen-web-search",
      "provider": "Octen",
      "name": "Octen / web search",
      "capability": "web.search",
      "category": "search",
      "estimatedPrice": 0.006,
      "priceBasis": "perCall",
      "eligibility": "byok"
    }
  ],
  "meta": {
    "requestedMode": "capability",
    "resolvedMode": "capability",
    "ranking": "balanced",
    "resultCount": 2
  }
}

Errors

Free and read-only; no runs.execute needed. A bad mode or enum value returns validation_error naming the field and the accepted values, for example Invalid option: expected one of "auto"|"task"|... at mode. An argument discover does not accept is refused with acceptedArguments listing what it does take. No supply for the named job is not an error: candidates is empty and meta.warnings carries no_supply_for_job: <jobId>.

REST and CLI

REST: GET /v1/discover