CircuitHub Platform Docs

A project represents a PCB design in CircuitHub. Each project has one or more revisions, and each revision has a BOM and board parameters.

Supported file formats

You can upload multiple files at once. All files from a single EDA tool can be combined with an optional BOM CSV for improved part matching.

EDA Tool	Extensions
KiCad	`.kicad_pro`, `.kicad_pcb`, `.kicad_sch`
Eagle	`.brd`, `.sch`
Altium / CircuitMaker	`.PcbDoc`, `.SchDoc`, `.PrjPcb`, `.PrjPcbVariants`, `.PrjPcbStructure`, `.Harness`
IPC-2581	`.cvg`
BOM	`.csv`

The .PrjPcb project file and its companion files are optional and only used with Altium Designer boards. Uploads through the API always build the base design; choosing a design variant is only possible on the upload page.

A .csv file is treated as a BOM and can be uploaded alongside any EDA format. Uploading a BOM CSV gives CircuitHub additional part information (such as MPNs and manufacturer names) for matching, which can reduce unresolved components.

The CSV must include a header row. At minimum it needs Reference Designators and Manufacturer Part Number columns. See the BOM CSV format guide for the full list of supported column names.

List projects

GET /v1/projects

List all projects you have access to for a workspace.

circuithub project list --workspace acme-electronics

Output:

ID      REV   NAME
12345   3     Power Supply Board
12346   1     Sensor Module v2

curl -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  "https://api.circuithub.com/v1/projects?workspace=acme-electronics"

Response:

{
  "projects": [
    {
      "id": 12345,
      "name": "power-supply-board",
      "description": "24V to 5V buck converter",
      "createdAt": "2025-01-10T08:00:00Z",
      "updatedAt": "2025-03-01T14:30:00Z",
      "exportClassification": "EAR99",
      "latestRevisionId": 99001,
      "latestRevisionNumber": 3
    }
  ]
}

Query parameters

Parameter	Type	Description
`workspace`	string	Required. Workspace slug

Response fields

Field	Type	Description
`id`	integer	Project ID
`name`	string	Project name
`description`	string	Project description
`createdAt`	string	ISO 8601 creation timestamp
`updatedAt`	string	ISO 8601 timestamp of the last edit to the project or anything in it
`exportClassification`	string \| null	Export classification (e.g. `"EAR99"`)
`latestRevisionId`	integer	ID of the latest revision
`latestRevisionNumber`	integer	Revision number of the latest revision

updatedAt moves when the project, its revisions, BOMs or board settings are edited, including a new revision's upload. It does not move for changes that are not edits to the project: refreshed part prices and stock, quotes and orders, automatic part suggestions that nobody has yet approved or rejected, and CircuitHub's internal notes. Do not use it to detect every change to a project's data.

Get a project

GET /v1/projects/:projectId

circuithub project show 12345
# or by name
circuithub project show "Power Supply Board"
# JSON output
circuithub project show 12345 --json

Output:

Project:  Power Supply Board
ID:       12345
Desc:     24V to 5V buck converter
Created:  2025-01-10 08:00
Updated:  2025-03-01 14:30
Revision: 3
Import:   complete

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

Response:

{
  "id": 12345,
  "name": "power-supply-board",
  "description": "24V to 5V buck converter",
  "createdAt": "2025-01-10T08:00:00Z",
  "updatedAt": "2025-03-01T14:30:00Z",
  "exportClassification": "EAR99",
  "latestRevisionId": 99001,
  "latestRevisionNumber": 3
}

Create a project

POST /v1/projects

Upload EDA files to create a new project. The <path> can be a file or a directory — when a directory is given, the CLI auto-collects all supported EDA and BOM files. Declare the design's export classification with --export-classification: NotExportControlled, EAR99, or ECCN with --eccn <code>.

circuithub project create power-supply-board ./my-board.kicad_pcb --workspace acme-electronics --export-classification EAR99

# Wait for import to complete before returning
circuithub project create power-supply-board ./my-board.kicad_pcb --workspace acme-electronics --export-classification EAR99 --wait

# Upload a directory containing EDA files and a BOM CSV
circuithub project create power-supply-board ./my-board/ --workspace acme-electronics --export-classification EAR99 --wait

# JSON output
circuithub project create power-supply-board ./my-board.kicad_pcb --workspace acme-electronics --export-classification EAR99 --json

Output:

Project created.
ID:          12345
Revision:    1 (98999)
Status URL:  /v1/projects/12345/status

Creating a project via the API is a three-step process: request presigned upload URLs, upload files directly to S3, then create the project. You can upload multiple files — for example, an IPC-2581 design file alongside a BOM CSV for better part matching.

Step 1 — Request upload URLs:

curl -X POST \
  -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace": "acme-electronics",
    "files": [
      {"filename": "my-board.cvg", "size": 48210},
      {"filename": "bom.csv", "size": 1024}
    ]
  }' \
  https://api.circuithub.com/v1/projects/upload-urls

Response:

{
  "uploads": [
    {
      "filename": "my-board.cvg",
      "uploadUrl": "https://circuithub-uploads.s3.amazonaws.com/...",
      "objectKey": "uploads/abc123/my-board.cvg",
      "validTill": "2025-03-15T11:00:00Z",
      "headers": [
        ["Content-Type", "application/octet-stream"],
        ["x-amz-acl", "bucket-owner-full-control"]
      ]
    },
    {
      "filename": "bom.csv",
      "uploadUrl": "https://circuithub-uploads.s3.amazonaws.com/...",
      "objectKey": "uploads/abc123/bom.csv",
      "validTill": "2025-03-15T11:00:00Z",
      "headers": [
        ["Content-Type", "application/octet-stream"],
        ["x-amz-acl", "bucket-owner-full-control"]
      ]
    }
  ]
}

Step 2 — Upload each file to S3:

# Upload the design file
curl -X PUT \
  -H "Content-Type: application/octet-stream" \
  -H "x-amz-acl: bucket-owner-full-control" \
  --data-binary @my-board.cvg \
  "https://circuithub-uploads.s3.amazonaws.com/..."

# Upload the BOM
curl -X PUT \
  -H "Content-Type: application/octet-stream" \
  -H "x-amz-acl: bucket-owner-full-control" \
  --data-binary @bom.csv \
  "https://circuithub-uploads.s3.amazonaws.com/..."

Step 3 — Create the project:

curl -X POST \
  -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "power-supply-board",
    "workspace": "acme-electronics",
    "exportClassification": {"tag": "EAR99"},
    "files": [
      {"objectKey": "uploads/abc123/my-board.cvg", "filename": "my-board.cvg"},
      {"objectKey": "uploads/abc123/bom.csv", "filename": "bom.csv"}
    ]
  }' \
  https://api.circuithub.com/v1/projects

Response: 200 OK

{
  "projectId": 12345,
  "revisionId": 98999,
  "statusUrl": "/v1/projects/12345/status"
}

Export classification

Project creation requires exportClassification. The example declares {"tag":"EAR99"}; choose the declaration that applies to your design. Other accepted shapes are {"tag":"NotExportControlled"} and {"tag":"ECCN","contents":"3A001"}. contents is required for an ECCN declaration. These are request objects; the project read response presents its classification as a string.

Upload a new revision

POST /v1/projects/:projectId/revisions

Upload EDA and BOM files to add a new revision to an existing project.

circuithub project revision create 12345 ./my-board-v2.kicad_pcb --workspace acme-electronics

# By project name
circuithub project revision create power-supply-board ./my-board-v2.kicad_pcb --workspace acme-electronics

# Upload a directory containing EDA files and a BOM CSV
circuithub project revision create 12345 ./my-board-v2/ --workspace acme-electronics --wait

# JSON output
circuithub project revision create 12345 ./my-board-v2.kicad_pcb --workspace acme-electronics --json

Output:

Revision created.
Project ID:  12345
Revision:    4 (99002)
Status URL:  /v1/projects/12345/status

The same three-step presigned URL flow as creating a project. You can include multiple files (e.g. design files and a BOM CSV).

Step 1 — Request upload URLs:

curl -X POST \
  -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace": "acme-electronics",
    "files": [
      {"filename": "my-board-v2.kicad_pcb", "size": 51030},
      {"filename": "bom.csv", "size": 1024}
    ]
  }' \
  https://api.circuithub.com/v1/projects/upload-urls

Step 2 — Upload each file to S3 (same as above).

Step 3 — Create the revision:

curl -X POST \
  -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {"objectKey": "uploads/def456/my-board-v2.kicad_pcb", "filename": "my-board-v2.kicad_pcb"},
      {"objectKey": "uploads/def456/bom.csv", "filename": "bom.csv"}
    ]
  }' \
  https://api.circuithub.com/v1/projects/12345/revisions

Response: 200 OK

{
  "projectId": 12345,
  "revisionId": 99002,
  "statusUrl": "/v1/projects/12345/status"
}

Project status

GET /v1/projects/:projectId/status

Check the import status of a project after uploading.

# Check status (exit code: 0=complete, 1=failed, 2=importing)
circuithub project status 12345

# Poll until import completes
circuithub project watch 12345
circuithub project watch 12345 --timeout 10m

Output (project status):

Project 12345: importing

Output (project watch, on completion):

Project 12345: complete

curl -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  https://api.circuithub.com/v1/projects/12345/status

Response:

{
  "projectId": 12345,
  "status": "importing",
  "message": null
}

Response fields

Field	Type	Description
`projectId`	integer	Project ID
`status`	string	`"importing"`, `"complete"`, or `"failed"`
`message`	string \| null	Error message when status is `"failed"`

List revisions

GET /v1/projects/:projectId/revisions

circuithub project revision list 12345
# by project name
circuithub project revision list "Power Supply Board" --workspace acme-electronics

Output:

REV   ID      CREATED
3     99001   2025-03-01T14:30:00Z
2     99000   2025-02-15T10:00:00Z
1     98999   2025-01-10T08:00:00Z

curl -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  https://api.circuithub.com/v1/projects/12345/revisions

Response:

{
  "revisions": [
    {
      "id": 99001,
      "number": 3,
      "createdAt": "2025-03-01T14:30:00Z",
      "importedAt": "2025-03-01T14:35:00Z",
      "edaTool": "kicad",
      "edaError": null
    }
  ]
}

Response fields

Field	Type	Description
`id`	integer	Revision ID
`number`	integer	Sequential revision number
`createdAt`	string	ISO 8601 creation timestamp
`importedAt`	string \| null	ISO 8601 timestamp when import completed
`edaTool`	string \| null	Detected EDA tool (e.g. `"kicad"`, `"altium"`, `"eagle"`)
`edaError`	string \| null	EDA import error message, if any

Projects

Supported file formats

List projects

Query parameters

Response fields

Get a project

Create a project

Export classification

Upload a new revision

Project status

Response fields

List revisions

Response fields

On this page