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

# Generate Symbols

> AI schematic-symbol generation on Trace Symbols — request/response, the camelCase transform, plan gating, and a full example.

`POST /api/generate` proxies to `POST /api/v3/components/generate/symbol`. The backend runs
the AI agent; the route validates input and maps the response to camelCase. **Requires a
bearer token** and a plan that includes generation.

## Request

<ParamField header="Authorization" type="string" required>`Bearer <access_token>`</ParamField>
<ParamField body="description" type="string" required>5–5000 characters.</ParamField>
<ParamField body="datasheet_url" type="string">Optional datasheet to ground generation.</ParamField>
<ParamField body="additional_instructions" type="string">Optional layout/pin hints.</ParamField>

## Response — `GenerateSymbolResult`

<ResponseField name="success" type="boolean" />

<ResponseField name="symbolName" type="string">From backend `name`.</ResponseField>
<ResponseField name="kicadSym" type="string | null">Rendered `.kicad_sym` (backend `kicad_sym`).</ResponseField>
<ResponseField name="pinCount" type="number">From `pin_count`.</ResponseField>
<ResponseField name="reference" type="string">Reference prefix, e.g. `U` (from `reference_prefix`).</ResponseField>

<ResponseField name="pins" type="Array<{ number, name, type }>" />

<ResponseField name="footprint_filters" type="string[]" />

<ResponseField name="traceJson" type="object">The structured TraceSymbolV1 payload (used for clipboard/save).</ResponseField>

<ResponseField name="steps" type="Array<{ step, status, duration_ms, warnings }>" />

<ResponseField name="keywords / description / datasheet / warning" type="…" />

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://symbols.buildwithtrace.com/api/generate \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"description":"ATmega328P MCU, 28-pin DIP with SPI, I2C, UART"}'
  ```

  ```ts TypeScript theme={null}
  import { generateSymbol } from "@/lib/api";
  const { data, status } = await generateSymbol(
    "ATmega328P MCU, 28-pin DIP with SPI, I2C, UART",
    { datasheet_url: "https://…/atmega328p.pdf" },
  );
  if (data.success) console.log(data.symbolName, data.pinCount, data.kicadSym);
  ```

  ```json Response theme={null}
  { "success": true, "symbolName": "ATmega328P", "kicadSym": "(kicad_symbol_lib …)",
    "pinCount": 28, "reference": "U", "pins": [ { "number": "1", "name": "PC6", "type": "input" } ],
    "footprint_filters": ["DIP*W7.62mm*"], "traceJson": { /* … */ } }
  ```
</CodeGroup>

## Errors

| Status        | Meaning                                |
| ------------- | -------------------------------------- |
| `400`         | Description too short/long             |
| `401`         | Missing/expired token                  |
| `402` / `403` | Plan/quota does not include generation |
| `504`         | Generation timed out                   |
| `502`         | Backend error                          |

<Warning>
  AI-generated symbols are a starting point. Always verify pin names, numbers, and types
  against the datasheet before using a generated symbol in a real design.
</Warning>

After a successful generation you can [copy or download](/platforms/symbols/clipboard-and-download)
the `.kicad_sym`, or [save it](/platforms/symbols/saved-and-community) to the user's account.