Trace Footprints — API Reference

Base URL: https://footprints.buildwithtrace.com. Backend base: https://api.buildwithtrace.com. Authenticated routes require Authorization: Bearer <access_token> (see 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 (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 — /api/footprints, semantic, by-library
Generate — /api/generate/footprint
Contribute — validate + submit
Clipboard & Download — /api/download/[library]
Saved & 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.

Getting Started

Core Concepts

Guides

API Reference (Footprints)

Catalog (public, no backend)

Proxied to backend / upstream

Detail pages

Common error codes

​Catalog (public, no backend)

​Proxied to backend / upstream

​Detail pages

​Common error codes

Catalog (public, no backend)

Proxied to backend / upstream

Detail pages

Common error codes