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	`.PrjPcb`, `.PcbDoc`, `.SchDoc`
IPC-2581	`.cvg`
BOM	`.csv`

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 last update timestamp
`exportClassification`	string \| null	Export classification (e.g. `"EAR99"`)
`latestRevisionId`	integer	ID of the latest revision
`latestRevisionNumber`	integer	Revision number of the latest revision

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.

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

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

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

# JSON output
circuithub project create power-supply-board ./my-board.kicad_pcb --workspace acme-electronics --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",
    "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: 201 Created

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

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

# 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/ --wait

# JSON output
circuithub project revision create 12345 ./my-board-v2.kicad_pcb --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: 201 Created

{
  "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

Upload a new revision

Project status

Response fields

List revisions

Response fields

On this page