{"openapi":"3.1.0","info":{"title":"breadboardhub circuits API","version":"1.0.0","description":"Check, simulate and design electronic circuits and Verilog chips over HTTPS. The same tools as the breadboardhub MCP server, with the same daily limits. Send an API token from https://www.breadboardhub.com/settings/tokens as \"Authorization: Bearer bbh_...\". Keep the token on a server: anyone who can read your browser code can use it. Guide: https://www.breadboardhub.com/developers"},"servers":[{"url":"https://www.breadboardhub.com"}],"paths":{"/api/v1/circuits/check":{"post":{"operationId":"checkCircuit","summary":"Check a circuit","description":"Free and instant. Checks a CircuitJS circuit for structural problems: unknown parts, loose ends, parts with no power source, LEDs with the wrong diode model. With \"request\", also checks it has the parts asked for. A token is optional here.","security":[{"bearerAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"circuit":{"type":"string","minLength":1,"maxLength":40000,"description":"The circuit: a CircuitJS export (a \"$\" options line, then one part per line, at most 20,000 characters), or a breadboardhub.com/sim link that carries one."},"request":{"type":"string","maxLength":1000,"description":"What the circuit is meant to be, in plain words (at most 1,000 characters)."}},"required":["circuit"],"additionalProperties":false},"example":{"circuit":"$ 1 0.000005 10.2 50 5 50\nv 144 320 144 80 0 0 40 9 0 0 0.5\nr 144 80 400 80 0 330\n162 400 80 400 320 2 default-led 1 0 0 0.01\nw 400 320 144 320 0"}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"The whole result in plain words, ready to show a person."},"ok":{"type":"boolean","description":"True when no problems were found. That does not prove it works: simulate it for that."},"problems":{"type":"array","items":{"type":"string"},"description":"Problems found, in plain words. Empty when none."},"parts":{"type":"array","items":{"type":"string"},"description":"The parts in the circuit, in plain words."},"sim_url":{"type":["string","null"],"description":"Opens the circuit running live on breadboardhub, where it can be changed and saved. Null when the circuit is too long for a link."}},"required":["message"]}}}},"400":{"description":"The request body is not valid JSON, does not match the schema, or the circuit was not accepted. code: invalid_json, invalid_input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API token (costly endpoints), or the token is not valid or has been revoked. code: missing_token, invalid_token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is over 64 KB. code: too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The tool ran but produced no result, for example the model declined or the simulator could not run the circuit. code: not_completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A limit was reached. code: daily_limit (the token's daily allowance; see reset_at and upgrade_url) or rate_limited (too many requests a minute). Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not available right now. code: platform_budget (breadboardhub's daily budget for everyone is spent; see reset_at), busy (the simulator is busy; retry in a few seconds), disabled or unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/circuits/simulate":{"post":{"operationId":"simulateCircuit","summary":"Simulate a circuit","description":"Runs a CircuitJS circuit in a real circuit simulator until it settles and returns the voltage across and current through each part, plus faults found: a short circuit, nothing flowing, an LED over its rating, a bulb too dim to light. Takes 10 to 30 seconds. Counts toward the daily simulation limit. Daily limit per token: 100 on a free account, 300 on Pro.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"circuit":{"type":"string","minLength":1,"maxLength":40000,"description":"The circuit: a CircuitJS export (a \"$\" options line, then one part per line, at most 20,000 characters), or a breadboardhub.com/sim link that carries one."}},"required":["circuit"],"additionalProperties":false},"example":{"circuit":"$ 1 0.000005 10.2 50 5 50\nv 144 320 144 80 0 0 40 9 0 0 0.5\nr 144 80 400 80 0 330\n162 400 80 400 320 2 default-led 1 0 0 0.01\nw 400 320 144 320 0"}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"The whole result in plain words, ready to show a person."},"status":{"type":"string","description":"\"ok\" when it settled with no faults, \"problems\" when faults were found."},"problems":{"type":"array","items":{"type":"string"},"description":"Problems found, in plain words. Empty when none."},"summary":{"type":["string","null"],"description":"A one-line summary of the readings."},"measurements":{"type":"array","items":{"type":"object"},"description":"One reading per part once settled: its type, the voltage across it (v) and the current through it (i)."},"sim_url":{"type":["string","null"],"description":"Opens the circuit running live on breadboardhub, where it can be changed and saved. Null when the circuit is too long for a link."},"usage":{"$ref":"#/components/schemas/Usage"}},"required":["message"]}}}},"400":{"description":"The request body is not valid JSON, does not match the schema, or the circuit was not accepted. code: invalid_json, invalid_input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API token (costly endpoints), or the token is not valid or has been revoked. code: missing_token, invalid_token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is over 64 KB. code: too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The tool ran but produced no result, for example the model declined or the simulator could not run the circuit. code: not_completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A limit was reached. code: daily_limit (the token's daily allowance; see reset_at and upgrade_url) or rate_limited (too many requests a minute). Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not available right now. code: platform_budget (breadboardhub's daily budget for everyone is spent; see reset_at), busy (the simulator is busy; retry in a few seconds), disabled or unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/circuits/design":{"post":{"operationId":"designCircuit","summary":"Design a circuit","description":"Designs a circuit (and an Arduino sketch, for microcontroller projects) from a plain description. The design passes breadboardhub's structural checks, with one corrected attempt if needed. It is not simulated: call /api/v1/circuits/simulate on it before presenting it as working. Takes up to 2 minutes. Counts toward the daily design limit. Daily limit per token: 10 on a free account, 50 on Pro.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","minLength":10,"maxLength":1000,"description":"What to design, in plain words (10 to 1,000 characters)."}},"required":["description"],"additionalProperties":false},"example":{"description":"A 9V battery lighting a red LED through a current-limiting resistor"}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"The whole result in plain words, ready to show a person."},"verdict":{"type":"string","description":"\"passed\", \"fixed\" (passed after one correction), \"failed\" (still has problems) or \"unchecked\" (code only)."},"problems":{"type":"array","items":{"type":"string"},"description":"Problems found, in plain words. Empty when none."},"circuit":{"type":["string","null"],"description":"The circuit, as CircuitJS text."},"code":{"type":["string","null"],"description":"The Arduino sketch, when there is one."},"sim_url":{"type":["string","null"],"description":"Opens the circuit running live on breadboardhub, where it can be changed and saved. Null when the circuit is too long for a link."},"parts_to_buy":{"type":"array","items":{"type":"object"},"description":"The parts needed to build the circuit, each with a quantity, a description and supplier search links. The links may earn breadboardhub a commission; say so wherever they are shown."},"usage":{"$ref":"#/components/schemas/Usage"}},"required":["message"]}}}},"400":{"description":"The request body is not valid JSON, does not match the schema, or the circuit was not accepted. code: invalid_json, invalid_input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API token (costly endpoints), or the token is not valid or has been revoked. code: missing_token, invalid_token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is over 64 KB. code: too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The tool ran but produced no result, for example the model declined or the simulator could not run the circuit. code: not_completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A limit was reached. code: daily_limit (the token's daily allowance; see reset_at and upgrade_url) or rate_limited (too many requests a minute). Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not available right now. code: platform_budget (breadboardhub's daily budget for everyone is spent; see reset_at), busy (the simulator is busy; retry in a few seconds), disabled or unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/circuits/edit":{"post":{"operationId":"editCircuit","summary":"Change a circuit","description":"Changes a circuit as asked in plain words (\"make the two resistors parallel\", \"add a voltmeter across the LED\"), or answers a question about it. A change that would break the circuit is refused. Takes up to a minute. Counts toward the daily design limit. Daily limit per token: 10 on a free account, 50 on Pro.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"circuit":{"type":"string","minLength":1,"maxLength":40000,"description":"The circuit: a CircuitJS export (a \"$\" options line, then one part per line, at most 20,000 characters), or a breadboardhub.com/sim link that carries one."},"change":{"type":"string","minLength":3,"maxLength":1000,"description":"What to change, or a question about the circuit (3 to 1,000 characters)."},"purpose":{"type":"string","maxLength":1000,"description":"What the circuit is for (at most 1,000 characters). Helps keep the change in line with it."}},"required":["circuit","change"],"additionalProperties":false},"example":{"circuit":"$ 1 0.000005 10.2 50 5 50\nv 144 320 144 80 0 0 40 9 0 0 0.5\nr 144 80 400 80 0 330\n162 400 80 400 320 2 default-led 1 0 0 0.01\nw 400 320 144 320 0","change":"Add an ammeter in series with the LED"}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"The whole result in plain words, ready to show a person."},"kind":{"type":"string","description":"\"change\" when the circuit was changed, \"answer\" when the request was a question."},"summary":{"type":"string","description":"What was changed (kind \"change\")."},"answer":{"type":"string","description":"The answer (kind \"answer\")."},"problems":{"type":"array","items":{"type":"string"},"description":"Problems found, in plain words. Empty when none."},"circuit":{"type":"string","description":"The changed circuit, as CircuitJS text (kind \"change\")."},"sim_url":{"type":["string","null"],"description":"Opens the circuit running live on breadboardhub, where it can be changed and saved. Null when the circuit is too long for a link."},"parts_to_buy":{"type":"array","items":{"type":"object"},"description":"The parts needed to build the circuit, each with a quantity, a description and supplier search links. The links may earn breadboardhub a commission; say so wherever they are shown."},"usage":{"$ref":"#/components/schemas/Usage"}},"required":["message"]}}}},"400":{"description":"The request body is not valid JSON, does not match the schema, or the circuit was not accepted. code: invalid_json, invalid_input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API token (costly endpoints), or the token is not valid or has been revoked. code: missing_token, invalid_token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is over 64 KB. code: too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The tool ran but produced no result, for example the model declined or the simulator could not run the circuit. code: not_completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A limit was reached. code: daily_limit (the token's daily allowance; see reset_at and upgrade_url) or rate_limited (too many requests a minute). Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not available right now. code: platform_budget (breadboardhub's daily budget for everyone is spent; see reset_at), busy (the simulator is busy; retry in a few seconds), disabled or unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/chips/design":{"post":{"operationId":"designChip","summary":"Design a digital chip in Verilog","description":"Writes a synthesizable Verilog module and a step-by-step test from a plain description, builds it with Yosys and runs the test on the built circuit, correcting it up to twice. \"verified\" means it built clean and every test step passed; the AI wrote the test too, so check it. Takes up to 4 minutes. Counts toward the daily design limit. Daily limit per token: 10 on a free account, 50 on Pro.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":"string","minLength":3,"maxLength":1000,"description":"The digital circuit wanted, in plain words (3 to 1,000 characters)."}},"required":["description"],"additionalProperties":false},"example":{"description":"A 4-bit counter with enable and synchronous reset"}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"The whole result in plain words, ready to show a person."},"verdict":{"type":"string","description":"\"verified\", \"built\" (compiles, test not confirmed) or \"failed\"."},"summary":{"type":["string","null"],"description":"What the module is."},"problems":{"type":"array","items":{"type":"string"},"description":"Problems found, in plain words. Empty when none."},"code":{"type":["string","null"],"description":"The Verilog source."},"test":{"type":["object","null"],"description":"The test: a clock and the steps, each with inputs and the outputs expected."},"attempts":{"type":"integer","description":"How many attempts it took."},"chip_url":{"type":["string","null"],"description":"Opens the design on breadboardhub with its diagram, waveforms and test."},"usage":{"$ref":"#/components/schemas/Usage"}},"required":["message"]}}}},"400":{"description":"The request body is not valid JSON, does not match the schema, or the circuit was not accepted. code: invalid_json, invalid_input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API token (costly endpoints), or the token is not valid or has been revoked. code: missing_token, invalid_token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is over 64 KB. code: too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The tool ran but produced no result, for example the model declined or the simulator could not run the circuit. code: not_completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A limit was reached. code: daily_limit (the token's daily allowance; see reset_at and upgrade_url) or rate_limited (too many requests a minute). Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not available right now. code: platform_budget (breadboardhub's daily budget for everyone is spent; see reset_at), busy (the simulator is busy; retry in a few seconds), disabled or unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/calculate":{"post":{"operationId":"calculate","summary":"Run an electronics calculator","description":"Free and instant. Runs one of breadboardhub's calculators (LED resistor, resistor color code, 555 timer, voltage divider and more) and returns the answer with a link to the circuit running live. Values may use SI prefixes (\"4.7k\", \"100n\"). Inputs left out take the calculator's example values. A token is optional here.","security":[{"bearerAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"calculator":{"type":"string","enum":["resistor-color-code","led-resistor","voltage-divider","rc-time-constant","ohms-law","series-parallel-resistor","transistor-base-resistor","555-timer","pcb-trace-width","battery-life","rc-filter","capacitor-code"],"description":"Which calculator."},"inputs":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","maxLength":40},{"type":"number"}]},"description":"The calculator's inputs by name, such as { \"supplyV\": \"9\", \"ledV\": \"2\", \"currentA\": \"15m\" }."}},"required":["calculator"],"additionalProperties":false},"example":{"calculator":"led-resistor","inputs":{"supplyV":"9","ledV":"2","currentA":"15m"}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"The whole result in plain words, ready to show a person."},"calculator":{"type":"string","description":"The calculator that ran."},"results":{"type":"array","items":{"type":"object"},"description":"The answer, as label and value pairs."},"note":{"type":["string","null"],"description":"Anything to watch out for."},"defaults_used":{"type":"array","items":{"type":"string"},"description":"Inputs that took the example value."},"sim_url":{"type":["string","null"],"description":"Opens the circuit running live on breadboardhub, where it can be changed and saved. Null when the circuit is too long for a link."},"page_url":{"type":"string","description":"The calculator's page on breadboardhub."}},"required":["message"]}}}},"400":{"description":"The request body is not valid JSON, does not match the schema, or the circuit was not accepted. code: invalid_json, invalid_input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API token (costly endpoints), or the token is not valid or has been revoked. code: missing_token, invalid_token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is over 64 KB. code: too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The tool ran but produced no result, for example the model declined or the simulator could not run the circuit. code: not_completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A limit was reached. code: daily_limit (the token's daily allowance; see reset_at and upgrade_url) or rate_limited (too many requests a minute). Retry-After says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not available right now. code: platform_budget (breadboardhub's daily budget for everyone is spent; see reset_at), busy (the simulator is busy; retry in a few seconds), disabled or unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API token (bbh_...) from https://www.breadboardhub.com/settings/tokens."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong, in plain words."},"code":{"type":"string","description":"A stable code to branch on."},"details":{"type":"array","items":{"type":"string"},"description":"The fields that did not validate (invalid_input)."},"limit":{"type":"integer","description":"The daily allowance that was reached (daily_limit)."},"reset_at":{"type":"string","format":"date-time","description":"When the daily counts reset: the next 00:00 UTC."},"upgrade_url":{"type":"string","description":"Where a free account upgrades to Pro for a higher limit."}},"required":["error","code"]},"Usage":{"type":"object","description":"The token's daily allowance for this kind of call, after this call.","properties":{"allowance":{"type":"string","description":"\"design\" (designs, edits and chips share it) or \"simulate\"."},"limit":{"type":"integer"},"remaining":{"type":"integer"},"reset_at":{"type":"string","format":"date-time"}}}}}}