soldermaskdocs

HTTP API

The app's HTTP API covers everything the app does: projects, builds, constraints, parts, proposals, versions and live events.

Basics

  • Everything under /api is JSON.
  • An error is {"error": "<message>"} with a status code that means what it says.
  • Slugs are lowercase [a-z0-9-]. Versions are vNNN.
  • Long operations are jobs. A chat turn, a build or an import answers 202 with a job. Poll it, or listen on the event stream.
  • Add "wait": true to 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/import may be 256 MB. That needs the login cookie, a Bearer token, 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 /login sets
  • 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

RouteAnswer
GET /api/health{ok, version, uptime, jobs}. Cheap: it never touches git or the disk.
GET /api/appThe 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/changelogThe parsed CHANGELOG.md: releases:[{version, date, sections}]
GET /api/benchmarksWhat 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>/meshOne platform's 3D model. It is a separate call because meshes are large.

/api/benchmarks returns six sections:

SectionWhat it holds
routabilityThe model file's training-day numbers
pipeline{runs:[…]}: any eval*/summary.json runs
rubricThe placer against the people who made the boards, on what a reviewer grades
router_abTwo routers on the same boards, under one judge
mendicantPhysarum and the fold against the routers
gnnThe 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

RouteAnswer
GET /api/projects{projects:[summary…], trash}, most recently touched first. Add ?archived=1 to include archived projects.
POST /api/projectsCreate 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.zipThe 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/importA bundle back in, as multipart file (with optional name) or the raw zip. 201 {project}.
POST /api/projects/<slug>/chatSend 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.

  • passed is the current version's verdict: true, false, or null when it was not judged.
  • poll is that verdict as the app draws it. See board.json.
  • trail is one row per version, oldest first: {id, passed, gaps, erc_errors, cost, when, created, label}.
  • unreadable says why project.json could not be read, or is empty.

Creating a project. The body takes name, description, and one of these:

Also sendYou get
NothingA blank project, 201
prompt with inline: trueA chat job, 202 {project, job}
designAn import job, 202
kicad with filenameA 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}. sim says whether a sim.json exists. npth counts the unplated holes the version's file drills.
  • chat[]: the thread, oldest first. Each turn is {t, you, bot, version, steps}, and may carry kind, first and error. 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 with wait, 200 {reply, changes, board, version, project}.
  • A question builds nothing: version and board are null.
  • A build that failed its checks may make two versions. version is the one that stands.
StatusWhy
400Empty message
413Over 20,000 characters
409A build is already running
503No model credentials
502The model call failed
500The 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.

RouteAnswer
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>/constraintsDrops 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>/simulateRuns 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.

  • 400 lists what is wrong, such as pinned[J1] rot must be one of 0, 90, 180, 270, and stores nothing.
  • 404 means an unknown version. 409 means 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.

  • seed overrides rules.seed for one build. It must be a whole number from 0 to 10000, or the answer is 400. 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.
  • 409 means nothing is built yet, a build is running, or (for route) the version has no placement. 404 means 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

RouteAnswer
GET /api/jobs/<id>The job, as below
FieldWhat it holds
id, kind, project, messageThe job. See the kinds below.
created, started, finished, elapsedTimes, in epoch seconds
statusqueued, running, done or failed
phaseThe stage the job is on now
stepsEvery stage so far, as [{phase, at, s}]: when it began and how long it ran
resultWhat the job made. Its shape depends on the kind.
errorWhy it failed
KindStarted byresult
chat, import, rebuild, routeA message, an import, a rebuild or a route again{version, prompt, reply, changes, decisions}
propose, part, remove, blockA 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.

RouteAnswer
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\}.

  • kind is what the catalogue's category says the part is, or "".
  • footprint is the package this pipeline has geometry for. "" means the pads would come from the vendor's drawing.
  • 503 means 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\}:

  • pin is the name to use in a net. It is empty when nothing resolves to that pad, and why says so.
  • Every name is checked through the same resolver the build uses.
  • component is the design line the part would be written as.
  • 404 means JLCPCB does not list the code. 503 means 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 with wait, {reply, proposal, review, board, said, refused, ref}. board is the proposal's built board.
  • 400 means no part or kind, 422 a net that does not exist, 409 no 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.
  • 400 means no refdes. 413 means more than 200.
  • 422 means a refdes this board does not have, or every part at once. 409 means 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.

RouteAnswer
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/boardThe proposal's board, for a page that did not build it. 404 when nothing is proposed.
POST /api/projects/<slug>/proposal/acceptThe proposal becomes the next version: {version, board, project}. 409 when nothing is proposed.
POST /api/projects/<slug>/proposal/rejectDrops 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>.

RouteAnswer
GET …The version's metadata, its files, and its diff against its parent
PATCH …{label?, notes?}. Answers with the project detail.
POST …/restoreMakes it current: {board, project, version}
GET …/boardboard.json
GET …/designdesign.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=1One 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.zipGerbers, drill, BOM and CPL
GET …/inspector.html?dl=1The standalone viewer, with the board and 3D models inside

Trash

RouteAnswer
GET /api/trash{trash:[{slug, name, versions}]}
POST /api/trash/<slug>/restoreBack to the projects list, renamed if the name is taken
DELETE /api/trashEmpties the trash for good

Live events

GET /api/events?project=<slug> is a server-sent event stream. Each message is a JSON object:

MessageWhen
{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: byeThe 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 503 with Retry-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

On this page