Skip to content

Spoolman Integration

Jump to bottom
Björn Strausmann edited this page May 10, 2026 · 1 revision

Spoolman Integration

Print 3D-printer filament spool labels from Spoolman.

Status: design specification. Implementation tracked in issue #16.

How it works — pull only

Spoolman does not offer outbound webhooks for spool events. Integration is therefore pull-mode only — you operate from inside the hub UI:

  1. Open the hub (e.g. on your phone)
  2. Switch to the Spoolman tab on a printer
  3. Search for a spool by ID, name, vendor, material, or partial match — the hub queries Spoolman's REST API
  4. Pick the spool from the results
  5. Choose a layout from the dropdown (see layouts below) and the tape size if not auto-set
  6. Hit Print → label prints
You / phone                  Hub                          Spoolman
─────────────                ─────                        ─────────
1. Open hub UI         ─────►
2. Switch to Spoolman tab
3. Search "PLA black"  ─────► /api/lookup/spoolman/search?q=PLA+black
                                                  ─────► GET /api/v1/spool?filament_name=PLA…
                                                  ◄───── matching spools
                              ◄────── search results
4. Click the spool       ─────► /api/lookup/spoolman/<id>
                                                  ─────► GET /api/v1/spool/<id>
                                                  ◄───── full spool detail
                              ◄────── LabelData
5. Choose layout
   Click Print          ─────► /api/print/<printer>?layout_id=<id>
                              ──► PrintQueue worker → printer
                              ◄── live status via SSE

There is no automatic / triggered printing in Spoolman integration. If you need that, file a feature request in Spoolman upstream — the hub would happily consume a webhook if Spoolman adds one.

Layouts

Per ADR 0012, every label has a layout — a saved recipe describing what the printed label looks like. You can:

  • Use a seeded default (e.g. spoolman-spool-12mm)
  • Save your own custom layout for Spoolman (e.g. "vendor + material + colour swatch + remaining weight")
  • Pick which layout to use for each print job
  • Set a different default per (integration, tape_mm) combination

Available Spoolman fields you can put on a layout (extends as Spoolman API evolves):

Field path Example value
title "PLA Black" (resolved from filament.name)
primary_id "42" (the spool ID)
qr_payload https://<your-host>/spool/42
secondary[0] filament material, e.g. "PLA"
secondary[1] filament vendor, e.g. "Polymaker"
extras.weight initial spool weight in g
extras.remaining_weight current remaining weight in g
extras.color_hex filament colour as hex code (for colour swatch element)
extras.first_used first-use date

Seed layouts shipped:

  • spoolman-spool-12mm (default for 12mm tape) — QR + name + material
  • spoolman-spool-with-vendor-24mm (default for 24mm tape) — QR + name + material + vendor + remaining weight

Create your own via POST /api/layouts — see the API reference at /redoc on a running hub.

Setup

If your Spoolman is open (default), no credential setup is needed.

Hub .env:

SPOOLMAN_URL=https://spoolman.example.com
# Optional, only if your Spoolman has authentication enabled
# SPOOLMAN_API_TOKEN=<your-token>

Restart the backend container:

docker compose restart backend

Verify

Open the hub UI → switch to the Spoolman tab → type part of a spool name → matching results appear in 1-2 s.

Limitations

  • Pull-only — no auto-print on spool changes (Spoolman doesn't support outbound webhooks)
  • Bulk print of multiple spools — out of scope for MVP. Possible future feature if requested
  • The hub doesn't write back to Spoolman (no "marked as labelled" status). Read-only by design.
  • Real-time spool inventory (Spoolman's running-out alerts) is out of scope — that's Spoolman's domain

Troubleshooting

Symptom Likely cause Fix
Spoolman tab empty Hub can't reach SPOOLMAN_URL From the backend container: curl -fI $SPOOLMAN_URL
401 from Spoolman API token expired or wrong Set or refresh SPOOLMAN_API_TOKEN
Search times out Spoolman API slow / large dataset Add filter terms; check Spoolman performance
Hub UI shows spool but printer fails Tape size mismatch or printer offline Check printer status page
Print runs but label looks wrong Layout chosen doesn't fit the data shape Pick a different layout, or create a custom one tailored to your fields

See also

Label Printer Hub

Getting Started

Integrations

Workflows

Help

Repo

Clone this wiki locally