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

> AI PCB-footprint generation on Trace Footprints — request/response, the camelCase transform, plan gating, and a full example.

`POST /api/generate/footprint` proxies to `POST /api/v3/components/generate/footprint`. The
backend runs a **parametric IPC-7351B engine** — it selects the land-pattern family and
package dimensions from your description/datasheet, then computes and renders a
`.kicad_mod` server-side (returning the IPC land-pattern name and a compliance report).
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="package_type" type="string">Optional package hint (e.g. `QFN`, `SOIC`).</ParamField>
<ParamField body="datasheet_url" type="string">Optional datasheet to ground generation.</ParamField>

## Response — `GenerateFootprintResult`

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

<ResponseField name="footprintName" type="string">From backend `name`.</ResponseField>
<ResponseField name="kicadMod" type="string | null">Rendered `.kicad_mod` (backend `kicad_mod`).</ResponseField>
<ResponseField name="padCount" type="number">From `pad_count`.</ResponseField>
<ResponseField name="pads" type="Array<{ number, type }>">Derived from `trace_json.pads`.</ResponseField>
<ResponseField name="traceJson" type="object">The structured payload (used for save).</ResponseField>

<ResponseField name="description / source / note" type="…" />

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://footprints.buildwithtrace.com/api/generate/footprint \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d '{"description":"QFN-16 3x3mm 0.5mm pitch","package_type":"QFN"}'
  ```

  ```ts TypeScript theme={null}
  import { generateFootprint } from "@/lib/api";
  const { data, status } = await generateFootprint("QFN-16 3x3mm 0.5mm pitch", { package_type: "QFN" });
  if (data.success) console.log(data.footprintName, data.padCount, data.kicadMod);
  ```

  ```json Response theme={null}
  { "success": true, "footprintName": "QFN-16_3x3mm_P0.5mm",
    "description": "QFN-16, 3x3mm, 0.5mm pitch", "kicadMod": "(footprint \"QFN-16…\" …)",
    "padCount": 16, "pads": [ { "number": "1", "type": "smd" } ],
    "traceJson": { /* … */ }, "source": "generated" }
  ```
</CodeGroup>

## Errors

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

<Warning>
  AI-generated footprints are a starting point. Always verify pad geometry, courtyard, and
  spacing against the datasheet and your fab's IPC rules before manufacturing.
</Warning>

After generating you can [copy or download](/platforms/footprints/clipboard-and-download) the
`.kicad_mod`, or [save it](/platforms/footprints/saved-and-community) to the user's account
(pass `type: "footprint"`).