BOM API — Items, Snapshots, and Lifecycle

The BOM API covers three connected capabilities: managing the line items in your bill of materials, taking point-in-time snapshots for revision control, and tracking the production lifecycle status of individual components. All endpoints are scoped to a project via :id in the URL path and require a valid X-Session-Id header.

The bom_items table uses soft deletes — DELETE sets a deleted_at timestamp rather than removing the row. All read queries automatically filter soft-deleted items. The total_price field is computed server-side as quantity × unit_price and cannot be set directly.

BOM items

BOM items are the individual components listed in your bill of materials. Each item carries part number, manufacturer, quantity, pricing, supplier, stock status, and a lifecycle link.

Endpoints

List items
Get item
Add item
Update item
Delete item

GET /api/projects/:id/bomReturns all active (non-deleted) BOM items for a project. Paginated (limit, offset, sort).

curl "http://localhost:5000/api/projects/1/bom?limit=50" \
  -H "X-Session-Id: $SESSION"

{
  "data": [
    {
      "id": 1,
      "projectId": 1,
      "partNumber": "RC0402FR-0710KL",
      "manufacturer": "Yageo",
      "description": "10k Ohm 1% 0.0625W resistor, 0402",
      "quantity": 10,
      "unitPrice": "0.0120",
      "totalPrice": "0.1200",
      "supplier": "DigiKey",
      "stock": 500,
      "status": "In Stock",
      "leadTime": null,
      "updatedAt": "2026-01-12T14:00:00.000Z"
    }
  ],
  "total": 1
}

GET /api/projects/:id/bom/:bomIdReturns a single BOM item.

curl http://localhost:5000/api/projects/1/bom/1 \
  -H "X-Session-Id: $SESSION"

POST /api/projects/:id/bomAdds a new line item to the BOM. Returns 201 Created with the full item including the server-computed totalPrice.

partNumber

string

required

Manufacturer or distributor part number.

manufacturer

string

required

Manufacturer name, for example "Texas Instruments".

description

string

required

Human-readable description of the component.

quantity

number

default:"1"

required

Quantity needed. Must be a positive integer.

unitPrice

string

required

Price per unit as a decimal string, for example "0.0120". Up to 4 decimal places.

supplier

string

required

Distributor name, for example "DigiKey" or "Mouser".

stock

number

default:"0"

required

Current stock on hand.

status

string

default:"In Stock"

Stock status. One of In Stock, Low Stock, Out of Stock, or On Order.

leadTime

string

Lead time description, for example "2 weeks". Optional.

curl -X POST http://localhost:5000/api/projects/1/bom \
  -H "X-Session-Id: $SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "partNumber": "RC0402FR-0710KL",
    "manufacturer": "Yageo",
    "description": "10k Ohm 1% 0.0625W resistor, 0402",
    "quantity": 10,
    "unitPrice": "0.0120",
    "supplier": "DigiKey",
    "stock": 500,
    "status": "In Stock"
  }'

PATCH /api/projects/:id/bom/:bomIdPartially updates a BOM item. All fields are optional. If you update quantity or unitPrice, totalPrice is recomputed automatically.

quantity

number

New quantity.

unitPrice

string

New unit price as a decimal string.

status

string

Updated stock status.

stock

number

Updated stock on hand.

leadTime

string

Updated lead time description.

curl -X PATCH http://localhost:5000/api/projects/1/bom/1 \
  -H "X-Session-Id: $SESSION" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 20, "status": "Low Stock"}'

DELETE /api/projects/:id/bom/:bomIdSoft-deletes a BOM item. The item is no longer returned by the list endpoint but remains in the database for audit and snapshot purposes. Returns 204 No Content.

curl -X DELETE http://localhost:5000/api/projects/1/bom/1 \
  -H "X-Session-Id: $SESSION"

BOM CSV export

POST /api/projects/:projectId/export/bom Exports the BOM as a CSV file. The response is a file download with Content-Type: text/csv.

bomFormat

string

default:"generic"

Output format. One of generic, jlcpcb, mouser, or digikey. Each format uses column headers and ordering compatible with that distributor’s upload tool.

includeHeader

boolean

default:"true"

Whether to include a header row in the CSV.

groupByPartNumber

boolean

default:"false"

When true, collapses duplicate part numbers and sums their quantities.

curl -X POST http://localhost:5000/api/projects/1/export/bom \
  -H "X-Session-Id: $SESSION" \
  -H "Content-Type: application/json" \
  -d '{"bomFormat": "jlcpcb"}' \
  -o bom-jlcpcb.csv

BOM snapshots

A BOM snapshot captures the complete state of your BOM at a point in time. Snapshots are immutable — you cannot edit a snapshot after it is created, only delete it or compare it against another state. Use snapshots before major design changes to establish a baseline you can diff against later.

Response fields

number

required

Snapshot ID.

projectId

number

required

ID of the owning project.

label

string

required

Human-readable name for the snapshot, for example "Pre-review BOM v1.2".

snapshotData

array

required

The full array of BomItem objects captured at snapshot time. This is a static copy — changes to live BOM items after snapshot creation do not affect this field.

createdAt

string

required

ISO 8601 timestamp of when the snapshot was taken.

Endpoints

List snapshots
Take snapshot
Delete snapshot

GET /api/projects/:id/bom-snapshotsReturns all snapshots for a project, newest first.

curl http://localhost:5000/api/projects/1/bom-snapshots \
  -H "X-Session-Id: $SESSION"

{
  "data": [
    {
      "id": 2,
      "projectId": 1,
      "label": "Pre-review BOM v1.2",
      "snapshotData": [...],
      "createdAt": "2026-01-15T10:00:00.000Z"
    }
  ],
  "total": 2
}

POST /api/projects/:id/bom-snapshotsCreates a snapshot of the current BOM state. The server fetches all active BOM items at this moment and stores them in snapshotData. Returns 201 Created.

label

string

required

Human-readable label for this snapshot. Between 1 and 200 characters.

curl -X POST http://localhost:5000/api/projects/1/bom-snapshots \
  -H "X-Session-Id: $SESSION" \
  -H "Content-Type: application/json" \
  -d '{"label": "Pre-review BOM v1.2"}'

{
  "id": 2,
  "projectId": 1,
  "label": "Pre-review BOM v1.2",
  "snapshotData": [
    {
      "id": 1,
      "partNumber": "RC0402FR-0710KL",
      "quantity": 10,
      "unitPrice": "0.0120"
    }
  ],
  "createdAt": "2026-01-15T10:00:00.000Z"
}

DELETE /api/projects/:id/bom-snapshots/:snapshotIdPermanently deletes a snapshot. Returns 204 No Content.

curl -X DELETE http://localhost:5000/api/projects/1/bom-snapshots/2 \
  -H "X-Session-Id: $SESSION"

BOM diff

POST /api/projects/:id/bom-diff Computes a structured diff between a saved snapshot and the current live BOM. The diff engine (shared/bom-diff.ts) categorises each change as added, removed, or modified.

snapshotId

number

required

ID of the snapshot to compare against. The server fetches the snapshot’s snapshotData and compares it to the current active BOM items.

curl -X POST http://localhost:5000/api/projects/1/bom-diff \
  -H "X-Session-Id: $SESSION" \
  -H "Content-Type: application/json" \
  -d '{"snapshotId": 2}'

{
  "added": [
    {
      "partNumber": "GRM188R61A106KE69D",
      "description": "100uF ceramic capacitor",
      "quantity": 4
    }
  ],
  "removed": [],
  "modified": [
    {
      "partNumber": "RC0402FR-0710KL",
      "changes": {
        "quantity": {"from": 10, "to": 20}
      }
    }
  ],
  "unchanged": 3
}

Component lifecycle

The component lifecycle resource tracks the production status of parts used in your design — whether they are active, not recommended for new designs (NRND), end-of-life, or discontinued. Each lifecycle entry can be linked to a BOM item and includes alternate part numbers and data source provenance.

Endpoints

List entries
Create entry
Update entry
Delete entry

GET /api/projects/:id/lifecycleReturns all lifecycle entries for a project.

curl http://localhost:5000/api/projects/1/lifecycle \
  -H "X-Session-Id: $SESSION"

POST /api/projects/:id/lifecycleCreates or upserts a lifecycle entry. If an entry already exists for the partNumber, it is updated in place.

partNumber

string

required

Part number for the component being tracked. Maximum 100 characters.

manufacturer

string

Manufacturer name. Maximum 200 characters.

lifecycleStatus

string

default:"active"

Current lifecycle status. Common values: active, nrnd (not recommended for new designs), eol (end of life), discontinued.

bomItemId

number

ID of the related bom_items record, if any. Links this lifecycle entry to a specific BOM line item.

alternatePartNumbers

string

Comma-separated list of alternate part numbers that can be substituted.

dataSource

string

Source of the lifecycle data, for example "IHS Markit" or "manufacturer website". Maximum 100 characters.

notes

string

Free-text notes about the lifecycle status.

curl -X POST http://localhost:5000/api/projects/1/lifecycle \
  -H "X-Session-Id: $SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "partNumber": "LM317T",
    "manufacturer": "Texas Instruments",
    "lifecycleStatus": "nrnd",
    "alternatePartNumbers": "LM317DCYR,LM317MDCYR",
    "notes": "Prefer LM317DCYR (SOT-223 package) for new designs"
  }'

PATCH /api/projects/:id/lifecycle/:entryIdPartially updates a lifecycle entry. All fields are optional.

curl -X PATCH http://localhost:5000/api/projects/1/lifecycle/3 \
  -H "X-Session-Id: $SESSION" \
  -H "Content-Type: application/json" \
  -d '{"lifecycleStatus": "eol"}'

DELETE /api/projects/:id/lifecycle/:entryIdDeletes a lifecycle entry. Returns 204 No Content.

curl -X DELETE http://localhost:5000/api/projects/1/lifecycle/3 \
  -H "X-Session-Id: $SESSION"

You can ask the AI assistant to automatically populate lifecycle status for components in your BOM. The AI uses its BOM tools to call create_bom_snapshot before major changes and can cross-reference the component lifecycle table to flag NRND and EOL parts during design review.

Setup & Architecture

API Reference

Contributing

BOM API — Items, Snapshots, and Lifecycle

BOM items

Endpoints

BOM CSV export

BOM snapshots

Response fields

Endpoints

BOM diff

Component lifecycle

Endpoints

Build docs developers (and LLMs) love

Setup & Architecture

API Reference

Contributing

Documentation Index

​BOM items

​Endpoints

​BOM CSV export

​BOM snapshots

​Response fields

​Endpoints

​BOM diff

​Component lifecycle

​Endpoints

Build docs developers (and LLMs) love

BOM items

Endpoints

BOM CSV export

BOM snapshots

Response fields

Endpoints

BOM diff

Component lifecycle

Endpoints