API Reference¶

Bambuddy provides a REST API for integration with external tools and automation.

Authentication¶

API Key Authentication¶

Include your API key in the X-API-Key header:

curl -H "X-API-Key: your-api-key" \
  http://localhost:8000/api/v1/printers

Getting an API Key¶

Go to Settings > API Keys
Click Create API Key
Select permissions
Copy the key (shown only once)

See API Keys & Webhooks for details.

Base URL¶

http://your-server:8000/api/v1

All endpoints are relative to this base URL.

Printers¶

List Printers¶

GET /printers

Response:

[
  {
    "id": 1,
    "name": "Workshop X1C",
    "ip_address": "192.168.1.100",
    "serial_number": "01P00A000000001",
    "model": "X1 Carbon",
    "status": "idle"
  }
]

Get Printer¶

GET /printers/{id}

Response:

{
  "id": 1,
  "name": "Workshop X1C",
  "ip_address": "192.168.1.100",
  "serial_number": "01P00A000000001",
  "model": "X1 Carbon",
  "status": "printing",
  "current_print": {
    "filename": "benchy.3mf",
    "progress": 45,
    "remaining_time": 3600
  }
}

Get Printer Status¶

GET /printers/{id}/status

Response:

{
  "state": "printing",
  "progress": 45,
  "remaining_time": 3600,
  "current_layer": 120,
  "total_layers": 267,
  "temperatures": {
    "nozzle": 220,
    "bed": 60,
    "chamber": 35
  },
  "hms_status": "ok"
}

Refresh Printer Status¶

Request a full status update from the printer via MQTT pushall command. Useful for getting fresh AMS data after swapping spools.

POST /printers/{id}/refresh-status

Response:

{
  "status": "refresh_requested"
}

Errors:

404 - Printer not found
400 - Printer not connected

Add Printer¶

POST /printers

Request:

{
  "name": "New Printer",
  "ip_address": "192.168.1.101",
  "access_code": "12345678",
  "serial_number": "01P00A000000002"
}

Update Printer¶

PATCH /printers/{id}

Request:

{
  "name": "Updated Name"
}

Delete Printer¶

DELETE /printers/{id}

Archives¶

List Archives¶

GET /archives

Query Parameters:

Parameter	Type	Description
`printer_id`	int	Filter by printer
`status`	string	success, failed, stopped
`start_date`	date	Filter from date
`end_date`	date	Filter to date
`search`	string	Full-text search
`project_id`	int	Filter by project
`limit`	int	Max results (default: 50)
`offset`	int	Pagination offset

Response:

{
  "total": 1234,
  "archives": [
    {
      "id": 1,
      "name": "Benchy",
      "filename": "benchy.3mf",
      "printer_id": 1,
      "printer_name": "Workshop X1C",
      "created_at": "2024-01-15T14:30:00Z",
      "duration": 8100,
      "status": "success",
      "filament_used": 45.2,
      "filament_type": "PLA"
    }
  ]
}

Get Archive¶

GET /archives/{id}

Update Archive¶

PATCH /archives/{id}

Request:

{
  "name": "Updated Name",
  "notes": "Great print",
  "tags": ["functional", "gift"]
}

Delete Archive¶

DELETE /archives/{id}

Download 3MF¶

GET /archives/{id}/3mf

Returns the 3MF file as download.

Export Archives¶

GET /archives/export

Query Parameters:

Parameter	Type	Description
`format`	string	csv or xlsx
(others)		Same filters as list

Projects¶

List Projects¶

GET /projects

Get Project¶

GET /projects/{id}

Create Project¶

POST /projects

Request:

{
  "name": "Voron Build",
  "description": "Building a Voron 2.4",
  "color": "#4caf50",
  "target_count": 100
}

Update Project¶

PATCH /projects/{id}

Delete Project¶

DELETE /projects/{id}

Print Queue¶

Get Queue¶

GET /queue

Query Parameters:

Parameter	Type	Description
`printer_id`	int	Filter by printer
`status`	string	pending, printing, completed

Add to Queue¶

POST /queue

Request:

{
  "archive_id": 123,
  "printer_id": 1,
  "scheduled_time": "2024-01-15T18:00:00Z"
}

Remove from Queue¶

DELETE /queue/{id}

Reorder Queue¶

POST /queue/reorder

Request:

{
  "order": [3, 1, 2, 4]
}

Statistics¶

Get Statistics¶

GET /statistics

Query Parameters:

Parameter	Type	Description
`printer_id`	int	Filter by printer
`start_date`	date	Period start
`end_date`	date	Period end

Response:

{
  "total_prints": 1234,
  "successful_prints": 1100,
  "failed_prints": 100,
  "stopped_prints": 34,
  "success_rate": 89.14,
  "total_print_time": 360000,
  "total_filament_used": 15000.5,
  "total_cost": 350.00
}

Export Statistics¶

GET /statistics/export

Camera¶

Stream (MJPEG)¶

GET /printers/{id}/camera/stream

Returns MJPEG stream. Query params:

Parameter	Type	Description
`fps`	int	Frames per second (1-30)

Snapshot¶

GET /printers/{id}/camera/snapshot

Returns single JPEG image.

Stop Stream¶

POST /printers/{id}/camera/stop

Terminates active streams for printer.

System¶

System Info¶

GET /system/info

Response:

{
  "version": "0.1.5b6",
  "uptime": 86400,
  "database": {
    "archives": 1234,
    "size_mb": 45.6
  }
}

Health Check¶

GET /health

Response:

{
  "status": "healthy",
  "database": "connected",
  "mqtt": "connected"
}

Error Responses¶

Error Format¶

{
  "detail": "Error message",
  "code": "ERROR_CODE"
}

HTTP Status Codes¶

Code	Meaning
200	Success
201	Created
400	Bad Request
401	Unauthorized (no/invalid API key)
403	Forbidden (insufficient permissions)
404	Not Found
429	Rate Limited
500	Server Error

Rate Limits¶

Endpoint Type	Limit
Read	100/minute
Write	30/minute
Control	10/minute

Rate Limit Headers¶

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705331400

Content Types¶

Request¶

Content-Type: application/json

Response¶

Content-Type: application/json

Except for file downloads (application/octet-stream) and images (image/jpeg).

Webhooks¶

Bambuddy can send webhooks for events. Configure in Settings > Notifications.

Webhook Payload¶

{
  "event": "print_complete",
  "timestamp": "2024-01-15T14:30:00Z",
  "data": {
    "printer_id": 1,
    "printer_name": "Workshop X1C",
    "archive_id": 123,
    "filename": "benchy.3mf",
    "duration": 8100,
    "status": "success"
  }
}

Event Types¶

Event	Trigger
`print_started`	Print begins
`print_progress`	Progress milestone
`print_complete`	Print finishes
`print_failed`	Print fails
`printer_offline`	Connection lost
`printer_error`	HMS error