The breadboardhub API for your app

Check, simulate and design electronic circuits and Verilog chips from any app over plain HTTPS, including apps made in AI app builders such as Replit, Lovable, Bolt and v0. Every circuit comes back with a link that opens it running live in the browser, and designs come with the parts to buy.

1. Get a token

Create an API token in Settings, API tokens (a free account is enough). It starts with bbh_ and is shown once. Send it on every request:

Authorization: Bearer bbh_your_token
Keep the token on a server. The API accepts calls from browsers, but a token written into browser code can be read by anyone who opens your app, and they can then spend your daily limit. Put it in your builder's secrets (Replit Secrets, Supabase secrets, Vercel or Netlify environment variables) and call breadboardhub from a server function, as in the examples below. If a token leaks, revoke it in Settings and make a new one.

2. Call an endpoint

Every endpoint takes a JSON body and answers JSON. Circuits use the CircuitJS text format; anywhere a circuit goes, a breadboardhub /sim link works too.

EndpointWhat it doesCost
POST /api/v1/circuits/checkCheck a circuitFree
POST /api/v1/circuits/simulateSimulate a circuitSimulation limit
POST /api/v1/circuits/designDesign a circuitDesign limit
POST /api/v1/circuits/editChange a circuitDesign limit
POST /api/v1/chips/designDesign a digital chip in VerilogDesign limit
POST /api/v1/calculateRun an electronics calculatorFree

The free endpoints work without a token too. The full schema of every request and answer is in the OpenAPI spec, which many builders and API tools can import: https://www.breadboardhub.com/api/v1/openapi.json.

Answers carry a message (the whole result in plain words, ready to show), the result fields, and sim_url, which opens the circuit running live. Designs and edits also return parts_to_buy, with supplier links that may earn breadboardhub a commission; say so wherever you show them.

Daily limits

Per token, per dayFree accountPro account
Designs, edits and chips1050
Simulations100300

Limits reset at 00:00 UTC and are shared with the MCP server: a token has one allowance however it is used. Costly answers include usage with what is left today. Checking circuits and the calculators are free.

Errors

Errors are JSON { "error": "...", "code": "..." }. Branch on code; show error.

  • 400 invalid_json, invalid_input: the body is wrong; a circuit that is not accepted lands here too.
  • 401 missing_token, invalid_token: no token, or it was revoked.
  • 429 daily_limit: the token's allowance is used up. The answer has reset_at and, on a free account, upgrade_url for Pro. rate_limited: too many requests a minute.
  • 422 not_completed: it ran but nothing usable came back. Try again or reword the request.
  • 503 busy (retry in a few seconds), platform_budget (breadboardhub's daily budget for everyone is spent), unavailable.

Examples

curl

curl -X POST https://www.breadboardhub.com/api/v1/circuits/design \ -H "Authorization: Bearer $BREADBOARDHUB_TOKEN" \ -H "Content-Type: application/json" \ -d '{"description": "A 9V battery lighting a red LED through a resistor"}'

Lovable or any Supabase app: an edge function

The function holds the token; the app calls the function, never breadboardhub directly.

// supabase/functions/circuit/index.ts // Set the secret first: supabase secrets set BREADBOARDHUB_TOKEN=bbh_... const cors = { "Access-Control-Allow-Origin": "*", "Access-Control-Allow-Headers": "authorization, apikey, content-type", }; Deno.serve(async (req) => { if (req.method === "OPTIONS") return new Response(null, { headers: cors }); const { description } = await req.json(); const res = await fetch("https://www.breadboardhub.com/api/v1/circuits/design", { method: "POST", headers: { "Authorization": `Bearer ${Deno.env.get("BREADBOARDHUB_TOKEN")}`, "Content-Type": "application/json", }, body: JSON.stringify({ description }), }); return new Response(await res.text(), { status: res.status, headers: { ...cors, "Content-Type": "application/json" }, }); });
// In the app's frontend (no breadboardhub token here): const { data, error } = await supabase.functions.invoke("circuit", { body: { description: "A 9V battery lighting a red LED through a resistor" }, });

Replit (Node)

// Add BREADBOARDHUB_TOKEN in the Secrets tool; it arrives as an env var. const res = await fetch("https://www.breadboardhub.com/api/v1/circuits/check", { method: "POST", headers: { "Authorization": `Bearer ${process.env.BREADBOARDHUB_TOKEN}`, "Content-Type": "application/json", }, body: JSON.stringify({ circuit: myCircuit }), }); const result = await res.json(); if (!res.ok) throw new Error(`${result.code}: ${result.error}`); console.log(result.ok, result.problems, result.sim_url);

Replit (Python)

# Add BREADBOARDHUB_TOKEN in the Secrets tool; it arrives as an env var. import os import requests res = requests.post( "https://www.breadboardhub.com/api/v1/circuits/simulate", headers={"Authorization": f"Bearer {os.environ['BREADBOARDHUB_TOKEN']}"}, json={"circuit": my_circuit}, timeout=60, ) result = res.json() if not res.ok: raise RuntimeError(f"{result['code']}: {result['error']}") print(result["status"], result["problems"], result["sim_url"])

Next.js (v0, Bolt or your own): a server route

Designs can take up to two minutes, so give the route enough time. Set BREADBOARDHUB_TOKEN in your host's environment variables.

// app/api/circuit/route.ts (the token stays on the server) export const maxDuration = 120; export async function POST(req: Request) { const { description } = await req.json(); const res = await fetch("https://www.breadboardhub.com/api/v1/circuits/design", { method: "POST", headers: { "Authorization": `Bearer ${process.env.BREADBOARDHUB_TOKEN}`, "Content-Type": "application/json", }, body: JSON.stringify({ description }), }); return Response.json(await res.json(), { status: res.status }); }

Worked example: ESP32 weather station app with verified wiring

Say your app helps someone build a weather station. One server function designs the wiring, runs it in the simulator and hands back everything the person needs: a live circuit to look at, the sketch to flash and the parts to order.

// Server side only: design the wiring, then simulate it. const API = "https://www.breadboardhub.com/api/v1"; const headers = { "Authorization": `Bearer ${process.env.BREADBOARDHUB_TOKEN}`, "Content-Type": "application/json", }; const post = async (path, body) => { const res = await fetch(API + path, { method: "POST", headers, body: JSON.stringify(body) }); const json = await res.json(); if (!res.ok) throw new Error(`${json.code}: ${json.error}`); return json; }; // 1. Design: the circuit, an Arduino sketch and the parts to buy. const design = await post("/circuits/design", { description: "An ESP32 weather station: a BME280 sensor on I2C for temperature, " + "humidity and pressure, powered from 5V USB through a 3.3V regulator, " + "with a status LED on a GPIO pin", }); // 2. Simulate the circuit it returned. const sim = await post("/circuits/simulate", { circuit: design.circuit }); // 3. Show the person what came back. return { wiringOk: design.verdict !== "failed" && sim.status === "ok", faults: [...design.problems, ...sim.problems], liveCircuit: sim.sim_url, // opens it running on breadboardhub sketch: design.code, // the Arduino sketch for the ESP32 partsToBuy: design.parts_to_buy, };

What "verified" means here: the design passed breadboardhub's structural checks and the simulator ran the circuit and found no faults (no short circuit, nothing over its rating, power reaching every part). The simulator checks the electrical side; it does not run the ESP32's firmware, and it is not a guarantee for a physical build, since real parts have tolerances the simulator does not model. Show the person the sim_url so they can see the circuit for themselves. To change the design, send the circuit to /api/v1/circuits/edit with what to change, then simulate it again.

Or connect over MCP

The same tools are available as a Model Context Protocol server. If the tool you build with lets you connect remote MCP servers, you can add this address instead of calling the REST API; check its documentation for whether it does and how:

https://www.breadboardhub.com/api/mcp

Setup for Claude, Cursor and VS Code is on the MCP page. Send the same API token as an Authorization header to use your own limits.

Your data

Descriptions and change requests you send to design or edit are processed by Anthropic to produce the result, and we store them with the result, linked to your token's account. Circuits you only check or simulate are not stored. Details are in our Privacy Policy. Questions: contact us.