vinez/bambuddy
1
0
Fork 0
mirror of https://github.com/maziggy/bambuddy.git synced 2026-08-11 00:30:12 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions
bambuddy/docs/bambu_lab_preset_sync_api.md
maziggy e47ef36630 sync
2025-12-08 09:56:21 +00:00

8 KiB
Raw Permalink Blame History

Bambu Lab Preset Sync API Documentation

This document describes the Bambu Lab cloud API endpoints for syncing slicer presets (filament, print process, and machine profiles) between Bambu Studio and the cloud.

Captured from: Bambu Studio v2.4.0.70 with bambu_network_agent v02.04.00.58 Date: 2025-12-08

Authentication

All API requests require authentication via Bearer token.

Required Headers

Host: api.bambulab.com
Authorization: Bearer <access_token>
User-Agent: bambu_network_agent/02.04.00.58
X-BBL-Client-Name: BambuStudio
X-BBL-Client-Type: slicer
X-BBL-Client-Version: 02.04.00.70
X-BBL-Device-ID: <uuid>
X-BBL-Language: en-US
X-BBL-OS-Type: macos|windows|linux
X-BBL-OS-Version: <version>
X-BBL-Agent-Version: 02.04.00.58
accept: application/json

Endpoints

1. Get User Profile

GET /v1/user-service/my/profile

Returns user account information including UID.

2. List All User Presets

GET /v1/iot-service/api/slicer/setting?version={slicer_version}&public=false

Parameters:

  • version: Slicer version (e.g., 2.4.0.5)
  • public: Set to false for user presets only

Response: Returns a list of preset IDs that the user has synced to cloud.

3. Get Individual Preset

GET /v1/iot-service/api/slicer/setting/{preset_id}

Response:

{
    "message": "success",
    "code": null,
    "error": null,
    "public": false,
    "version": "1.5.0.20",
    "type": "filament",
    "name": "Devil Design PLA @Bambu Lab X1 Carbon 0.6 nozzle",
    "update_time": "2025-12-08 01:06:27",
    "nickname": null,
    "base_id": "GFSA00",
    "setting": {
        "inherits": "Bambu PLA Basic @BBL X1C",
        "filament_vendor": "\"Devil Design\"",
        "nozzle_temperature": "225,220",
        "pressure_advance": "0.03",
        "updated_time": "1765138658"
    },
    "filament_id": null
}

Preset ID Naming Convention

Preset IDs follow a specific prefix pattern indicating the type:

Prefix Type Description
PPUS Print Process Print/quality settings (layer height, speeds, infill, etc.)
PFUS Filament Filament settings (temperatures, flow, pressure advance, etc.)
PMUS Printer/Machine Machine settings (gcode, bed size, kinematics, etc.)

The suffix after the prefix is a unique hash identifier.

Examples:

  • PPUS1b03400426f57d - Print process preset
  • PFUS169056f3003bb4 - Filament preset
  • PMUSbc396893c54df0 - Machine/printer preset

Preset Response Schema

Common Fields

Field Type Description
message string API response status ("success")
code int/null Error code if any
error string/null Error message if any
public boolean Whether preset is publicly shared
version string Preset version
type string Preset type: "filament", "print", or "printer"
name string Display name of the preset
update_time string Last update timestamp (ISO format)
nickname string/null Optional user-defined nickname
base_id string Reference ID of the parent/base preset
setting object Key-value pairs of customized settings
filament_id string/null Bambu filament ID if applicable

Setting Object

The setting object contains only the delta/modified values from the parent preset. Key fields include:

  • inherits: Name of the parent preset this inherits from
  • updated_time: Unix timestamp of last modification
  • Other fields depend on preset type (see below)

Preset Types and Common Settings

Filament Presets (PFUS)

{
    "inherits": "Bambu PLA Basic @BBL X1C",
    "filament_vendor": "\"Devil Design\"",
    "filament_cost": "20",
    "filament_settings_id": "\"Devil Design PLA @Bambu Lab X1 Carbon 0.6 nozzle\"",
    "nozzle_temperature": "225,220",
    "nozzle_temperature_initial_layer": "225,220",
    "hot_plate_temp": "60",
    "cool_plate_temp": "60",
    "textured_plate_temp": "60",
    "pressure_advance": "0.03",
    "enable_pressure_advance": "1",
    "filament_max_volumetric_speed": "30,29",
    "activate_air_filtration": "1",
    "during_print_exhaust_fan_speed": "50",
    "complete_print_exhaust_fan_speed": "50",
    "close_fan_the_first_x_layers": "2",
    "overhang_fan_threshold": "10%",
    "slow_down_layer_time": "5",
    "temperature_vitrification": "65",
    "filament_start_gcode": "...",
    "filament_end_gcode": "..."
}

Print Process Presets (PPUS)

{
    "inherits": "0.08mm Extra Fine @BBL H2D",
    "print_settings_id": "# 0.08mm Extra Fine @BBL H2D",
    "prime_tower_max_speed": "100",
    "prime_tower_rib_wall": "0",
    "prime_tower_width": "20"
}

Machine/Printer Presets (PMUS)

{
    "inherits": "Bambu Lab H2D 0.4 nozzle",
    "printer_settings_id": "# Bambu Lab H2D 0.4 nozzle",
    "bed_custom_model": "/path/to/model.stl",
    "machine_start_gcode": "...",
    "machine_end_gcode": "...",
    "change_filament_gcode": "...",
    "printer_notes": "...",
    "support_air_filtration": "1"
}

Base ID Reference

The base_id field references Bambu's internal preset database:

Prefix Type
GF Generic Filament
GP Generic Print Process
GM Generic Machine

Examples:

  • GFSA00 - Generic filament base
  • GP136 - Generic print process base
  • GM033 - Generic machine base (H2D)

API Operations (Verified)

Create Preset

POST /v1/iot-service/api/slicer/setting
Content-Type: application/json

{
    "type": "filament",
    "name": "My Custom PLA",
    "version": "2.0.0.0",
    "base_id": "GFSA00",
    "setting": {
        "inherits": "Bambu PLA Basic @BBL X1C",
        "nozzle_temperature": "210,205",
        "updated_time": "1733665800"
    }
}

Required fields:

  • type: "filament", "print", or "printer"
  • name: Display name
  • version: Version string (e.g., "2.0.0.0", "2.3.0.2")
  • base_id: Parent preset ID
  • setting: Object with modified values including updated_time (Unix timestamp)

Response:

{
    "message": "success",
    "code": null,
    "error": null,
    "setting_id": "PFUSe99f2ff04974b4",
    "update_time": "2025-12-08 16:31:48"
}

Update Preset

Important: The Bambu Cloud API does NOT support true updates via PUT/PATCH.

  • PUT /v1/iot-service/api/slicer/setting/{preset_id} returns 405 Method Not Allowed
  • PATCH /v1/iot-service/api/slicer/setting/{preset_id} returns 500 Cloud database failed

Workaround: To "update" a preset:

  1. GET the existing preset details
  2. Merge your changes
  3. POST to create a new preset (returns new setting_id)
  4. DELETE the old preset

This mimics how Bambu Studio handles preset updates.

Delete Preset

DELETE /v1/iot-service/api/slicer/setting/{preset_id}

Response:

{
    "message": "success",
    "code": null,
    "error": null
}

Related Endpoints

Slicer Resources

GET /v1/iot-service/api/slicer/resource?slicer/plugins/cloud={version}
GET /v1/iot-service/api/slicer/resource?slicer/printer/bbl={version}
GET /v1/iot-service/api/slicer/resource?policy/privacy={version}

User Print Status

GET /v1/iot-service/api/user/print?force=true

User Tasks

GET /v1/user-service/my/tasks?limit=5&offset=0&status=0

MQTT Certificate

GET /v1/iot-service/api/user/applications/{app_id}/cert?aes256={encrypted_key}

Notes

  1. Delta Storage: Presets only store modified values from the parent, using the inherits field to reference the base preset.

  2. Version Tracking: The updated_time field (Unix timestamp) is used for sync conflict resolution.

  3. Gcode Escaping: Gcode fields use \\n for newlines within JSON strings.

  4. Multi-value Fields: Some fields like nozzle_temperature contain comma-separated values for different conditions.

  5. Authentication: The access token can be obtained via Bambu Lab OAuth flow or the /v1/user-service/user/ticket/{code} endpoint.