Trace Symbols — AI Generation API

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

string

required

Bearer <access_token>

string

required

5–5000 characters.

string

Optional datasheet to ground generation.

string

Optional layout/pin hints.

Response — `GenerateSymbolResult`

boolean

string

From backend name.

string | null

Rendered .kicad_sym (backend kicad_sym).

number

From pin_count.

string

Reference prefix, e.g. U (from reference_prefix).

Array<{ number, name, type }>

string[]

object

The structured TraceSymbolV1 payload (used for clipboard/save).

Array<{ step, status, duration_ms, warnings }>

…

Example

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"}'

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);

{ "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": { /* … */ } }

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

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.

After a successful generation you can copy or download the .kicad_sym, or save it to the user’s account.

Getting Started

Core Concepts

Guides

Generate Symbols

Request

Response — `GenerateSymbolResult`

Example

Errors

​Request

​Response — GenerateSymbolResult

​Example

​Errors

Request

Response — `GenerateSymbolResult`

Example

Errors