CircuitHub Platform Docs

Every project revision has a Bill of Materials (BOM) — the list of electronic components needed to assemble the board. The BOM endpoint returns each line with its resolution status, telling you whether CircuitHub has matched the component to a purchasable part.

You can improve part matching by uploading a BOM CSV alongside your design files when creating a project or uploading a new revision. The CSV gives CircuitHub additional part information (such as MPNs and manufacturer names) that may not be present in the EDA design files alone. See Supported file formats for details on the CSV format.

Get a BOM

GET /v1/projects/:projectId/bom

Returns the BOM for the project's latest revision. Pass ?revision= to get the BOM for a specific revision.

circuithub project bom list 12345 --workspace acme-electronics

Output:

BOM: 4 lines (2 resolved, 1 unresolved, 1 errored)

Part                Footprint    Qty  Match
100nF 0402          C_0402         4  GCM155R71C104KA55D (Murata)
10uF 0805           C_0805         2  GRM21BR61E106KA73 (Murata)
LM358               SOIC-8         1  -
BAD_PART            QFN-24         1  error

Use --json for machine-readable output:

circuithub project bom list 12345 --workspace acme-electronics --json

# Latest revision
curl -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  https://api.circuithub.com/v1/projects/12345/bom

# Specific revision
curl -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  "https://api.circuithub.com/v1/projects/12345/bom?revision=99001"

Response:

{
  "revisionId": 99001,
  "bomLines": [
    {
      "id": 1001,
      "value": "100nF",
      "footprint": "C_0402",
      "description": "Ceramic capacitor",
      "referenceDesignators": ["C1", "C2", "C3", "C4"],
      "status": "resolved",
      "resolvedPartMpn": "GCM155R71C104KA55D",
      "resolvedPartDescription": "100nF 16V X7R 0402",
      "resolvedManufacturer": "Murata"
    },
    {
      "id": 1003,
      "value": "LM358",
      "footprint": "SOIC-8",
      "description": "Dual op-amp",
      "referenceDesignators": ["U1"],
      "status": "unresolved",
      "resolvedPartMpn": null,
      "resolvedPartDescription": null,
      "resolvedManufacturer": null
    }
  ],
  "summary": {
    "total": 4,
    "resolved": 2,
    "unresolved": 1,
    "errored": 1
  }
}

Query parameters

Parameter	Type	Description
`revision`	integer	Revision ID. Defaults to the latest revision if omitted

Set a part on a BOM line

PUT /v1/bom/:bomLineId/part

Set the part for a BOM line. Use the BOM line id from GET /v1/projects/:projectId/bom and a part id from GET /v1/parts.

Positional argument order is: BOM line ID, then part ID.

circuithub project bom set-part 1003 5001

Output:

BOM 1003  resolved  LM358DR (Texas Instruments)

Use --json for machine-readable output:

circuithub project bom set-part 1003 5001 --json

curl -X PUT \
  -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"partId": 5001}' \
  https://api.circuithub.com/v1/bom/1003/part

Response: 200 OK

{
  "partId": 5001,
  "mpn": "LM358DR",
  "manufacturer": "Texas Instruments"
}

Request body

Field	Type	Description
`partId`	integer	Required. Part ID from `GET /v1/parts`

Response fields

Field	Type	Description
`partId`	integer	Part ID that was set on the BOM line
`mpn`	string	Manufacturer part number
`manufacturer`	string	Manufacturer name

Set DNP on a placement

PUT /v1/bom/:bomLineId/placements/:ref/dnp

Mark or unmark a placement as Do Not Place (DNP). A DNP placement will not be assembled or purchased. Use the BOM line id and the reference designator from GET /v1/projects/:projectId/bom. The reference designator is passed in the URL path.

Positional argument order is: BOM line ID, then reference designator.

# Mark as DNP
circuithub project bom set-dnp 1001 C3

# Clear DNP
circuithub project bom clear-dnp 1001 C3

Output:

C3  DNP

# Mark as DNP
curl -X PUT \
  -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dnp": true}' \
  https://api.circuithub.com/v1/bom/1001/placements/C3/dnp

# Unmark DNP
curl -X PUT \
  -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dnp": false}' \
  https://api.circuithub.com/v1/bom/1001/placements/C3/dnp

Response (set): 200 OK

{
  "ref": "C3",
  "dnp": true
}

Response (clear): 200 OK

{
  "ref": "C3",
  "dnp": false
}

Request body

Field	Type	Description
`dnp`	boolean	Required. `true` to mark as DNP, `false` to unmark

Path parameters

Field	Type	Description
`ref`	string	Required. Reference designator in the URL path (e.g. `"C3"`)

Response fields

Field	Type	Description
`ref`	string	Reference designator
`dnp`	boolean	Current DNP state

BOM line fields

Field	Type	Description
`id`	integer	BOM line ID
`value`	string \| null	Component value (e.g. `"100nF"`)
`footprint`	string \| null	Component footprint (e.g. `"C_0402"`)
`description`	string \| null	Component description
`referenceDesignators`	string[]	Reference designators (e.g. `["C1", "C2"]`)
`status`	string	One of `"resolved"`, `"unresolved"`, `"error"`
`resolvedPartMpn`	string \| null	Matched manufacturer part number
`resolvedPartDescription`	string \| null	Matched part description
`resolvedManufacturer`	string \| null	Matched manufacturer name

Summary fields

Field	Type	Description
`total`	integer	Total BOM lines
`resolved`	integer	Lines matched to a purchasable part
`unresolved`	integer	Lines without a match
`errored`	integer	Lines that failed resolution

Bill of Materials

On this page