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!

Permissions¶

Available Permissions¶

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

Principle of Least Privilege¶

Only grant permissions that are needed:

• Read-only for dashboards
• Control for automation
• Tariff scope only on the HA-integration key

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 pipeline needs.

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¶