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

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

Base URL: `https://symbols.buildwithtrace.com`. Backend base: `https://api.buildwithtrace.com`.
Authenticated routes require `Authorization: Bearer <access_token>` (see
[Authentication](/platforms/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](/platforms/symbols/browse-and-search) — libraries, search, semantic, suggest, categories, thumbnails
* [Generate](/platforms/symbols/generate) — `/api/generate` request/response
* [Contribute](/platforms/symbols/contribute) — validate + submit
* [Saved & Community](/platforms/symbols/saved-and-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`

```ts theme={null}
{
  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;
}
```