Documentation Index
Fetch the complete documentation index at: https://mintlify.com/wtyler2505/ProtoPulse/llms.txt
Use this file to discover all available pages before exploring further.
The circuit API covers everything needed to build and manipulate a schematic inside ProtoPulse. It is split across 13 routers registered in server/circuit-routes/: circuit designs, component instances, nets, wires, netlist generation, hierarchical sheets, auto-routing, expansion, import, export, and simulations. This page covers the five most commonly used resource groups — designs, instances, nets, wires, ERC, and auto-routing — with request schemas and curl examples for every operation.
All circuit endpoints require a valid X-Session-Id header. See REST API Overview for authentication details. Circuit designs
A circuit design is the top-level container for a schematic. Every project can have multiple circuit designs (for example, separate sheets for power supply and signal processing). Circuit designs belong to a project and can optionally have a parentDesignId to form a hierarchical sheet tree.
Endpoints
List designs
Get design
Create design
Update design
Delete design
GET /api/projects/:projectId/circuitsReturns all circuit designs for a project.curl http://localhost:5000/api/projects/1/circuits \
-H "X-Session-Id: $SESSION"
{
"data": [
{
"id": 1,
"projectId": 1,
"name": "Main Circuit",
"description": null,
"settings": {},
"version": 3,
"createdAt": "2026-01-10T09:00:00.000Z",
"updatedAt": "2026-01-12T14:30:00.000Z"
}
],
"total": 1
}
GET /api/projects/:projectId/circuits/:idReturns a single circuit design. The response includes an ETag header with the current version.curl http://localhost:5000/api/projects/1/circuits/1 \
-H "X-Session-Id: $SESSION"
POST /api/projects/:projectId/circuitsCreates a new circuit design. Returns 201 Created with the created object.Display name for the circuit design. Minimum 1 character.
Optional description. Can be null.
ID of a parent circuit design. Set this to create a hierarchical sub-sheet.
Circuit display settings. Known fields include gridSize, powerSymbols, noConnectMarkers, netLabels, and annotations. Additional unknown fields are passed through for forward compatibility.
curl -X POST http://localhost:5000/api/projects/1/circuits \
-H "X-Session-Id: $SESSION" \
-H "Content-Type: application/json" \
-d '{"name": "Power Supply", "description": "3.3V LDO section"}'
PATCH /api/projects/:projectId/circuits/:idPartially updates a circuit design. All body fields are optional. Supply an If-Match: "<version>" header to enable optimistic concurrency — the server returns 409 Conflict if the version has changed.New name. Minimum 1 character.
New description. Can be null to clear.
Partial settings update. Merged server-side.
curl -X PATCH http://localhost:5000/api/projects/1/circuits/1 \
-H "X-Session-Id: $SESSION" \
-H "Content-Type: application/json" \
-H 'If-Match: "3"' \
-d '{"name": "Power Supply v2"}'
DELETE /api/projects/:projectId/circuits/:idDeletes a circuit design and all its instances, nets, and wires. Returns 204 No Content.curl -X DELETE http://localhost:5000/api/projects/1/circuits/2 \
-H "X-Session-Id: $SESSION"
Component instances
A component instance is a placed occurrence of a component part inside a circuit design. It carries position and rotation coordinates for three views: schematic, breadboard, and PCB. Reference designators (R1, C2, U3) are auto-generated if you omit them or send a placeholder ending in ?.
Endpoints
List instances
Place instance
Update instance
Delete instance
GET /api/circuits/:circuitId/instancesReturns all instances in a circuit design. Paginated (limit, offset, sort).curl "http://localhost:5000/api/circuits/1/instances?limit=100" \
-H "X-Session-Id: $SESSION"
POST /api/circuits/:circuitId/instancesPlaces a new component instance in the circuit. If referenceDesignator is omitted or ends with ?, the server auto-increments the next available designator for that part family (for example, the first resistor becomes R1, the second R2).ID of the component_parts record to instantiate. Can be null for a “bare” instance with no associated part shape.
Reference designator such as R1 or U3. Optional — auto-generated if omitted. Send R? to auto-assign within the R-series.
X coordinate on the schematic canvas.
Y coordinate on the schematic canvas.
Rotation in degrees on the schematic canvas.
X coordinate on the breadboard view. Nullable.
Y coordinate on the breadboard view. Nullable.
X coordinate on the PCB layout view. Nullable.
Y coordinate on the PCB layout view. Nullable.
PCB side — front or back.
Key-value string pairs for component properties such as resistance value, tolerance, or package.
curl -X POST http://localhost:5000/api/circuits/1/instances \
-H "X-Session-Id: $SESSION" \
-H "Content-Type: application/json" \
-d '{
"partId": 5,
"schematicX": 120,
"schematicY": 80,
"properties": {"value": "10k", "tolerance": "1%"}
}'
201 Created and the full instance object including the auto-assigned referenceDesignator.PATCH /api/circuits/:circuitId/instances/:idUpdates position, rotation, or properties for an existing instance. All fields are optional.curl -X PATCH http://localhost:5000/api/circuits/1/instances/12 \
-H "X-Session-Id: $SESSION" \
-H "Content-Type: application/json" \
-d '{"schematicX": 200, "schematicY": 100}'
DELETE /api/circuits/:circuitId/instances/:idRemoves an instance from the circuit. Returns 204 No Content.curl -X DELETE http://localhost:5000/api/circuits/1/instances/12 \
-H "X-Session-Id: $SESSION"
Nets
A net is an electrical connection that links component pins. Nets carry a type (signal, power, ground, or bus), an optional voltage label, and structured data for segments (which pins are connected), wire labels, and visual style.
Endpoints
List nets
Create net
Update net
Delete net
GET /api/circuits/:circuitId/netsReturns all nets in a circuit. Paginated.curl http://localhost:5000/api/circuits/1/nets \
-H "X-Session-Id: $SESSION"
POST /api/circuits/:circuitId/netsCreates a new named net.Net name. Must be at least 1 character. Conventionally uses names like VCC, GND, SDA, or ~{RST} for active-low signals.
Net type: signal, power, ground, or bus.
Nominal voltage label, for example "3.3V" or "5V". Nullable.
Bus width for bus-type nets, for example 8 for an 8-bit data bus. Nullable.
Array of connection segments. Each segment links a component instance pin to this net. Accepts the canonical NetSegment shape ({ instanceId, pinId }), a line-segment shape ({ x1, y1, x2, y2 }), or a DSL placeholder { irId }. Defaults to [].
Array of net label objects with position and text. Defaults to [].
Visual style overrides such as stroke colour or dash pattern. Defaults to {}.
curl -X POST http://localhost:5000/api/circuits/1/nets \
-H "X-Session-Id: $SESSION" \
-H "Content-Type: application/json" \
-d '{"name": "VCC", "netType": "power", "voltage": "3.3V"}'
PATCH /api/circuits/:circuitId/nets/:idPartially updates a net. Accepts the same fields as the create schema, all optional.curl -X PATCH http://localhost:5000/api/circuits/1/nets/3 \
-H "X-Session-Id: $SESSION" \
-H "Content-Type: application/json" \
-d '{"voltage": "5V"}'
DELETE /api/circuits/:circuitId/nets/:idDeletes a net and all wires that belong to it (cascade). Returns 204 No Content.curl -X DELETE http://localhost:5000/api/circuits/1/nets/3 \
-H "X-Session-Id: $SESSION"
Wires
A wire is the visual representation of a segment of a net in a specific view. Wires belong to a net and store an ordered array of {x, y} points defining the wire path. The same net can have multiple wires in the schematic view and separate wires in the breadboard or PCB view.
Endpoints
List wires
Draw wire
Update wire
Delete wire
GET /api/circuits/:circuitId/wiresReturns all wires in a circuit across all views.curl http://localhost:5000/api/circuits/1/wires \
-H "X-Session-Id: $SESSION"
POST /api/circuits/:circuitId/wiresDraws a new wire segment for a net.ID of the net this wire belongs to.
The view this wire is drawn in: schematic, breadboard, or pcb.
Ordered array of { x: number, y: number } objects defining the wire path. The wire router uses 90-degree segments.
PCB layer. Only relevant when view is pcb. Examples: front, back, inner1.
Trace width in canvas units.
Override wire colour (hex string). Falls back to the net-class colour if omitted.
Wire type. Currently wire is the only supported value.
curl -X POST http://localhost:5000/api/circuits/1/wires \
-H "X-Session-Id: $SESSION" \
-H "Content-Type: application/json" \
-d '{
"netId": 3,
"view": "schematic",
"points": [
{"x": 120, "y": 80},
{"x": 200, "y": 80},
{"x": 200, "y": 140}
]
}'
PATCH /api/circuits/:circuitId/wires/:idUpdates a wire’s path or visual properties.curl -X PATCH http://localhost:5000/api/circuits/1/wires/7 \
-H "X-Session-Id: $SESSION" \
-H "Content-Type: application/json" \
-d '{"width": 2.0}'
DELETE /api/circuits/:circuitId/wires/:idRemoves a single wire segment. Returns 204 No Content. The net itself is not deleted.curl -X DELETE http://localhost:5000/api/circuits/1/wires/7 \
-H "X-Session-Id: $SESSION"
Electrical Rule Check
POST /api/projects/:projectId/circuits/:id/erc (via the circuit design router)
Runs the Electrical Rule Check engine against a circuit design and returns a list of ERC violations. The ERC engine checks for unconnected pins, conflicting net driver types, floating power rails, missing decoupling capacitors on power pins, and other electrical correctness issues. Results are also written to the validation_issues table for the project.
curl -X POST http://localhost:5000/api/projects/1/circuits/1/erc \
-H "X-Session-Id: $SESSION" \
-H "Content-Type: application/json" \
-d '{}'
{
"violations": [
{
"severity": "error",
"message": "Pin U1.VCC is unconnected",
"instanceId": 4,
"pinId": "VCC"
},
{
"severity": "warning",
"message": "Net VCC has no power source driver",
"netId": 3
}
],
"passedCount": 12,
"failedCount": 2
}
ERC must pass before Gerber export. The export endpoint runs a DRC/ERC gate and returns 422 Unprocessable Entity if violations are present. Fix all error-severity violations before exporting manufacturing files.
Auto-route
POST /api/projects/:projectId/circuits/:id/autoroute
Triggers the server-side PCB auto-router, which attempts to connect all component instances on the PCB layout view by generating wire segments for each net. The router uses a grid-based 90-degree routing algorithm.
Routing grid pitch in canvas units.
Minimum clearance between traces in canvas units.
curl -X POST http://localhost:5000/api/projects/1/circuits/1/autoroute \
-H "X-Session-Id: $SESSION" \
-H "Content-Type: application/json" \
-d '{"gridSize": 10, "clearance": 5}'
{
"routedNets": 8,
"unroutedNets": 1,
"message": "Auto-routing complete. 1 net could not be routed — manual routing required."
}
After auto-routing, run the ERC endpoint to verify that no pin connections were missed, and review the PCB layout view to confirm that trace clearance rules are met before exporting Gerbers.
Inline netlist
GET /api/circuits/:circuitId/netlist
Generates and returns a netlist for the circuit in JSON format, listing all nets with their connected instance/pin pairs. This is useful for programmatic connectivity analysis without triggering a full export.
curl http://localhost:5000/api/circuits/1/netlist \
-H "X-Session-Id: $SESSION"
{
"circuitId": 1,
"nets": [
{
"id": 3,
"name": "VCC",
"netType": "power",
"connections": [
{"instanceId": 1, "refDes": "U1", "pinId": "VCC"},
{"instanceId": 2, "refDes": "C1", "pinId": "+"}
]
}
]
}