Trace Symbols — API Reference

Base URL: https://symbols.buildwithtrace.com. Backend base: https://api.buildwithtrace.com. Authenticated routes require Authorization: Bearer <access_token> (see Authentication).

Catalog (public, no backend)

Method	Route	Params	Returns
GET	`/api/libraries`	`category, page, limit`	`{ libraries[], total, page, limit, totalPages }`
GET	`/api/libraries/[name]`	—	Library + `symbols[]` (with pins); `404` if missing
GET	`/api/search`	`q, category, page, limit`	`{ symbols[], total, page, limit, totalPages }`
GET	`/api/search/suggest`	`q` (≥2)	`[{ id, name, library, pinCount }]` (max 8)
GET	`/api/categories`	—	`[{ id, count }]`
GET	`/api/thumbnail`	`id`	`image/svg+xml` or `404`
GET	`/api/download/[library]`	—	Raw `.kicad_sym` attachment
GET	`/api/health`	—	`{ status, timestamp, data }`

Proxied to backend

Method	Route	Auth	Backend target
GET	`/api/search/semantic`	–	`GET /api/v3/components/search?q=&limit=`
POST	`/api/generate`	✓	`POST /api/v3/components/generate/symbol`
POST	`/api/generate/save`	✓	`POST /api/v3/components/generated`
POST	`/api/contribute/validate`	–	(local — `kicad_parser.ts`)
POST	`/api/contribute/submit`	✓	`POST /api/v3/components/submit`
GET	`/api/community`	–	`GET /api/v3/components/community`
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-symbols`	✓	`GET /api/v3/components/my`
PATCH	`/api/my-symbols`	✓	`PATCH /api/v3/components/generated/{id}`
DELETE	`/api/my-symbols`	✓	`DELETE /api/v3/components/generated/{id}`

Detail pages

Browse & Search — libraries, search, semantic, suggest, categories, thumbnails
Generate — /api/generate request/response
Contribute — validate + submit
Saved & Community — my-symbols, community, comments, ratings

Common error codes

Status	Meaning
`400`	Validation error (bad params / file / description length)
`401`	Missing or expired bearer token
`402` / `403`	Plan or quota does not permit the action
`404`	Resource not found
`422`	Invalid uploaded file
`502` / `504`	Backend error / generation timeout

Save payload — `SaveComponentPayload`

{
  type: "symbol" | "footprint";
  name: string; description: string; is_public: boolean;
  keywords?: string[]; datasheet?: string; trace_json: object;
  // symbol-specific
  reference_prefix?: string; pin_count?: number;
  kicad_sym?: string | null; footprint_filters?: string[];
  // footprint-specific
  pad_count?: number; kicad_mod?: string | null; package_type?: string | null;
}

Getting Started

Core Concepts

Guides

API Reference (Symbols)

Catalog (public, no backend)

Proxied to backend

Detail pages

Common error codes

Save payload — `SaveComponentPayload`

​Catalog (public, no backend)

​Proxied to backend

​Detail pages

​Common error codes

​Save payload — SaveComponentPayload

Catalog (public, no backend)

Proxied to backend

Detail pages

Common error codes

Save payload — `SaveComponentPayload`