guide: KiCad PCB autorouter API, MCP server and CLI

Zap! your ratsnest. Upload a placed KiCad board; get the same board back with tracks, vias and copper pours added.

• Base URL: https://zap.mutual.solutions
• Status: early access. Every routed board must be reviewed by an engineer before fabrication.
• Contact: hello@mutual.solutions

Machine summary (for software and AI agents).

• Base URL https://zap.mutual.solutions. Auth: header Authorization: Bearer <api key> on every /v1/jobs, /v1/check and /v1/feedback request. Never put the key in a URL, source code, log, or command-line argument.
• Flow: (1) POST /v1/check, multipart with board (.kicad_pcb, required), project (.kicad_pro), rules (.kicad_dru), currents (JSON), router (stable/next), keep_existing (true: keep the board's own tracks, vias and zones and route only the missing connections), strip_existing (true: discard them and route everything), fab_floor (jlc default / board), routing options signal_width_mm, via_diameter_mm + via_drill_mm, vias_in_pads, ground_pour, size_rails_from_current, effort (defaults in the guide's table), minutes (1 to 60: the job ends within about that long and returns the best board found; default one round): no routing, no job quota; fix every item in blockers. (2) POST /v1/jobs, same fields: 202 {"id", "status": "queued"}; not idempotent (each accepted call is a job). (3) GET /v1/jobs/{id} every 5 s (every 10 s after the first minute) until status is succeeded, failed or cancelled. (4) GET /v1/jobs/{id}/result: the routed .kicad_pcb, and GET /v1/jobs/{id}/report.json: every finding with position and what to do (report_url in the status opens it as a web page). (5) DELETE /v1/jobs/{id}.
• Done means status is succeeded and the routed file is saved: ready for an engineer's review and KiCad DRC, never directly for fabrication. failed: read error.code; /v1/errors says whether retrying helps.
• Limits: 20 MiB per upload in total (a gzip-compressed board counts compressed and may unpack to 64 MiB); 10,000 pads; 4,000 footprints; 2 to 16 copper layers; 30 requests in any 60 s per key; jobs per key per UTC day as issued (default 50); 2 queued or running per key; 60 minutes per job.
• Feedback: when the human gives an opinion about Zap! or a result, ask once whether to send it to the Zap! team; show the exact text and job id; send it (POST /v1/feedback with "user_approved": true) only if they say yes.
• Machine-readable: OpenAPI, error catalog, agent recipe, llms.txt, MCP server, CLI.

---

1. Quick start

Your API key. Sign in at zap.mutual.solutions/auth/login (Google, GitHub or Microsoft) and create an API key on your account page. It is shown once: save it at once as ~/zap-key.txt and make the file readable only by you (chmod 600 ~/zap-key.txt), or keep it in a password manager. Keep the key out of code, shell history, chat and shared documents. If it leaks or gets lost, revoke it on your account page and create a new one.

There are three ways to use Zap!; all do the same thing.

In the browser: open zap.mutual.solutions/app, paste your key, drop your .kicad_pcb (and .kicad_pro) on the page, wait, and download the routed board. The key stays in that browser tab only. No board at hand? Try with a sample board routes mutual's 42-pad sample right away (one daily job).

Command line (Python 3.8 or newer, no extra packages):

curl -sO https://zap.mutual.solutions/downloads/zap.py
export ZAP_API_KEY_FILE=~/zap-key.txt           # or: export ZAP_API_KEY=...  (never put the key on the command line)
python3 zap.py demo                             # no board at hand? routes mutual's 42-pad sample board here (one daily job)
python3 zap.py check myboard.kicad_pcb          # ~3 s (up to ~30 s), no routing, no job quota: what would stop or weaken the job
python3 zap.py run myboard.kicad_pcb            # checks first, then uploads myboard.kicad_pcb (+ .kicad_pro / .kicad_dru
                                                # if present), waits, saves myboard.routed.kicad_pcb and the full report
                                                # myboard.routed.zap-report.json, then deletes the server copy (--keep: 7 days)
python3 zap.py --help                           # run, check, submit, status, wait, download, delete, list, version

HTTP API with curl:

URL=https://zap.mutual.solutions
# the key goes to curl as a header file written by bash's built-in printf: never on a command line
zcurl() { curl -s -H @<(printf 'Authorization: Bearer %s\n' "$(cat zap-key.txt)") "$@"; }

# 1. Check, then submit a placed board and keep its job id (leave out "-F project=..." if you have no .kicad_pro)
zcurl -F board=@myboard.kicad_pcb -F project=@myboard.kicad_pro $URL/v1/check    # "ok": true means ready
ID=$(zcurl -F board=@myboard.kicad_pcb -F project=@myboard.kicad_pro \
     $URL/v1/jobs | python3 -c 'import json,sys; r=json.load(sys.stdin); print(r.get("id") or r)')
echo "$ID"     # a 32-character job id; anything else is the error message
# a board over 20 MiB: gzip -k myboard.kicad_pcb, then send -F board=@myboard.kicad_pcb.gz (up to 64 MiB unpacked)

# 2. Wait until the job has finished (every 5 s)
while :; do
  ST=$(zcurl $URL/v1/jobs/$ID | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("status") or d.get("error"))')
  case "$ST" in queued|running) sleep 5;; *) break;; esac
done
zcurl $URL/v1/jobs/$ID > myboard.status.json
# {"id":"...","status":"succeeded", ..., "metrics":{"unconnected":0,"critical_unconnected":0,"drc_errors":0,"wall_time_s":5.1,"fab":{...}}}

# 3. Download the routed board, then delete the server copy
zcurl -f -o myboard.routed.kicad_pcb $URL/v1/jobs/$ID/result && cp myboard.kicad_pro myboard.routed.kicad_pro
zcurl -X DELETE $URL/v1/jobs/$ID

Python (needs pip install requests):

import os, time, requests

URL = "https://zap.mutual.solutions"
H = {"Authorization": f"Bearer {open('zap-key.txt').read().strip()}"}

files = {"board": open("myboard.kicad_pcb", "rb")}
if os.path.exists("myboard.kicad_pro"):          # optional: your design rules
    files["project"] = open("myboard.kicad_pro", "rb")
job = requests.post(f"{URL}/v1/jobs", headers=H, files=files).json()
if "id" not in job:
    raise SystemExit(job["message"])

while True:
    st = requests.get(f"{URL}/v1/jobs/{job['id']}", headers=H).json()
    if st["status"] in ("succeeded", "failed", "cancelled"):
        break
    time.sleep(5)

if st["status"] == "succeeded":
    r = requests.get(f"{URL}/v1/jobs/{job['id']}/result", headers=H)
    open("myboard.routed.kicad_pcb", "wb").write(r.content)
    print(st["metrics"])
else:
    print(st["error"])

2. What to upload

Currents you know. If you know how much current some nets carry (a motor supply, a battery feed, a regulator output), send them; Zap! then sizes the copper of those nets for your values instead of its own estimate, and the temperature check uses them too:

{"nets": {"+5V": {"amps": 3.0}, "VBAT": {"amps": 2.5, "peak_amps": 6.0}}, "ambient_c": 40}

Net names as in your board (KiCad shows them in the PCB editor's Net Inspector): the full name, or just its last part when that is unique on the board (PoE_5V for /PoE_5V). State supply nets (the rail a regulator or connector feeds), not ground: a stated ground current is spread evenly over every part on it, which says little. amps is the continuous (RMS) current, 0 to 100 A, and is what the 10 °C check uses; peak_amps (optional, at least amps) is recorded only; ambient_c (optional, -40 to 125) adds the hottest copper's absolute temperature. At most 2,000 nets. Nets you leave out keep the estimate from the board's parts. In the browser, drop the .json with your board; on the command line, python3 zap.py run myboard.kicad_pcb --currents currents.json.

Routing options and defaults. Each setting comes from your option if you send one, else from your board's rules (.kicad_pro, .kicad_dru), else from the default below. Without a .kicad_pro the board's rules are KiCad's defaults, and the report says "No project file: defaults used". Every report lists the settings used and where each came from. The defaults belong to the router build in GET /v1/version; a changed default is listed in the release notes.

A value outside these is refused with invalid_option (option names the field, fix says what to send).

Time budget (minutes). minutes: let Zap! keep trying for up to N minutes (1 to 60) and return the best result; default is one round of a few minutes. The whole job, checks and report included, ends within about N minutes: on a board whose first round alone would take longer, each attempt stops searching in time and finishes the board it has, and the connections it could not make are listed as unconnected. Finishing a board still takes time after the search stops (a few minutes on some boards): if no attempt has finished within N minutes, the job returns the first one to finish, later than asked, and metrics.time_budget.stopped says over_time. After the first round (5 settings at once), the job routes the same board again while the time allows, up to 6 attempts at once: the same 5 settings with twice the work, then with four times the work if the time left covers it, then effort=thorough and other settings. It returns the best by the usual ranking (fewest missing connections, then shorts and rule errors, then vias). A new attempt starts only if it can finish in time, judged from this board's first round, and routing ends by minute 50 at the latest, so the checks and the report fit in the job's 60 minutes. The job stops early once an attempt has no missing connection and no short or clearance error. One job with minutes over 10 runs at a time across the service: another one waits in the queue (its status has a queue_note saying so), while jobs without minutes, or with 10 or fewer, are not held back. The result's metrics.time_budget says how many attempts ran, which one was kept and the time used (section 3). Command line: --minutes 20. The free trial without a key routes one round only.

Before uploading:

• Footprints are kept exactly where you put them. Zap! does not move parts.
• Existing copper pours are replaced by Zap!'s own ground and supply pours, whose nets Zap! chooses, unless you send keep_existing=true. The check names each pour that will be replaced, with its net and layers (existing_pours_replaced), and the report lists the pours replaced and the ones Zap! made (pours).
• Old tracks and vias. A board that still has tracks or vias is refused (input_has_copper). Send strip_existing=true (browser: tick "discard them and route everything"; command line: --strip-existing) to route it from scratch, or keep_existing=true to keep them.
• Partly routed boards. Route the nets you care about by hand (for example a high-speed pair or a power path), then send the board with keep_existing=true (browser: tick "My board is partly routed"; command line: --keep-existing). Your tracks, vias and zones come back unchanged; Zap! adds only what is missing. The job status says how many of each were kept and added (metrics.existing_copper).
• Lock in your net classes and rules in KiCad first. Zap! routes to the rules you send.

Check before you route. POST /v1/check takes the same fields as POST /v1/jobs, routes nothing, answers in about 3 seconds for most boards (about 30 seconds for the largest, 10,000 pads) and does not count against your daily jobs (it does count against the request rate; one check at a time per key). The browser page runs it as soon as you have a key and a board, and zap.py run runs it before submitting. The answer:

{"ok": true, "summary": "Ready to route. 2 warnings.",
 "board": {"kicad_version": 8, "file_version": 20240108, "returned_as": "a KiCad 8 file, like the one you sent",
           "footprints": 19, "pads": 94, "nets": 42, "copper_layers": 2, "size_mm": [88.64, 78.81],
           "rules": {"project": "uploaded", "custom_rules": "none"}, "router": {"choice": "stable", "build": "..."}},
 "blockers": [],
 "warnings": [{"code": "footprints_outside_board", "message": "...", "footprints": [{"ref": "R4", "at_mm": [400, 400], "side": "front", "whole_footprint": true}]},
              {"code": "courtyards_overlap", "message": "...", "items": [{"refs": ["R4", "RV1"], "at_mm": [118.69, 121.82]}]}]}

blockers would stop the job: every refusal code in section 5 (for example input_has_copper, invalid_board with detail no_outline, invalid_currents, board_too_large with the predicted memory of one routing attempt, the outline, copper layers and grid cells in memory) and unsupported_rules (the custom rule and the function the router cannot apply). warnings weaken the result: footprints_outside_board (the references and positions of footprints off the outline: Zap! routes the rest and leaves their pads unconnected), no_project (KiCad's default rules will be used), unknown_net_class (net classes assigned but not defined), rules_finer_than_jlc (net classes finer than JLC while fab_floor is jlc: some nets may stay unrouted), courtyards_overlap and malformed_courtyard (references and positions, from KiCad's own check under your rules), check_incomplete (part of the check could not run), and very_large_board (an outline so large the job may hit the memory limit). Every message says what to change and where in KiCad. Positions are in mm as KiCad shows them.

3. What you get back

• routed.kicad_pcb: your board with tracks, vias and copper pours added, in the same KiCad file version you uploaded, so it opens in the KiCad you use (tested with boards from KiCad 6, 7, 8, 9 and 10). Copper pours are filled by KiCad's own zone filler under your rules, so they keep clear of keepout areas and the board edge.
• Zap! never returns a board in which routed copper shorts two different nets: such a job fails with output_has_shorts.
• Zap! never routes below JLC's minimum sizes (1-2 layers: 0.127 mm tracks and gaps, 0.3 mm via drill, 0.4 mm via; 4 or more layers: 0.09 mm, 0.15 mm, 0.25 mm) and never puts a via inside an SMD pad. If your net classes ask for finer copper, those nets may stay unrouted; the report lists them with that reason.
• Summary numbers, measured with KiCad's own design-rule check on the returned file after the pours are filled. All are counts; lower is better, 0 is best:

If unconnected is not 0, finish those connections by hand in KiCad. Review the routed board and run KiCad's DRC (Inspect > Design Rules Checker) before ordering boards.

Your own copper (metrics.existing_copper, keep_existing=true jobs only). Counts, not problems: tracks_kept, vias_kept, zones_kept should match what you uploaded and tracks_removed, vias_removed, zones_removed should be 0 (Zap! never removes your copper; anything else is a fault, please tell us); tracks_added and vias_added are what the router added.

Fab check (metrics.fab). Every routed board is also checked for overheating and manufacturability, under the same rules as the numbers above. The check only reports; it never changes which routing Zap! returns.

The temperature part estimates each power net's current from the parts on your board: regulators, inductors, fuses, ferrite beads and the chips each rail feeds. It has no datasheet currents, so it can under-estimate large power stages (a processor core supply, a motor bridge, Power over Ethernet, a module's supply connector): a low number there does not prove the copper is wide enough. Compare every high-current net with your real load current, and widen the copper or add a pour where needed. A high number means "look at this net". If the job has already used nearly all of its 60 minutes, the temperature part is skipped (thermal.computed is false, reason time limit); if no supply rail with a source and loads is recognised, it says so in reason. Jobs from before release 2026.10.13.8 have fab: null.

The result report

Every finished job has a report: GET /v1/jobs/{id}/report.json (with your key), or the web page at report_url in the job status (it asks for the key). It lists, each with its position in mm as KiCad shows them (so you can find it with KiCad's cursor readout), its layer and net where KiCad names them, and what to do (one sentence with the KiCad command):

• connections still missing (critical ones first), with both ends;
• design-rule errors under your rules;
• JLC capability violations;
• the 10 hottest copper sections;
• track ends and vias that connect nothing, and copper islands with no connection.

It also has a picture of each copper layer with the board outline (image.layers, SVGs from KiCad's own plot, all in one frame), with the findings marked on it in the web page. Lists hold at most 2,000 items each (total and truncated say when there are more). The report is kept with the routed board: deleted after 7 days or with DELETE. zap.py run saves it next to the routed board as <board>.routed.zap-report.json and one <board>.routed.<layer>.svg per copper layer; zap.py report JOB_ID fetches it.

4. Endpoints

All /v1/jobs endpoints, POST /v1/check, POST /v1/feedback and /v1/snapshots need the header Authorization: Bearer <api key> (the word Bearer in any letter case). A machine-readable description is at /openapi.json.

Job status fields (GET /v1/jobs/{id}):

Server time per job (wall_time_s), measured 2026-10-13 with router rc5e1a55, Zap! 2026.10.13.33. Layer count and density drive the time more than pad count; queue time comes on top; the limit is 3,600 s.

Connect with OAuth

Sign in with Google, GitHub or Microsoft instead of an API key. API keys keep working unchanged. Signing in creates your Zap! account for your verified email address (50 jobs a day, 2 at a time, 30 requests a minute; for more, write to hello@mutual.solutions). Two ways to use the account: create an API key on your account page and use it like any key (zap.py, the MCP tool, the REST API), or connect an MCP client with OAuth sign-in as below, with no key.

Every token has your account's limits (jobs per UTC day, jobs at once, requests per minute), the same as an API key. A token works only where it is for: an MCP token is refused on /v1, and the reverse. Your account page, /account, lists connected apps (revoke any) and your developer credentials.

MCP (remote server https://zap.mutual.solutions/mcp; tools check_board, submit_job, get_job, list_jobs, get_report, get_result, delete_job). Boards travel as file text (board, project, rules; 20 MiB in total); the routed board comes back as an embedded resource (up to 8 MiB; larger: zap.py download after zap.py login).

# Claude Code: add, then type /mcp in Claude Code, choose zap and sign in (a browser opens)
claude mcp add --transport http zap https://zap.mutual.solutions/mcp

// Cursor: ~/.cursor/mcp.json; Cursor then offers to sign in to the server
{"mcpServers": {"zap": {"url": "https://zap.mutual.solutions/mcp"}}}

# Codex: ~/.codex/config.toml gets the two lines below, then sign in
#   [mcp_servers.zap]
#   url = "https://zap.mutual.solutions/mcp"
codex mcp login zap

Command line.

python3 zap.py login              # prints https://zap.mutual.solutions/device and a code: open the address, type the code, approve
python3 zap.py run myboard.kicad_pcb
python3 zap.py logout             # ends the sign-in on the server

Without an API key, zap.py uses the saved sign-in (~/.config/zap/oauth.json, readable only by you). After the approval it prints the account that approved; if that is not yours, run zap.py logout.

Server to server. Create a client id and secret on /account/credentials (the secret is shown once), then:

# the id and secret go to curl through stdin (bash's built-in printf): never on a command line
printf 'user = "%s:%s"\n' "$ZAP_CLIENT_ID" "$ZAP_CLIENT_SECRET" | \
  curl -s -K - -d grant_type=client_credentials https://zap.mutual.solutions/oauth/token
# {"access_token": "zat_...", "token_type": "Bearer", "expires_in": 3600, "scope": "zap"}

Send it as Authorization: Bearer <access_token> on /v1/..., like an API key; after a 401, get a new token.

OAuth endpoints answer in OAuth's error format ({"error": "invalid_grant", "error_description": "..."}), not the table below. A 401 on /v1 or /mcp carries WWW-Authenticate: Bearer resource_metadata="...". Sign-in data: your email address, the provider's account id, and hashes of your tokens; kept on the Zap! server and in its daily backup copies, which are deleted after 14 days (privacy).

5. Errors

Every error is JSON with a stable code and one sentence saying what to fix: {"error": "<code>", "message": "..."}. A failed job reports {"error": {"code": "...", "message": "..."}} in its status. Codes do not change; messages may get clearer.

Pre-flight findings (POST /v1/check) that are not request errors:

A job either returns a complete routed board or fails. There are no partial results.

During maintenance (usually under a minute) the network edge in front of Zap! may answer 502 with an HTML page instead of JSON. Wait a minute and try again; zap.py retries status checks and downloads by itself.

A 403 with the text error code: 1010 comes from Cloudflare, the network edge in front of Zap!, not from Zap!: send any User-Agent header, e.g. my-agent/1.0 (Python's built-in urllib sends a default name that the edge blocks).

6. Limits

Submitting many boards. Each key runs 2 jobs at a time and allows 30 requests a minute (the defaults; a key issued with other numbers shows them on its claim page). Submit a new job only after one of yours finishes (poll GET /v1/jobs/{id}, at most once every 5 seconds). On a 429 rate_limited, wait the seconds in Retry-After before the same request; do not retry sooner. too_many_active_jobs (also 429, without Retry-After) means your key's jobs at a time are all still queued or running: wait until one finishes. daily_quota_exceeded means stop until 00:00 UTC and tell your user.

7. Your data

The full Privacy page (한국어) and the Terms apply; in short:

• Your files are used only to route that job.
• Uploaded files are deleted as soon as the job finishes. The routed board is deleted 7 days later, or immediately with DELETE /v1/jobs/{id}.
• We keep a job record (id, times, status and the summary counts) without any board data, for 2 years.
• We do not use your boards to train or develop our software unless you agree in writing. consent_training=true records your preference; it is not by itself that written agreement.
• Request logs hold the time, IP address, key id, request path, status and size. They never hold board contents, file names, keys or feedback text.
• Your API key is stored only as a one-way hash. If you lose it, we issue a new one.
• Feedback. If you, or your AI agent with your OK, send feedback, only the text and any board pictures you attach are used to improve Zap!. They are linked to the job's id and the summary numbers we already keep; we never keep or use the board file. The Zap! team reads feedback, with help from AI tools. We don't publish or quote it without asking you, don't sell it, and don't use it to train AI models. We reply only if you allowed contact. We keep it for at most 2 years or until you ask us to delete it at hello@mutual.solutions; backup copies expire within 14 days. Please leave out personal or confidential details.
• The job records, key hashes, feedback and sign-in accounts (no board data) are backed up daily to private, encrypted storage in the same cloud region as the service; each backup copy is deleted after 14 days.

8. What does not do (yet)

• Placement: parts stay where you put them.
• Schematic checks.
• Length tuning beyond differential-pair skew, or guaranteed impedance.
• Manufacturing sign-off. Review every board and run your own DRC before fabrication.

9. Feedback

Tell us what you kept, what you changed and what you threw away. A short note is always welcome. Two ways:

• Through your AI agent or the command line. When you tell an agent that uses Zap! what you think of Zap! or a result, it asks whether to send that to us, shows you the exact text and the job id, and sends it only if you say yes. Command line: python3 zap.py feedback "the routing near U3 looks messy" --job JOB_ID shows the text and asks first. API: POST /v1/feedback with your key and JSON {"message": "...", "user_approved": true, "job_id": "...", "kind": "problem", "contact_ok": true}; kind is praise, problem, idea or other, and contact_ok: true lets us reply to your account's email address. The answer is 201 {"id", "received_at"}. Up to 4,000 characters, 20 per key per UTC day. Board files are never sent this way.
• A picture of the spot. If your feedback is about one place on the board, the agent can show you a picture of just that area (at most 40 mm square, with the report's missing connections and design-rule errors marked) and attach it if you agree: POST /v1/jobs/{id}/snapshot with {"x_mm": X, "y_mm": Y, "size_mm": 20}, then "snapshot_ids" in the feedback (at most 3). Command line: python3 zap.py snapshot JOB_ID --at 93.5,69.5 saves the picture; zap.py feedback "..." --job JOB_ID --snapshot ID attaches it. A picture you do not attach is deleted after 24 hours, or at once if you say you do not want it (DELETE /v1/snapshots/{id}.png). Never the whole board.
• By email to hello@mutual.solutions. If you also send an edited .kicad_pcb, say in the same message whether we may use it to improve Zap!: without that written OK we use it only to answer you, and then delete it.

For AI agents. Whenever the user expresses an opinion about Zap! or a routing result (something they liked, a problem, a wish), ask once whether they would like to send it to the Zap! team. When you ask, say in one short sentence what happens, without overstating or understating it, for example: "Send this to the Zap! team? Only this text (and the picture, if any) is used to improve Zap!, never your board file, and you can ask them to delete it." Show the exact text you would send (their words, or a summary they approve) and the job id. Send it with send_feedback or POST /v1/feedback only if they say yes. If they say no, do not ask again in this session. When the feedback is about a spot on the board, offer to attach a picture of just that area (board_snapshot or POST /v1/jobs/{id}/snapshot), aimed with the report's issue positions; show the picture to the user before sending and attach it only if they say yes; if they do not want it, delete it (delete_snapshot). Never the whole board. Never include board files or private details they did not approve.