CircuitHub Platform Docs

Issues let you track problems, defects, or follow-up items on a manufacturing order. Every issue belongs to an order. You can list issues and create a new issue with an optional initial comment.

List issues

GET /v1/issues

circuithub issue list --workspace acme-electronics
circuithub issue list --workspace acme-electronics --order 8001
circuithub issue list --workspace acme-electronics --status open

Output:

ID     PROJECT           ORDER   TITLE                    STATUS   CREATED BY       CREATED
7001   Power Supply      8001    Wrong footprint on C12   open     alice@acme.co    2025-03-02T09:00:00Z
7002   Sensor Module     8002    BOM needs review         closed   bob@acme.co      2025-02-25T14:30:00Z

curl -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  "https://api.circuithub.com/v1/issues?workspace=acme-electronics&order=8001&status=open"

Response:

{
  "issues": [
    {
      "id": 7001,
      "projectId": 12345,
      "orderId": 8001,
      "title": "Wrong footprint on C12",
      "status": "open",
      "createdBy": {
        "id": 501,
        "email": "alice@acme.co"
      },
      "createdAt": "2025-03-02T09:00:00Z",
      "updatedAt": "2025-03-02T09:00:00Z"
    }
  ]
}

Query parameters

Parameter	Type	Description
`workspace`	string	Required. Workspace slug
`order`	integer	Filter by order ID (optional)
`status`	string	Filter by status: `open`, `closed` (optional)

Response fields

Field	Type	Description
`id`	integer	Issue ID
`projectId`	integer	Project the order belongs to
`orderId`	integer	Order this issue is filed against
`title`	string	Short summary
`status`	string	`open` or `closed`
`createdBy`	object	`{ id, email }` of the user who created the issue
`createdAt`	string	ISO 8601 creation timestamp
`updatedAt`	string	ISO 8601 last update timestamp

Create an issue

POST /v1/orders/:orderId/issues

circuithub issue create 8001 --title "Wrong footprint on C12"
# with an initial comment
circuithub issue create 8001 \
  --title "BOM mismatch" \
  --comment "Assembly house reported incorrect part"

Output:

ID:          7003
Project:     Power Supply (12345)
Order:       8001
Title:       BOM mismatch
Status:      open
Created by:  alice@acme.co
Created:     2025-03-03T08:00:00Z
Updated:     2025-03-03T08:00:00Z

curl -X POST \
  -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Wrong footprint on C12", "comment": "C12 should be 0805, not 0402"}' \
  https://api.circuithub.com/v1/orders/8001/issues

Response: 201 Created

{
  "id": 7003,
  "projectId": 12345,
  "orderId": 8001,
  "title": "Wrong footprint on C12",
  "status": "open",
  "createdBy": {
    "id": 501,
    "email": "alice@acme.co"
  },
  "createdAt": "2025-03-03T08:00:00Z",
  "updatedAt": "2025-03-03T08:00:00Z"
}

Path parameters

Parameter	Type	Description
`orderId`	integer	Required. Order ID to file the issue against

Request body

Field	Type	Required	Description
`title`	string	yes	Short summary of the issue
`comment`	string	no	Optional initial comment attached to the issue when it is created

Issue creation supports an optional initial comment. Follow-up comments and comment attachments are planned as the next step, using the same direct-upload pattern as project files: request an upload URL, upload the file directly, then create the comment referencing the uploaded object.

Planned attachment workflow

This is the intended contract for attachment support; it is not part of the current issue list/create rollout.

# 1. Request an upload URL for the attachment
circuithub issue attachment upload-url 7001 --file layout-rev4.zip

# 2. Upload the file directly to object storage
curl -X PUT -T layout-rev4.zip "$UPLOAD_URL"

# 3. Create the comment with the uploaded attachment reference
circuithub issue comment 7001 "See updated layout" --attach-object "$OBJECT_KEY"

# 1. Request an upload URL
curl -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  "https://api.circuithub.com/v1/issues/7001/upload-url?filename=layout-rev4.zip&uuid=0f6d6f74-7d92-4d20-bf6c-2e37d2c1d9c8"

Response:

{ "uploadUrl": "https://...", "objectKey": "orders/issues/comments/attachments/..." }

# 2. Upload the file directly to object storage
curl -X PUT -T layout-rev4.zip "$UPLOAD_URL"

# 3. Create the comment with the uploaded object key
curl -X POST \
  -H "Authorization: Bearer $CIRCUITHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body": "See updated layout", "attachments": [{"name": "layout-rev4.zip", "url": "'"$OBJECT_KEY"'"}]}' \
  https://api.circuithub.com/v1/issues/7001/comments

Request an upload URL for the issue attachment.
Upload the file directly to object storage using the returned URL.
Create the comment and include the uploaded object key in the comment attachment list.

This keeps large files off the application server, matches the project upload pattern, and lets clients retry uploads independently from comment creation.

Initial comments on issue create will not include attachments in the first release.

Issues