> ## 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 (Footprints)

> Search footprints, browse by library, and semantic search on the Trace Footprints platform.

Catalog reads are public and served from `data/footprints_index.json` (no backend), except
**semantic search**, which proxies to the backend vector index with a local text fallback.
Footprints are browsed by **library**, not category.

## Search / list — `GET /api/footprints`

<ParamField query="q" type="string">Case-insensitive match over name, description, tags, library.</ParamField>

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

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

<ResponseField name="footprints" type="Footprint[]" />

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

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://footprints.buildwithtrace.com/api/footprints?q=QFN&limit=20"
  ```

  ```ts TypeScript theme={null}
  import { searchFootprints } from "@/lib/api";
  const { footprints, total } = await searchFootprints("QFN", { limit: 20 });
  ```

  ```json Response theme={null}
  { "footprints": [ { "id": "Package_DFN_QFN:QFN-16…", "name": "QFN-16-1EP_3x3mm_P0.5mm",
    "library": "Package_DFN_QFN", "tags": "QFN 0.5", "padCount": 17,
    "pads": [ { "number": "1", "type": "smd" } ], "source": "trace" } ],
    "total": 771, "page": 1, "limit": 20, "totalPages": 39 }
  ```
</CodeGroup>

<Note>
  `/api/footprints` is search/list only (`q`, `page`, `limit`). The footprint **detail** page
  is a Server Component that reads the index directly via `getFootprintById()` — it does not
  call this route.
</Note>

## Browse by library

There is no library-list API route — libraries come from the index via the data layer:

```ts theme={null}
import { getAllFootprintLibraries, getTopFootprintLibraries, getFootprintsByLibrary } from "@/lib/footprints";

getTopFootprintLibraries(12);                 // homepage "Browse by Library" grid
getFootprintsByLibrary("Package_DFN_QFN", 1, 120);   // /browse/[library] page
```

Each returns `{ id, name, footprintCount }` (libraries) or a paginated
`FootprintSearchResult` (footprints in a library).

## 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=&type=footprint`. Returns
`source: "vector"` on success or `source: "text_fallback"` when the backend is unreachable.
Result items use the backend's `snake_case` (`pad_count`).

```json theme={null}
{ "results": [ { "name": "…", "library": "…", "description": "…", "pad_count": 16 } ],
  "query": "…", "total": 8, "source": "vector" }
```