> ## 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.

# API Reference (Footprints)

> Complete endpoint reference for the Trace Footprints site routes and the backend endpoints they proxy to.

Base URL: `https://footprints.buildwithtrace.com`. Backend base: `https://api.buildwithtrace.com`.
Authenticated routes require `Authorization: Bearer <access_token>` (see
[Authentication](/platforms/authentication)). Every backend call carries `type=footprint`.

## Catalog (public, no backend)

| Method | Route             | Params           | Returns                                             |
| ------ | ----------------- | ---------------- | --------------------------------------------------- |
| GET    | `/api/footprints` | `q, page, limit` | `{ footprints[], total, page, limit, totalPages }`  |
| GET    | `/api/health`     | —                | `{ status, timestamp, data: { footprints_index } }` |

Library lists and footprint detail are read from the index via the
[data layer](/platforms/footprints/data-layer) (Server Components), not via dedicated routes.

## Proxied to backend / upstream

| Method | Route                      | Auth | Target                                              |
| ------ | -------------------------- | ---- | --------------------------------------------------- |
| GET    | `/api/search/semantic`     | –    | `GET /api/v3/components/search?…&type=footprint`    |
| GET    | `/api/download/[library]`  | –    | GitHub raw `.kicad_mod` (`?name=&source=`)          |
| POST   | `/api/generate/footprint`  | ✓    | `POST /api/v3/components/generate/footprint`        |
| POST   | `/api/generate/save`       | ✓    | `POST /api/v3/components/generated`                 |
| POST   | `/api/contribute/validate` | –    | *(local — pad-count check)*                         |
| POST   | `/api/contribute/submit`   | ✓    | `POST /api/v3/components/submit`                    |
| GET    | `/api/community`           | –    | `GET /api/v3/components/community?…&type=footprint` |
| GET    | `/api/comments`            | –    | `GET /api/v3/components/comments/{id}`              |
| POST   | `/api/comments`            | ✓    | `POST /api/v3/components/comments`                  |
| GET    | `/api/rating`              | –    | `GET /api/v3/components/generated/{id}/rating`      |
| POST   | `/api/rating`              | ✓    | `POST /api/v3/components/generated/{id}/rate`       |
| GET    | `/api/my-footprints`       | ✓    | `GET /api/v3/components/my?…&type=footprint`        |
| PATCH  | `/api/my-footprints`       | ✓    | `PATCH /api/v3/components/generated/{id}`           |
| DELETE | `/api/my-footprints`       | ✓    | `DELETE /api/v3/components/generated/{id}`          |

## Detail pages

* [Browse & Search](/platforms/footprints/browse-and-search) — `/api/footprints`, semantic, by-library
* [Generate](/platforms/footprints/generate) — `/api/generate/footprint`
* [Contribute](/platforms/footprints/contribute) — validate + submit
* [Clipboard & Download](/platforms/footprints/clipboard-and-download) — `/api/download/[library]`
* [Saved & Community](/platforms/footprints/saved-and-community) — my-footprints, community, comments, ratings

## Common error codes

| Status        | Meaning                                                           |
| ------------- | ----------------------------------------------------------------- |
| `400`         | Validation error (bad params / not `.kicad_mod` / missing `name`) |
| `401`         | Missing or expired bearer token                                   |
| `402` / `403` | Plan or quota does not permit the action                          |
| `404`         | Not found (incl. CERN raw download, or upstream miss)             |
| `502` / `500` | Backend / proxy error                                             |

The shared `SaveComponentPayload` (used by `/api/generate/save` with `type: "footprint"`) is
documented in the [symbols API reference](/platforms/symbols/api-reference#save-payload-savecomponentpayload).