HTTP API
The app's HTTP API covers everything the app does: projects, builds, constraints, parts, proposals, versions and live events.
Basics
- Everything under
/apiis JSON. - An error is
{"error": "<message>"}with a status code that means what it says. - Slugs are lowercase
[a-z0-9-]. Versions arevNNN. - Long operations are jobs. A chat turn, a build or an import answers
202with a job. Poll it, or listen on the event stream. - Add
"wait": trueto a body to get the finished answer instead of a job. - A request body may be at most 8 MB, or the answer is
413. - A project zip sent to
POST /api/projects/importmay be 256 MB. That needs the login cookie, aBearertoken, or a request from the server's own machine.
Authentication. Requests from the server's own machine need nothing. Any other client needs the access token, sent in one of three ways:
- the cookie that
/loginsets Authorization: Bearer <token>?token=in a URL, once
Under serve --proxy, a request from the server's own machine needs the token
too. /api/health, /static/, /login, /logout and the manifest are always
open. See Access control.
Pages that are not under /api, such as /p/<slug> and /about, are listed
in The app.
The app
| Route | Answer |
|---|---|
GET /api/health | {ok, version, uptime, jobs}. Cheap: it never touches git or the disk. |
GET /api/app | The version, build and project format. chat says whether a model is available. router says what this machine can run: lightcycle, astar, kicad and the catalogue. Also project counts, data_dir, jobs and whether auth is on. |
GET /api/changelog | The parsed CHANGELOG.md: releases:[{version, date, sections}] |
GET /api/benchmarks | What the shipped models scored, read off disk. See Benchmarks. |
GET /api/platforms | {platforms:[…]}: the microcontrollers a board can be built around, with live price and stock. See Projects. |
GET /api/platforms/<pid>/mesh | One platform's 3D model. It is a separate call because meshes are large. |
/api/benchmarks returns six sections:
| Section | What it holds |
|---|---|
routability | The model file's training-day numbers |
pipeline | {runs:[…]}: any eval*/summary.json runs |
rubric | The placer against the people who made the boards, on what a reviewer grades |
router_ab | Two routers on the same boards, under one judge |
mendicant | Physarum and the fold against the routers |
gnn | The graph judge against the CNN, within a board |
Each section but pipeline carries available. It is false when the
section's file is missing, which is normal on a deployed server.
Projects
| Route | Answer |
|---|---|
GET /api/projects | {projects:[summary…], trash}, most recently touched first. Add ?archived=1 to include archived projects. |
POST /api/projects | Create a project. See below. |
GET /api/projects/<slug> | The summary, plus versions[] and the chat[] thread |
PATCH /api/projects/<slug> | {name?, description?, tags?, archived?, example?}. Answers with the detail. |
DELETE /api/projects/<slug> | Moves it to the trash. 409 while a build runs. |
POST /api/projects/<slug>/fork | {name?, version?}. 201 with the new project. |
GET /api/projects/<slug>/export.zip | The whole project as one zip. ?chat=0 leaves the conversation out. 409 when a version in the table has no design.json on disk. |
POST /api/projects/import | A bundle back in, as multipart file (with optional name) or the raw zip. 201 {project}. |
POST /api/projects/<slug>/chat | Send a message. See below. |
POST /api/projects/<slug>/import | {design, note?, wait?} or {kicad, filename?, route?, wait?}. Answers like chat. |
GET /api/projects/<slug>/jobs | {active, recent} |
A summary carries name, slug, description, tags, archived, example, format, unreadable, versions, current, summary, prompt, parts, erc_errors, gaps, passed, poll, cost, label, app_version, thumbnail, created, touched, trail.
passedis the current version's verdict:true,false, ornullwhen it was not judged.pollis that verdict as the app draws it. See board.json.trailis one row per version, oldest first:{id, passed, gaps, erc_errors, cost, when, created, label}.unreadablesays whyproject.jsoncould not be read, or is empty.
Creating a project. The body takes name, description, and one of these:
| Also send | You get |
|---|---|
| Nothing | A blank project, 201 |
prompt with inline: true | A chat job, 202 {project, job} |
design | An import job, 202 |
kicad with filename | A finished board read as it is, 202. Add route: true to route it too. |
note labels an import, and wait: true answers when the build is done.
Without a name, the project is named from the prompt, then renamed after its
first board.
The detail adds two lists:
versions[]:{id, created, when, summary, prompt, parts, erc_errors, gaps, cost, passed, parent, app_version, label, notes, sim, poll, npth}.simsays whether asim.jsonexists.npthcounts the unplated holes the version's file drills.chat[]: the thread, oldest first. Each turn is{t, you, bot, version, steps}, and may carrykind,firstanderror. See The chat.
Chat. The body is {message, base?, backend?, model?, effort?, wait?}.
base is the version to edit, and it becomes current first.
- The answer is
202 {job, project}, or withwait,200 {reply, changes, board, version, project}. - A question builds nothing:
versionandboardarenull. - A build that failed its checks may make two versions.
versionis the one that stands.
| Status | Why |
|---|---|
400 | Empty message |
413 | Over 20,000 characters |
409 | A build is already running |
503 | No model credentials |
502 | The model call failed |
500 | The pipeline failed |
Import. A design must be a design, or the answer is 422. Its
constraints block is checked by field; a malformed one is 422. A good block
is kept when the project has none, and set aside, with a line in the reply,
when it has. A kicad board keeps its own placement. Nothing is designed,
resolved, priced or routed unless you send route: true. A board this pipeline
cannot build is 422 with the reason.
Bundle import. It writes nothing unless the whole zip is good. 400 names
the file or field it stopped at, 409 means a newer app's format, and 413
means over 256 MB.
Constraints
Constraints are what a person decided about their own board: pins, sides, hand-drawn copper, schematic positions and build rules. Saving them builds nothing. Only a rebuild makes a version. See design.json for the block.
| Route | Answer |
|---|---|
GET /api/projects/<slug>/constraints?base=<vid> | {base, constraints, unbuilt, touched, built}. base defaults to the current version. built holds the rack's knobs that version was built with. |
PUT /api/projects/<slug>/constraints | {base?, constraints}. Checks and stores the block, and answers as GET does. Runs no pipeline. |
DELETE /api/projects/<slug>/constraints | Drops the unbuilt edits and goes back to what was last built |
GET /api/projects/<slug>/sheet?base=<vid> | {base, sheet}: the schematic laid out under the constraints for that version. Milliseconds; builds nothing. |
POST /api/projects/<slug>/rebuild | {base?, seed?, wait?}. Builds the same design again, under the constraints as they are now. |
POST /api/projects/<slug>/route | {base?, seed?, wait?}. Routes the version's own placement again, under the current constraints. |
POST /api/projects/<slug>/versions/<vid>/simulate | Runs the simulation on that version. No new version. |
GET /api/projects/<slug>/variations | {variations:[{id, name, macros, when}]} |
POST /api/projects/<slug>/variations | {name, macros?, base?}. Saves a set of knobs. 201 {variation, variations}. |
PATCH /api/projects/<slug>/variations/<id> | {name}. Renames it. DELETE on the same route forgets it. |
POST /api/projects/<slug>/variations/<id>/recall | {base?}. Writes the set's knobs into the draft. Builds nothing. |
Saving. unbuilt: true means edits are saved that no build has seen yet.
The workbench uses it to mark the copper on screen as stale.
400lists what is wrong, such aspinned[J1] rot must be one of 0, 90, 180, 270, and stores nothing.404means an unknown version.409means the project has no version to pin to yet.- A saved change publishes
{constraints: <base>}on the event stream, so other devices see it.
Rebuild and route. Both answer like chat: 202 {job, project}, or the
finished turn with wait.
seedoverridesrules.seedfor one build. It must be a whole number from 0 to 10000, or the answer is400. Route checks it too, though a route moves no part.- Route again pins every part where it is, so the placer moves nothing and the router runs once.
409means nothing is built yet, a build is running, or (for route) the version has no placement.404means an unknown version.
Simulate. It resolves the version's parts and runs ngspice on its netlist,
in seconds. The answer is 200 {sim, gaps, notes, version}, and sim.json
lands beside the version's board.json. 409 gives the reason when there is
nothing to simulate: no engine, no ground, or no declared rail.
Variations. A variation's macros carry only the rack's knobs:
rules.router, rules.seed, rules.pour, rules.precedent, rules.mark,
rules.min_track_mm, board.sides, board.fixed and board.layers. Any other
key is 400.
Without macros, the knobs are read from the constraints for base.
A recall sets every knob the variation carries and clears every knob it does not. Pins and hand-drawn copper are untouched.
Jobs
| Route | Answer |
|---|---|
GET /api/jobs/<id> | The job, as below |
| Field | What it holds |
|---|---|
id, kind, project, message | The job. See the kinds below. |
created, started, finished, elapsed | Times, in epoch seconds |
status | queued, running, done or failed |
phase | The stage the job is on now |
steps | Every stage so far, as [{phase, at, s}]: when it began and how long it ran |
result | What the job made. Its shape depends on the kind. |
error | Why it failed |
| Kind | Started by | result |
|---|---|---|
chat, import, rebuild, route | A message, an import, a rebuild or a route again | {version, prompt, reply, changes, decisions} |
propose, part, remove, block | A proposal, adding a part, removing parts or adding a block | {reply, proposal, review, board, refused, said}, plus ref for a part and removed for a removal |
In a build's result, version is null for a turn that built nothing.
prompt is the line the record keeps for the turn: what was asked, or the
app's note for a rebuild.
Parts and blocks
Three routes change a board without asking a model: add a part, remove parts, add a block. Each ends in a proposal, built and priced before anyone accepts it.
| Route | Answer |
|---|---|
GET /api/parts?q=&package=&limit=&stock= | JLCPCB stock: {query, parts:[…]}. limit is 1 to 40, 20 by default. stock=0 includes parts that are out of stock. |
GET /api/parts/<lcsc>?kind=&value= | One part, resolved, with the pin names a net may use |
POST /api/projects/<slug>/parts | {lcsc, kind, value?, purpose?, connect?, wait?}. Puts the part on the board. |
DELETE /api/projects/<slug>/parts | {refs:[…], wait?}. Takes those parts off the board. |
GET /api/blocks?q= | The block library: {blocks:[…], total} |
POST /api/projects/<slug>/blocks | {block, connect?, wait?}. Drops a block in. |
Search. Each part is \{lcsc, mfr, description, package, category, stock, price, basic, pads, kind, footprint\}.
kindis what the catalogue's category says the part is, or"".footprintis the package this pipeline has geometry for.""means the pads would come from the vendor's drawing.503means the catalogue could not answer. It says nothing about the part.
One part. The answer is \{part, kind, package, symbol, component, pins, notes, gaps\}. Each pin is \{pin, pad, name, why\}:
pinis the name to use in a net. It is empty when nothing resolves to that pad, andwhysays so.- Every name is checked through the same resolver the build uses.
componentis the design line the part would be written as.404means JLCPCB does not list the code.503means the catalogue could not answer.
Adding a part. kind is required and never guessed, because it decides
which electrical rules apply. connect is {pin: net} against nets the board
already has. A pin left out stays unconnected, and with no pins wired, ERC
reports the part as an orphan.
- The answer is
202 {job, project}, or withwait,{reply, proposal, review, board, said, refused, ref}.boardis the proposal's built board. 400means no part or kind,422a net that does not exist,409no board yet.
Removing parts. No model is asked. Every pin the parts had goes with them,
and a net left with fewer than two pins goes too. review counts both and
reply names them.
- The answer is the same as adding a part, plus
removed. 400means no refdes.413means more than 200.422means a refdes this board does not have, or every part at once.409means no board yet.
Blocks. Each block is \{name, boards, source, instances, agreed, named, ports, parts, checked\}. source is mined (found on several boards) or
authored (written against a datasheet). connect is {port: net} and merges
nets. It draws no wire.
Proposals
A change to an existing board is built as a proposal first. The model returns a patch of what changes, so a part it never mentions cannot be dropped.
| Route | Answer |
|---|---|
POST /api/projects/<slug>/propose | {message, base?, selection?, backend?, model?, effort?, wait?}. Builds the change and writes no version. base becomes current first. |
GET /api/projects/<slug>/proposal | {proposal}: id, created, base, message, selection, reply, report, review, constraints, steps, files. null when nothing is proposed. |
GET /api/projects/<slug>/proposal/board | The proposal's board, for a page that did not build it. 404 when nothing is proposed. |
POST /api/projects/<slug>/proposal/accept | The proposal becomes the next version: {version, board, project}. 409 when nothing is proposed. |
POST /api/projects/<slug>/proposal/reject | Drops the proposal. The board is as it was. |
selection is {refs:[…], nets:[…]}. Selected parts and nets may be changed
or removed, and anything may be added. Everything else is refused by name.
With wait, propose answers {reply, proposal, review, board, said, refused}.
Without it, 202 {job, project}. 409 means there is no board yet.
review is {parts, nets, erc, cost}: what was added, removed and changed, the
ERC before and after, and the cost change. said is the same in sentences.
A proposal is accepted whole, because half a route cannot be accepted.
Versions
Every route here starts /api/projects/<slug>/versions/<vid>.
| Route | Answer |
|---|---|
GET … | The version's metadata, its files, and its diff against its parent |
PATCH … | {label?, notes?}. Answers with the project detail. |
POST …/restore | Makes it current: {board, project, version} |
GET …/board | board.json |
GET …/design | design.json |
GET …/diff?against=<vid> | {from, to, components, nets, board, summary, empty} |
GET …/files | {files:[{name, size, kind}]}. See Files in a version. |
GET …/files/<name>?dl=1 | One file. SVG, JSON, HTML and CSV show inline unless dl=1. Cached a day, since versions never change. |
GET …/markers | {markers, source, judge, note?}: where DRC found each error, as in board.json. source is stored, or drc when KiCad's DRC ran again for a version that kept none. That takes seconds. |
GET …/gerbers.zip | Gerbers, drill, BOM and CPL |
GET …/inspector.html?dl=1 | The standalone viewer, with the board and 3D models inside |
Trash
| Route | Answer |
|---|---|
GET /api/trash | {trash:[{slug, name, versions}]} |
POST /api/trash/<slug>/restore | Back to the projects list, renamed if the name is taken |
DELETE /api/trash | Empties the trash for good |
Live events
GET /api/events?project=<slug> is a server-sent event stream. Each message is
a JSON object:
| Message | When |
|---|---|
{from, view?, orbit?, sel?, net?, qty?} | Another device changed what it shows |
{version} | The current version changed |
{constraints} | Constraints were saved against that version |
{phase, at} | A build reached a stage. at is when it began, in epoch seconds. |
{job, status, kind, phase?, at?, version?, error?} | A job was queued, ran, reported a stage or finished |
{anneal: {…}} | A frame of the placer at work, while a build places |
event: bye | The stream is ending |
POST /api/state with {project, from, …} sends your view to the other devices
on that project (204).
Limits. A stream holds a server thread, and cannot tell when its client has gone. Two limits keep streams from starving ordinary requests:
- At most a third of the server's workers stream at once. Past that, the answer is
503withRetry-After: 10, and the page falls back to polling its job. - A stream ends after five minutes. The browser reconnects on its own.
A listener too slow to keep up is dropped and told so.
Example
Send a chat message, wait for the build, then download the Gerbers:
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