HTTP API

Everything under /api is JSON. Errors are {"error": "<message>"} with an honest status code. Slugs are lowercase [a-z0-9-]; versions are vNNN.

Authentication. Requests from the machine itself need nothing. Any other client needs the access token — as the cookie set by /login, as Authorization: Bearer <token>, or once as ?token= in a URL. /api/health, /static/, /login and the manifest are always open. See Access control.

Long operations are jobs. A chat turn or an import answers 202 with a job; poll it or listen on the event stream. Add "wait": true to the body for a synchronous answer instead.

The appCopy Anchor Link

ProjectsCopy Anchor Link

ConstraintsCopy Anchor Link

What a person decided about their own board — pinned parts, edges, keepouts, schematic positions, hand-drawn copper, which side of the board a part is on (pinned[ref].side, back or the default front), how many sides the placer may use (board.sides, 1 to hold a board to one side; 2 is the default), and the fab rules they set themselves (rules.min_track_mm, a floor under every routed net; rules.router, freerouting or krt, which program lays the copper first). Saved without building anything: a rebuild is the only thing that makes a version.

See design.json for the block itself. A change publishes {constraints: <base>} on /api/events, because another device looking at this board has no other way to find out.

JobsCopy Anchor Link

Parts and blocksCopy Anchor Link

Three ways to change what is on a board without describing it to a model — two that add and one that takes away. All of them end in a proposal: the board that results is resolved, placed, routed and priced before anybody commits to it, which is as true of a deletion as of an addition.

ProposalsCopy Anchor Link

A change to a board that already exists does not become the board. The model returns what changes — a patch, not a new copy of the design, so a part it never mentions cannot be dropped — which is applied to a copy, built, and reported on before anyone commits to it.

review is {parts:{added,removed,changed}, nets:{added,removed,changed}, erc:{before,after,errors,warnings}, cost:{before,after,delta}}, and said is the same thing in sentences. Acceptance is the whole proposal at once — per-hunk review works on text because text is lines, and there is no way to accept half a route.

VersionsCopy Anchor Link

TrashCopy Anchor Link

Live eventsCopy Anchor Link

GET /api/events?project=<slug> is a server-sent event stream. Messages are JSON objects and can be:

• sync state from another device — {from, view?, orbit?, sel?, net?, qty?};
• a version switch — {version};
• build progress — {phase, at} and {job, status, kind, phase?, at?, version?, error?} as a job is queued, runs, reports a phase, and finishes; at is when the phase began, epoch seconds;
• event: bye when the stream ends.

A stream holds one server thread for as long as it runs, and it cannot tell that its client has gone — a closed laptop leaves a socket that is written into and never read. So two limits apply, and between them a browser that keeps reconnecting can never take the threads that answer ordinary requests. At most a third of the server's workers stream at once; past that the endpoint answers 503 with Retry-After: 10 instead of spending a thread, and the page keeps working on its job poll until a slot frees. A stream ends after five minutes and the browser's EventSource reconnects on its own, which is what returns a thread abandoned by a client that went away. A listener too slow to drain its queue is dropped and told so, ending its stream, rather than being left connected to a queue nobody publishes to.

POST /api/state with {project, from, …} publishes sync state to the other devices on that project (204).

ExampleCopy Anchor Link

T=$(cat .cache/access-token)
J=$(curl -sk -H "Authorization: Bearer $T" -H 'Content-Type: application/json' \
      -d '{"message":"add a power LED"}' https://192.168.1.10:8443/api/projects/ldo-breakout/chat \
    | jq -r .job.id)
until curl -sk -H "Authorization: Bearer $T" https://192.168.1.10:8443/api/jobs/$J | jq -e '.status=="done"' >/dev/null; do sleep 5; done
curl -sk -H "Authorization: Bearer $T" -o ldo.zip https://192.168.1.10:8443/api/projects/ldo-breakout/versions/v003/gerbers.zip