Developers · API · CLI · MCP

The whole pipeline, programmable.

Gate hardware in CI the way you gate code. Build board design into your own tool. Or give an AI agent the ability to design real, manufacturable hardware, not just describe it.

Everything Compose does in the browser is available over a REST API. A prompt goes in. A routed, DRC gated PCBA, a real CAD enclosure, simulations, firmware and manufacturing docs come out. Drive it from CI with the CLI, or hand it to an AI agent as MCP tools.

Paste the whole reference into Claude, Cursor or ChatGPT so it can build with FirstLight for you.

Quickstart

Mint an API key in Compose under Integrations. Keys start read only. Creating builds needs the read_write scope. Then

terminal
export FIRSTLIGHT_API_KEY=flk_live_...

curl -X POST https://compose.firstlight.build/api/v1/boards \
  -H "Authorization: Bearer $FIRSTLIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "USB-C powered desk presence puck with a 60GHz radar module and an LED status ring"}'

# 202 { "runId": "run-…", "status": "queued", "statusUrl": "/api/v1/runs/run-…" }

A full build takes about seven minutes and runs the same gates as the app. Electronics passes only when the board routes clean with zero DRC errors, the enclosure carries a real fit check, and every simulation is labeled with its fidelity and the tool that produced it. Builds are queued and run one at a time.

REST API

All endpoints authenticate with Authorization: Bearer flk_live_… and live under /api/v1.

POST/api/v1/boards

Start a build from a prompt (read_write scope). Returns 202 with a runId immediately. The run is owned by the key's creator and private to that account. Pass rebuildRunId instead of a prompt to re-verify an existing run. Stages whose inputs are provably unchanged skip as current, so a rebuild only pays for what changed.

GET/api/v1/runs/

Build status. Per stage progress across electronics, mechanical, simulation, firmware, manufacturing, supply chain and validation, plus the honest electronics verdict and wall clock timing.

GET/api/v1/runs//artifacts

Inventory of what the run actually produced. Only files that exist on disk are listed. Nothing is promised that was not built.

GET/api/v1/runs//artifacts/

Download one artifact. Kinds include step, glb, schematic, layout, pcb, bom, fab-package, firmware, simulation and the discipline reports.

GET/api/v1/boards

The enterprise board portfolio visible to this key.

poll until complete
curl -s https://compose.firstlight.build/api/v1/runs/$RUN_ID \
  -H "Authorization: Bearer $FIRSTLIGHT_API_KEY"

# { "status": "running",
#   "stages": { "electronics": { "status": "passed",
#                "detail": "chip-scale board 29×29mm · routed clean, 0 DRC errors" }, … } }

Limits

  • Prompt length — 8 to 2000 characters. Outside that range returns 400. (A rebuild carries no prompt.)
  • Build queue — up to five builds may be pending per instance. A sixth returns 429; retry once one drains.
  • Serialized — builds run one at a time. POST /boards returns your queuePosition immediately, then the pipeline runs in the background.
  • Build time — a full run takes about seven minutes. Poll statusUrl; do not hold the connection open.
  • Credits — each build spends a platform run-credit. Plan credits reset monthly (use-or-lose); purchased credits roll over. Frontier-model builds are plan-gated — see 402.
  • Key scope — read can poll and download; read_write is required to create or import.

Status codes

  • 202 — build accepted and queued.
  • 400 — bad input (prompt length, wrong file types).
  • 401 — missing, invalid, or revoked key (creating needs read_write).
  • 402 — plan gate: your plan or credits do not allow the requested model. Upgrade, or bring your own LLM key.
  • 403 — the run is not owned by your key.
  • 404 — unknown run.
  • 429 — build queue full (five pending). Retry later.

Artifact kinds

Every kind you can pass to /artifacts/<kind>. Only kinds the run actually produced appear in its inventory.

  • spec — resolved product spec (JSON)
  • board — placements, nets, board stats (JSON)
  • schematic — schematic (SVG)
  • layout — layout (SVG)
  • pcb — KiCad .kicad_pcb
  • fab-package — Gerbers, drill, BOM, CPL (zip)
  • bom — bill of materials (CSV)
  • step — enclosure (STEP)
  • glb — enclosure (GLB)
  • mechanical — mechanical fit report (JSON)
  • firmware — firmware (zip)
  • simulation — simulation report
  • manufacturing — manufacturing report
  • supply-chain — sourcing report
  • validation — validation report
  • id-brief — industrial-design brief
  • concept-render — concept render (JPG)
  • timing — per-stage timing (JSON)

CLI

Install once, then it wraps the API for terminals and CI. Set FIRSTLIGHT_API_KEY; for self-hosted instances also set FIRSTLIGHT_URL.

install
npm install -g firstlight
export FIRSTLIGHT_API_KEY=flk_live_...

The firstlight CLI wraps the API for terminals and CI. build --wait exits 0 only when every stage finishes green, so a pipeline job can gate on it directly.

terminal
firstlight build "USB-C ambient air quality tile with an SGP40 VOC sensor" --wait
#   run run-… queued (position 0)
#   running (pipeline)  ✓ electronics  … mechanical  … firmware …
#   complete  ✓ electronics ✓ mechanical ✓ simulation ✓ firmware ✓ manufacturing ✓ supplyChain ✓ validation

firstlight artifacts <runId>
firstlight get <runId> step -o enclosure.step
firstlight get <runId> fab-package -o fab.zip
firstlight status <runId> --watch
firstlight boards

Add --json to any command for machine output. Set FIRSTLIGHT_API_KEY and, for self hosted instances, FIRSTLIGHT_URL.

MCP for AI agents

firstlight-mcp exposes the pipeline as Model Context Protocol tools, so Claude Code, Cursor or any MCP client can design and fetch real hardware in a conversation.

Claude Code
claude mcp add firstlight \
  -e FIRSTLIGHT_API_KEY=flk_live_... \
  -- npx firstlight-mcp

Five tools, mapped one to one onto the API

  • create_board starts a build from a prompt and returns the runId
  • board_status reports stage progress and the honest electronics verdict
  • list_artifacts lists what the run actually produced
  • get_artifact downloads a file locally, or returns small JSON and SVG artifacts inline
  • list_boards lists the board portfolio

The honesty contract

The API is the same pipeline as the app, with the same gates. A board passes only when it routes clean with zero DRC errors from a real KiCad check. The enclosure fit check compares the actual PCB against the actual cavity. Simulations state their fidelity and solver on every result, and metrics that cannot be computed are reported as gated, never invented. Artifact listings contain only files that exist.

If the machine could not verify it, the API will not claim it.