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.
ProtoPulse’s backend is an Express 5 server that exposes a REST API with 50+ endpoints across 21 domain routers and 13 circuit routers. Every endpoint accepts and returns JSON, enforces Zod schema validation on request bodies, and uses session-based authentication via an X-Session-Id header. This page covers the global conventions that apply to all endpoints — base URL, authentication flow, request and response formats, error codes, and rate limiting — followed by a complete endpoint index grouped by domain.
Base URL
http://localhost:5000/api
localhost:5000 with your deployed domain. All paths below are relative to this base. The server also sets an X-API-Version: 1 header on every response.
Authentication
ProtoPulse uses session-based authentication. You obtain a session ID by registering or logging in, then pass it as a header on every subsequent request.
Getting a session:
Register a new account
Send POST /api/auth/register with { username, password }. The response contains a sessionId UUID.
Or log in to an existing account
Send POST /api/auth/login with { username, password }. The response also returns a sessionId.
Include the session on every request
Add the header X-Session-Id: <sessionId> to all subsequent API calls. The middleware validates the UUID against the sessions table, checks expiresAt, and populates req.userId for the route handler.
/api/auth/register and /api/auth/loginGET /api/healthPOST /api/seed (development only — 404 in production)
Admin endpoints use a separate X-Admin-Key header matching the ADMIN_API_KEY environment variable instead of a session.
Example — register and retrieve your session:
curl -s -X POST http://localhost:5000/api/auth/register \
-H "Content-Type: application/json" \
-d '{"username": "alice", "password": "securepassword"}' \
| jq .sessionId
"a3f8c2d1-7e14-4b5a-9f30-1d2e8b6c0a4f"
SESSION="a3f8c2d1-7e14-4b5a-9f30-1d2e8b6c0a4f"
curl http://localhost:5000/api/projects \
-H "X-Session-Id: $SESSION"
POST, PATCH, PUT) expect a JSON body:
Content-Type: application/json
413 Payload Too Large.
Request bodies are validated with Zod. Unknown fields are stripped. A 400 response is returned for any validation failure with a human-readable message describing the offending field.
Successful responses return JSON. List endpoints use a paginated envelope:
{
"data": [...],
"total": 42
}
| Parameter | Type | Default | Range | Description |
|---|
limit | integer | 50 | 1–100 | Maximum number of items to return |
offset | integer | 0 | 0+ | Number of items to skip |
sort | string | desc | asc | desc | Sort order by creation time |
201 Created with the full created object. Update endpoints return 200 OK with the updated object. Delete endpoints return 204 No Content.
Resources that support optimistic concurrency expose an ETag response header containing the current version number. Supply an If-Match: "<version>" header on PATCH requests to opt in to conflict detection — the server returns 409 Conflict if the version has changed since you last fetched.
All error responses share a consistent shape:
{
"message": "Human-readable description of what went wrong"
}
| Status | Meaning |
|---|
200 | Success |
201 | Resource created |
204 | Success, no content (deletes) |
400 | Validation error (Zod) or malformed request |
401 | Missing or invalid X-Session-Id |
403 | CSRF origin mismatch, or admin key required |
404 | Resource not found |
408 | Request timed out (30-second server timeout) |
409 | Conflict — optimistic concurrency version mismatch, or username already taken |
413 | Payload too large |
422 | Unprocessable entity — DRC gate failed before export |
429 | Rate limited |
500 | Internal server error (message is sanitized in production) |
Rate limiting
Rate limits are applied with express-rate-limit:
| Scope | Limit | Window |
|---|
| Global (all routes) | 300 requests | 15 minutes |
Auth endpoints (/api/auth/*) | 10 requests | 15 minutes |
SSE streaming (POST /api/chat/ai/stream) | 20 requests | 1 minute (sliding) |
| Concurrent SSE streams | 1 per session | — |
429 Too Many Requests and standard RateLimit-* headers.
Complete endpoint index
Auth
| Method | Path | Auth | Description |
|---|
POST | /api/auth/register | No | Register a new user. Returns { sessionId, user } (201). |
POST | /api/auth/login | No | Authenticate and get a session. Returns { sessionId, user }. |
POST | /api/auth/logout | Optional | Invalidate the current session. Returns 204. |
GET | /api/auth/me | Yes | Return the authenticated user { id, username }. |
Projects
| Method | Path | Auth | Description |
|---|
GET | /api/projects | Yes | List all non-deleted projects. Paginated. |
POST | /api/projects | Yes | Create a project. Body: { name, description? }. Returns 201. |
GET | /api/projects/:id | Yes | Get a single project. |
PATCH | /api/projects/:id | Yes | Update project name or description. |
DELETE | /api/projects/:id | Yes | Soft-delete a project. Returns 204. |
Architecture
| Method | Path | Auth | Description |
|---|
GET | /api/projects/:id/nodes | Yes | List architecture nodes. Paginated. |
POST | /api/projects/:id/nodes | Yes | Create a node. Body: { nodeId, nodeType, label, positionX, positionY, data? }. |
PATCH | /api/projects/:id/nodes/:nodeId | Yes | Update a node. Partial update. |
PUT | /api/projects/:id/nodes | Yes | Replace all nodes atomically (512 KB limit). |
GET | /api/projects/:id/edges | Yes | List architecture edges. Paginated. |
POST | /api/projects/:id/edges | Yes | Create an edge. |
PATCH | /api/projects/:id/edges/:edgeId | Yes | Update an edge. |
PUT | /api/projects/:id/edges | Yes | Replace all edges atomically (512 KB limit). |
Circuit designs, instances, nets, and wires
See the Circuit API page for full details.
| Method | Path | Auth | Description |
|---|
GET/POST/PATCH/DELETE | /api/projects/:projectId/circuits | Yes | Circuit design CRUD. |
GET/POST/PATCH/DELETE | /api/circuits/:circuitId/instances | Yes | Component instance CRUD. |
GET/POST/PATCH/DELETE | /api/circuits/:circuitId/nets | Yes | Net CRUD. |
GET/POST/PATCH/DELETE | /api/circuits/:circuitId/wires | Yes | Wire CRUD. |
GET | /api/circuits/:circuitId/netlist | Yes | Generate an inline netlist. |
POST | /api/projects/:projectId/circuits/:id/autoroute | Yes | Auto-route PCB traces. |
BOM
See the BOM API page for full details.
| Method | Path | Auth | Description |
|---|
GET/POST/PATCH/DELETE | /api/projects/:id/bom | Yes | BOM item CRUD. |
POST/GET/DELETE | /api/projects/:id/bom-snapshots | Yes | BOM snapshot management. |
POST | /api/projects/:id/bom-diff | Yes | Diff a snapshot against the current BOM. |
GET/POST/PATCH/DELETE | /api/projects/:id/lifecycle | Yes | Component lifecycle tracking. |
Validation
| Method | Path | Auth | Description |
|---|
GET | /api/projects/:id/validation | Yes | List validation issues. Paginated. |
POST | /api/projects/:id/validation | Yes | Create an issue. Body: { severity, message, componentId?, suggestion? }. |
PUT | /api/projects/:id/validation | Yes | Replace all issues atomically. |
DELETE | /api/projects/:id/validation/:issueId | Yes | Delete a single issue. Returns 204. |
Chat and AI
POST /api/chat/ai/stream uses Server-Sent Events (SSE), not standard JSON responses. The connection remains open and the server pushes data: events until the AI response is complete. You must handle the SSE protocol on the client — do not treat this endpoint like a normal fetch call.
| Method | Path | Auth | Description |
|---|
POST | /api/chat/ai | Yes | Send a message to the AI (non-streaming JSON response). |
POST | /api/chat/ai/stream | Yes | Send a message to the AI (SSE streaming). |
GET | /api/projects/:id/chat | Yes | List saved chat messages. |
POST | /api/projects/:id/chat | Yes | Save a chat message. |
DELETE | /api/projects/:id/chat | Yes | Delete all messages for a project. |
GET | /api/projects/:id/ai-actions | Yes | List AI action history. |
Export
See the Export API page for full details.
| Method | Path | Auth | Description |
|---|
POST | /api/projects/:projectId/export/bom | Yes | BOM CSV export. |
POST | /api/projects/:projectId/export/netlist | Yes | Netlist export (SPICE, KiCad, CSV). |
POST | /api/projects/:projectId/export/gerber | Yes | Gerber + drill files (runs DRC gate). |
POST | /api/projects/:projectId/export/kicad | Yes | KiCad project (.kicad_sch, .kicad_pcb). |
POST | /api/projects/:projectId/export/eagle | Yes | Eagle project (.sch, .brd). |
POST | /api/projects/:projectId/export/pdf | Yes | PDF schematic export. |
POST | /api/projects/:projectId/export/report-pdf | Yes | Full design report PDF. |
POST | /api/projects/:projectId/export/fmea | Yes | FMEA analysis CSV. |
POST | /api/projects/:projectId/export/fzz | Yes | Fritzing .fzz project. |
POST | /api/projects/:projectId/export/firmware | Yes | Firmware scaffold ZIP. |
POST | /api/projects/:projectId/export/pick-place | Yes | Pick-and-place centroid CSV. |
Simulations
| Method | Path | Auth | Description |
|---|
POST | /api/projects/:projectId/circuits/:circuitId/simulate | Yes | Run a simulation (OP, TRAN, AC, DC). |
GET | /api/projects/:projectId/circuits/:circuitId/simulations | Yes | List simulation result summaries. |
GET | /api/projects/:projectId/circuits/:circuitId/simulations/:simId | Yes | Get a full simulation result. |
DELETE | /api/projects/:projectId/circuits/:circuitId/simulations/:simId | Yes | Delete a simulation result. |
POST | /api/projects/:projectId/circuits/:circuitId/analyze/power | Yes | DC operating point + power estimate per component. |
POST | /api/projects/:projectId/circuits/:circuitId/analyze/signal-integrity | Yes | Signal integrity analysis. |
Miscellaneous
| Method | Path | Auth | Description |
|---|
GET | /api/health | No | Health check. |
GET | /api/projects/:id/export | Yes | Export full project as JSON. |
POST | /api/projects/import | Yes | Import a project from JSON (10 MB limit). |
GET | /api/admin/metrics | Admin key | Server request metrics. |
DELETE | /api/admin/purge | Admin key | Hard-purge soft-deleted records older than 30 days. |
Use GET /api/health in your deployment health checks. It returns 200 OK with no authentication required and has no rate limit.