---
title: "Search the index by natural-language capability or task"
method: GET
path: "/search"
tags: ["discovery"]
---

# Search the index by natural-language capability or task

`GET /search`

## Request

- Base URL: `https://wellknown.network/api/v1`
- URL: `https://wellknown.network/api/v1/search`
- Auth: one of:
  - none
  - HTTP bearer

## Query parameters

- `q` string
- `capability` string
- `protocol` 'mcp' | 'a2a' | 'openapi' | 'http'
- `status` 'live' | 'recently_observed' | 'unavailable' | 'unknown'
- `kind` 'agent' | 'mcp_server' | 'tool' | 'api'
- `category` string
- `remote` 'true' | 'false'
- `claimed` 'true' | 'false'
- `language` string
- `limit` integer
- `offset` integer
- `sort` 'relevance' | 'recent' | 'name'

## Response `200`

OK

- SearchResponse
  - `query` string
  - `interpretation` object
  - `total` integer
  - `count` integer
  - `offset` integer
  - `facets` object
  - `results` SearchHit[]
    - `id` string
    - `handle` string
    - `name` string
    - `kind` 'agent' | 'mcp_server' | 'tool' | 'api'
    - `summary` string, nullable
    - `publisherName` string, nullable
    - `protocols` string[]
    - `categories` string[]
    - `status` 'live' | 'recently_observed' | 'unavailable' | 'unknown'
    - `statusReason` string, nullable
    - `lastObservedOkAt` string, date-time, nullable
    - `claimVerified` boolean
    - `primaryEndpointUrl` string, nullable: Network URL, or `npm:<name>` / `pypi:<name>` for local packages.
    - `capabilities` Capability[]
      - `slug` string
      - `name` string
      - `confidence` number
      - `provenance` 'declared' | 'derived' | 'claimed'
    - `pricing` object, nullable
    - `score` number
    - `signals` Signals: Transparent ranking components.
      - `lexical` number
      - `capability` number
      - `availability` number
      - `verification` number
      - `popularity` number
  - `tookMs` integer

## Other responses

- `429`: Rate limited; see Retry-After and X-RateLimit-* headers.

---

[API](https://skmtc.dev/wellknown/apis/wellknown-api.md) · [All operations](https://skmtc.dev/wellknown/apis/wellknown-api/llms.txt) · [OpenAPI document](https://skmtc.dev/wellknown/apis/wellknown-api/revisions/8a177fdcd434?raw)