> For the complete documentation index, see [llms.txt](https://docs.kumbaya.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kumbaya.xyz/developers/apis/search-service.md).

# Search Service

Public, no-auth full-text search for Kumbaya tokens and pools. Backed by an in-memory index (MiniSearch) that's continuously synced.

| Field             | Value                                                        |
| ----------------- | ------------------------------------------------------------ |
| Base URL          | `https://search.kumbaya.xyz`                                 |
| Base path         | `/api/v1`                                                    |
| OpenAPI / Swagger | [`search.kumbaya.xyz/docs`](https://search.kumbaya.xyz/docs) |
| Auth              | None. Rate-limited per IP.                                   |

> **Building an LLM agent?** These endpoints are also available as MCP tools - 8 of them under the `search_` prefix. See the [MCP Server](/developers/building-agents/agent-kit/mcp.md), part of the [Kumbaya Agent Kit](/developers/building-agents/agent-kit.md).

## Endpoints

### Health

* `GET /health` - `{ status, indexed, tokenCount, poolCount }`
* `GET /ready` - readiness probe (`200` if synced, `503` until then)

### Search (`/api/v1/search*`)

#### `GET /api/v1/search` - combined token + pool search

Query parameters:

| Param                        | Type                         | Notes                                                          |
| ---------------------------- | ---------------------------- | -------------------------------------------------------------- |
| `q`                          | string (1–256)               | The search query - fuzzy matched on symbol, name, and address. |
| `chainId`                    | int                          | `4326` mainnet, `6343` testnet                                 |
| `limit`                      | int (1–100, default 20)      | Max results                                                    |
| `isBluechip`                 | bool                         | Filter to blue-chip tokens/pools                               |
| `isTrending`                 | bool                         | Filter to trending                                             |
| `isFireToken` / `isFirePool` | bool                         | Filter to launchpad-originated tokens / their pools            |
| `isVerified`                 | bool                         | Filter to verified                                             |
| `visibility`                 | `verified \| trusted \| all` | Visibility level                                               |

Response: `{ tokens: Token[], pools: Pool[], query, chainId }`.

#### `GET /api/v1/search/tokens` - tokens only

Same query params; returns `{ tokens, query, chainId }`.

#### `GET /api/v1/search/pools` - pools only

Same query params; returns `{ pools, query, chainId }`.

#### `GET /api/v1/autocomplete` - fast prefix completion

For typeahead UIs. Returns either `null` or a single best `suggestion`:

```jsonc
{
  "query": "kum",
  "suggestion": {
    "completion": "Kumbaya",
    "symbol": "KUM",
    "name": "Kumbaya Token",
    "address": "0x…",
    "matchType": "name"        // or "symbol"
  }
}
```

Stricter rate limits than the main search endpoints.

### Index introspection

* `GET /api/v1/search/stats` - `{ tokenCount, poolCount, lastSyncTime, syncInProgress }`
* `GET /api/v1/tokens` - list all indexed tokens with the same filter params (no `q` required)

## Token / pool fields

Tokens include: `id, address, symbol, name, chainId, decimals, totalValueLockedUSD, volumeUSD, isBluechip, isTrending, isFireToken, isVerified, fireCreator, fireGraduated, imageUrl`.

Pools include: `id, address, chainId, feeTier, token0 { symbol, name, address }, token1 { … }, totalValueLockedUSD, volumeUSD, isBluechip, isFirePool, isVerified`.

## When to use this vs. the indexer

* **Search service** - typeahead, full-text matching, filtering for "show me launchpad tokens that are trending" style queries. Optimized for browser-grade latency.
* [**Hasura indexer**](/developers/resources/indexer.md) - anything analytical, time-series, or filtered on numeric ranges. The search index doesn't do range queries on TVL or time-bounded counts.
* [**Exchange API**](/developers/apis/exchange-api.md) - when you need quote pricing or detailed pool state, not search.

For complete schemas see Swagger at [`search.kumbaya.xyz/docs`](https://search.kumbaya.xyz/docs).