> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildwithtrace.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Browse & Search (Symbols)

> Browse libraries, text search, semantic search, suggestions, categories, and thumbnails on the Trace Symbols platform.

All catalog reads are public and served from `data/symbols_index.json` (no backend), except
**semantic search**, which proxies to the backend vector index and falls back to local text
search if the backend is unreachable.

## List libraries — `GET /api/libraries`

<ParamField query="category" type="string">Filter by category id.</ParamField>

<ParamField query="page" type="number" default="1" />

<ParamField query="limit" type="number" default="50">Capped at 100.</ParamField>

<ResponseField name="libraries" type="Library[]">
  Each: `id, name, description, category, symbolCount, lastUpdated, contributor, source`.
</ResponseField>

<ResponseField name="total / page / limit / totalPages" type="number" />

## Library detail — `GET /api/libraries/[name]`

Returns the library plus its full `symbols[]` array (with `pins`). `404` if not found.

## Text search — `GET /api/search`

<ParamField query="q" type="string">Query string.</ParamField>

<ParamField query="category" type="string" />

<ParamField query="page" type="number" default="1" />

<ParamField query="limit" type="number" default="60">Capped at 100.</ParamField>

Returns `{ symbols, total, page, limit, totalPages }`. Scoring favors name matches, then
keywords, then library name, then description.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://symbols.buildwithtrace.com/api/search?q=STM32&category=mcu&limit=20"
  ```

  ```ts TypeScript theme={null}
  import { searchSymbols } from "@/lib/api";
  const { symbols, total } = await searchSymbols("STM32", { category: "mcu", limit: 20 });
  ```

  ```json Response theme={null}
  { "symbols": [ { "id": "MCU_ST_STM32F4:STM32F407VETx", "name": "STM32F407VETx",
    "library": "MCU_ST_STM32F4", "category": "mcu", "pinCount": 100, "source": "trace" } ],
    "total": 137, "page": 1, "limit": 20, "totalPages": 7 }
  ```
</CodeGroup>

## Semantic search — `GET /api/search/semantic`

<ParamField query="q" type="string" required>Minimum 2 characters.</ParamField>
<ParamField query="limit" type="number" default="20">Capped at 50.</ParamField>

Proxies to `GET /api/v3/components/search?q=&limit=`. Returns `source: "vector"` on success
or `source: "text_fallback"` when the backend is unreachable. Result items use the backend's
`snake_case` (`pin_count`).

```json theme={null}
{ "results": [ { "name": "…", "library": "…", "description": "…",
  "pin_count": 64, "category": "mcu" } ], "query": "…", "total": 12, "source": "vector" }
```

## Suggestions — `GET /api/search/suggest`

<ParamField query="q" type="string" required>Minimum 2 characters.</ParamField>

Local prefix/substring search, **max 8** results: `[{ id, name, library, pinCount }]`.

## Categories — `GET /api/categories`

Computed from the index: `[{ id, count }]`. `power_symbol`, `graphical`, and `mechanical`
are merged into `"other"`.

## Thumbnails — `GET /api/thumbnail?id=<symbolId>`

Returns a pre-rendered `image/svg+xml` (cached 1 day, immutable) from
`data/symbol_thumbnails.json`. `404` when missing — the UI then renders a generic
`MiniSchematic` from `pinCount`. SVGs use `currentColor`, so they inherit hover color.