API Keys & Webhooks¶

Integrate Bambuddy with external tools using API keys and webhooks.

API Keys¶

Overview¶

API keys allow external applications to:

• Access Bambuddy data
• Trigger actions
• Integrate with automation tools

Creating an API Key¶

1. Go to Settings > API Keys
2. Click Create API Key
3. Enter a name (e.g., "Home Assistant")
4. Select permissions
5. Click Create
6. Copy the key immediately - it won't be shown again!

Mobile setup with a QR code¶

The success panel shown right after you create a key has a QR code button next to Use in API Browser:

Click it to display a QR code that encodes the Bambuddy server URL and the new API key together, so a compatible mobile app (for example, an NFC spool-inventory app) can scan once to configure both — no copy-pasting the long key by hand.

The encoded server URL comes from your configured Settings → Network → External URL, falling back to the address you're currently viewing Bambuddy on. If clients connect from outside your LAN (reverse proxy, Docker host, VPN), set the External URL so the scanned address is actually reachable from the phone.

bambuddy://config?v=1&url=<url-encoded base URL>&key=<url-encoded API key>

Permissions¶

Available Permissions¶

API keys are intentionally scoped narrowly — they cannot perform administrative operations (user management, full settings updates, backup restore, firmware installs). The ten toggles you can set on a key are:

Principle of Least Privilege¶

Only grant permissions that are needed:

• Read-only dashboards: Read Status only.
• Home Assistant queue automation: Read Status + Manage Queue.
• Home Assistant queue + start prints: + Control Printer.
• Headless slicer / library-uploading automation: + Manage Library.
• SpoolBuddy kiosks (bundled installs handle this for you): + Manage Inventory.
• Home Assistant maintenance-log automation ("cleaned nozzle every N hours"): Read Status + Manage Maintenance.
• Print-history cleanup automation (prune old archives): Read Status + Manage Archives.
• Filing finished prints into projects: Read Status + Manage Projects.
• Trigger a slicer pipeline from an automation: Read Status + Manage Queue + Manage Library.
• HA dynamic-tariff integration: + Update Electricity Price.
• Slicing against Bambu Cloud or Orca Cloud presets (whether from a pipeline or a direct slice call): + Allow Cloud Access (requires owner sign-in).

Upgrade Notes¶

When upgrading from a pre-0.2.4.5 install:

• Existing keys are backfilled: Manage Library and Manage Inventory default to whatever Manage Queue was set to (so "queue-only" keys keep working for the upload+queue workflow they already used, while hardened "read-only" keys do not silently gain write capabilities).
• Manage Maintenance was carved out of the admin denylist in the #1832 follow-up. It was explicitly denied for every API key beforehand, so no existing integration relies on it — existing keys are backfilled to off, and new keys default to on. Toggle it explicitly if an older key needs to log maintenance events.
• Manage Archives was carved out of the admin denylist in #1888 (archive delete/edit previously returned 403 for every API key). Same shape as Manage Maintenance: explicitly denied beforehand, so existing keys are backfilled to off and new keys default to on. Toggle it explicitly if an older key needs to delete or edit archives.
• Manage Projects was carved out of the admin denylist in #1893 (creating a project, or adding archives to one, previously returned 403 for every API key). Same shape again: existing keys are backfilled to off and new keys default to on. Toggle it explicitly if an older key needs to manage projects.
• Slicer pipelines were unreachable from any API key until the run dispatch shipped; every pipeline endpoint answered 403. They now ride the toggles you already have — no new checkbox, and nothing to backfill — so a key that already holds Manage Queue and Manage Library can run a pipeline after upgrading. That grants no capability it lacked: such a key could already slice a library file and queue prints directly, and a pipeline only composes those two steps using settings an administrator authored.
• The bundled SpoolBuddy kiosk key is explicitly granted Manage Inventory by the CLI (it needs to write NFC scans and scale readings).
• If a previously-working integration starts returning 403, the missing toggle is named in the response body — tick it in Settings → API Keys, regenerate or update the key, and retry.

Cloud Access Scope¶

API keys created in v0.2.4 and later carry an explicit owner (the user who created them) and an opt-in cloud-access scope. This unlocks a workflow that was previously blocked: reading the owner's Bambu Cloud presets, filament catalogue, and device list from /api/v1/cloud/* endpoints — exactly what a headless slicing workflow needs. It is also what lets a slicer pipeline built on cloud presets be run by an API key rather than only by a signed-in person.

When to enable it¶

Tick Allow cloud access on the create form when the key needs to:

• Pull filament profiles (GET /cloud/filaments) for an automated slicer
• List your Bambu Cloud devices (GET /cloud/devices)
• Read printer firmware availability (GET /cloud/firmware-updates)
• Read your slicer presets (GET /cloud/settings)

The flag defaults to off, so existing automation never silently gains cloud-read access on upgrade.

Three fences a key must pass for /cloud/*¶

When an API-keyed call reaches /api/v1/cloud/*, three checks all need to succeed:

1. The key has an owner. Keys created before v0.2.4 have no owner and are shown as Legacy in the API Keys list — they're rejected at /cloud/* with a "recreate it" message. Every other endpoint they were used against (queue, status, control) keeps working.
2. Allow cloud access is enabled on the key. Otherwise /cloud/* returns 403 with a "enable cloud access" hint.
3. The owner is signed into Bambu Cloud (Settings → Cloud Profiles). Without a stored token, /cloud/* returns the standard token-not-set error.

Auth-disabled deployments¶

The cloud-access scope only makes sense when authentication is enabled — auth-disabled deployments don't have per-user cloud tokens to read against. The create form refuses Allow cloud access = true in that mode with a 400 Bad Request so you don't end up with a non-functional key.

Migrating older keys¶

Keys created before v0.2.4 keep working against every non-cloud endpoint without any change. To grant one of them cloud access, delete the key and recreate it — there's no in-place upgrade because the original creator identity wasn't recorded at the time.

Owner deletion¶

Deleting a user removes all of their API keys (ON DELETE CASCADE on PostgreSQL, plus an explicit cleanup step in the user-delete route for SQLite where FK enforcement is off by default). Orphan keys can never authenticate.

Using the API¶

Authentication¶

Include the API key in request headers:

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

Base URL¶

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

Common Endpoints¶

See API Reference for complete documentation.

Interactive API Browser¶

Bambuddy includes a built-in API browser for testing endpoints directly in the interface.

Accessing the API Browser¶

The API Browser appears in the right column of the API Keys settings page.

1. Go to Settings > API Keys
2. Scroll to see the API Browser on the right

Features¶

• Auto-discovery - All endpoints loaded from OpenAPI schema
• Grouped by category - Printers, archives, settings, etc.
• Parameter inputs - Fill in path, query, and body parameters
• Request body examples - Pre-filled from schema
• Live execution - Test requests and see responses
• Response display - Formatted JSON with status and timing
• Search - Filter endpoints across categories

Using with API Keys¶

1. Paste an API key in the "API Key for Testing" input
2. Expand an endpoint and fill in parameters
3. Click Execute to make the request
4. View the response below

Webhooks¶

Outgoing Webhooks¶

Bambuddy can send notifications to external URLs:

1. Go to Settings > Notifications
2. Add a Webhook provider
3. Enter your endpoint URL
4. Configure events to trigger

Payload Format¶

{
  "event": "print_complete",
  "timestamp": "2024-01-15T14:30:00Z",
  "data": {
    "printer": "Workshop X1C",
    "filename": "benchy.3mf",
    "duration": 8100,
    "filament_used": 45.2,
    "filament_details": "PLA: 30.0g | PETG: 15.2g",
    "status": "success"
  }
}

For failed/stopped prints, filament_used is scaled by progress and additional fields are included:

{
  "event": "print_failed",
  "timestamp": "2024-01-15T15:15:00Z",
  "data": {
    "printer": "Workshop X1C",
    "filename": "benchy.3mf",
    "duration": 2700,
    "filament_used": 7.6,
    "filament_details": "PLA: 7.6g",
    "progress": 50,
    "reason": "Filament runout",
    "status": "failed"
  }
}

Events¶

Integration Examples¶

Home Assistant¶

Use REST sensors to display status:

sensor:
  - platform: rest
    name: "Bambuddy Printer Status"
    resource: "http://bambuddy:8000/api/v1/printers/1/status"
    headers:
      X-API-Key: "your-api-key"
    value_template: "{{ value_json.state }}"
    json_attributes:
      - progress
      - remaining_time
      - temperature

Trigger automations on webhook events.

Node-RED¶

Use HTTP request nodes with API key authentication.

IFTTT / Zapier¶

Use webhook triggers and actions.

Managing API Keys¶

Viewing Keys¶

See all API keys in Settings:

• Name
• Created date
• Last used
• Permissions

Revoking Keys¶

Delete keys that are no longer needed:

1. Find the key in the list
2. Click Delete
3. Confirm deletion

Key is immediately invalidated.

Rotating Keys¶

Best practice: Rotate keys periodically:

1. Create new key
2. Update applications
3. Delete old key

Security Best Practices¶

Key Storage¶

• Never commit keys to version control
• Use environment variables
• Store in secrets managers

Network Security¶

• Use HTTPS for external access
• Limit API access to trusted IPs if possible
• Consider VPN for remote access

Monitoring¶

• Review API key usage
• Check for unauthorized access
• Revoke unused keys

Permissions¶

• Use minimum required permissions
• Create separate keys per application
• Avoid using admin keys in automation

Troubleshooting¶

401 Unauthorized¶

• Check API key is correct
• Verify key hasn't been revoked
• Ensure header name is X-API-Key

403 Forbidden¶

• Check key has required permissions
• Verify endpoint matches permissions

Tips¶