spooly.eu/docs/api/spools

Spulen

Spulen lesen, anlegen, ändern, wiegen, nachfüllen, archivieren und umlagern. Endgültig löschen geht nicht.

Auf dieser Seite

Spulen auflisten

GET/spools

Sortiert nach Spulennummer. fill_level folgt den Warnschwellen des Kontos wie in der App: low, crit oder null. Jedes Feld, das du schreiben kannst, heißt beim Lesen gleich. Nur lesbar sind id, number, title (Anzeigename wie in der App), fill_level, location (Ort als Text wie in der App) und archived. material ist die Sorte mit Variante wie in der App, z. B. PLA Basic. color_hex trägt bei mehrfarbigen Spulen mehrere Farben, getrennt mit „; “.

Parameter

limitAbfrage, optional: 1 bis 500, Standard 100
offsetAbfrage, optional: 0 bis 1.000.000, Standard 0
archivedAbfrage, optional: false: aktive Spulen (Standard), true: archivierte

curl "https://spooly.eu/api/v1/spools?limit=100" \
  -H "Authorization: Bearer $SPOOLY_KEY"

Antwort 200

{
  "items": [
    {
      "id": "7f3c2a10-5e1b-4c8e-9a44-2d6b1f0c7e21",
      "number": 1,
      "title": "Jade White",
      "name": null,
      "manufacturer": "Bambu Lab",
      "material": "PLA Matte",
      "finish": "matt",
      "color_hex": "#E8E9DF",
      "color_name": "Jade White",
      "remaining_grams": 342,
      "spool_size_grams": 1000,
      "empty_spool_grams": 250,
      "fill_level": "low",
      "location": "Schrank 01 · Fach vorne · Platz 3",
      "location_id": "loc_3c9b7e1a5d60",
      "place": 3,
      "archived": false,
      "price": 19.99,
      "notes": null
    }
  ],
  "total": 23,
  "limit": 100,
  "offset": 0
}

Eine Spule abrufen

GET/spools/{spool_id}

Parameter

spool_idPfad: Die id der Spule, nicht ihre Nummer

curl "https://spooly.eu/api/v1/spools/7f3c2a10-5e1b-4c8e-9a44-2d6b1f0c7e21" \
  -H "Authorization: Bearer $SPOOLY_KEY"

Antwort 200

{
  "id": "7f3c2a10-5e1b-4c8e-9a44-2d6b1f0c7e21",
  "number": 1,
  "title": "Jade White",
  "name": null,
  "manufacturer": "Bambu Lab",
  "material": "PLA Matte",
  "finish": "matt",
  "color_hex": "#E8E9DF",
  "color_name": "Jade White",
  "remaining_grams": 342,
  "spool_size_grams": 1000,
  "empty_spool_grams": 250,
  "fill_level": "low",
  "location": "Schrank 01 · Fach vorne · Platz 3",
  "location_id": "loc_3c9b7e1a5d60",
  "place": 3,
  "archived": false,
  "price": 19.99,
  "notes": null
}

Spule anlegen

POST/spools

Antwortet mit 201. Ohne remaining_grams ist die Spule voll.

Parameter

color_hexBody: #RRGGBB
materialBody: 1 bis 40 Zeichen, die Sorte mit Variante wie in der App, z. B. PLA Basic, PLA+ oder PETG HF
spool_size_gramsBody: Über 0 bis 20.000 g
nameBody, optional: Bis 80 Zeichen
color_nameBody, optional: Bis 60 Zeichen
manufacturerBody, optional: Bis 60 Zeichen
finishBody, optional: matt, shiny, satin, silk, metallic, transparent, glow_in_dark, sparkle, marble, wood oder rainbow
remaining_gramsBody, optional: 0 bis 20.000 g, nicht mehr als die Spule
empty_spool_gramsBody, optional: Tara, 0 bis 2.000 g
priceBody, optional: 0 bis 100.000
notesBody, optional: Bis 1.000 Zeichen
location_idBody, optional: Kennung aus GET /locations
placeBody, optional: Platz im Lagerort, 1 bis places, nur mit location_id
Idempotency-KeyKopf, optional: 1 bis 128 sichtbare ASCII-Zeichen. Idempotency-Key

curl -X POST "https://spooly.eu/api/v1/spools" \
  -H "Authorization: Bearer $SPOOLY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: neu-petg-0001" \
  -d '{"color_hex":"#1B1B1D","material":"PETG HF","spool_size_grams":1000,"color_name":"Black"}'

Antwort 201

{
  "change_id": 381,
  "spool": {
    "id": "2c9e5a71-0d4b-4e3f-b862-91a7c4d0e5f3",
    "number": 24,
    "title": "Black",
    "name": null,
    "manufacturer": null,
    "material": "PETG HF",
    "finish": null,
    "color_hex": "#1B1B1D",
    "color_name": "Black",
    "remaining_grams": 1000,
    "spool_size_grams": 1000,
    "empty_spool_grams": null,
    "fill_level": null,
    "location": null,
    "location_id": null,
    "place": null,
    "archived": false,
    "price": null,
    "notes": null
  },
  "slot": null,
  "old_grams": null,
  "new_grams": null,
  "replayed": false,
  "task": null,
  "printer": null,
  "stock_empty": null,
  "summary": "Spule #24 Black angelegt"
}

Spule ändern

PATCH/spools/{spool_id}

Nur die mitgeschickten Felder, mindestens eines. Unbekannte Felder ergeben 422. color_hex, material und spool_size_grams dürfen nicht null sein, die übrigen leerst du mit null. place null nimmt nur den Platz weg. Das Gewicht läuft über /weight und /refill.

Parameter

spool_idPfad: Die id der Spule, nicht ihre Nummer
name, color_hex, color_name, material, manufacturer, finish, spool_size_grams, empty_spool_grams, price, notes, location_id, placeBody, optional: Regeln wie beim Anlegen
Idempotency-KeyKopf, optional: 1 bis 128 sichtbare ASCII-Zeichen. Idempotency-Key

curl -X PATCH "https://spooly.eu/api/v1/spools/7f3c2a10-5e1b-4c8e-9a44-2d6b1f0c7e21" \
  -H "Authorization: Bearer $SPOOLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notes":"Trocknen vor dem Druck"}'

Antwort 200

{
  "change_id": 381,
  "spool": {
    "id": "7f3c2a10-5e1b-4c8e-9a44-2d6b1f0c7e21",
    "number": 1,
    "title": "Jade White",
    "name": null,
    "manufacturer": "Bambu Lab",
    "material": "PLA Matte",
    "finish": "matt",
    "color_hex": "#E8E9DF",
    "color_name": "Jade White",
    "remaining_grams": 342,
    "spool_size_grams": 1000,
    "empty_spool_grams": 250,
    "fill_level": "low",
    "location": "Schrank 01 · Fach vorne · Platz 3",
    "location_id": "loc_3c9b7e1a5d60",
    "place": 3,
    "archived": false,
    "price": 19.99,
    "notes": null
  },
  "slot": null,
  "old_grams": null,
  "new_grams": null,
  "replayed": false,
  "task": null,
  "printer": null,
  "stock_empty": null,
  "summary": "Spule #1 Jade White bearbeitet"
}

Restgewicht setzen

POST/spools/{spool_id}/weight

Genau eines der beiden Gewichte. 0 g archiviert die Spule, wie in der App.

Parameter

spool_idPfad: Die id der Spule, nicht ihre Nummer
gramsBody, optional: 0 bis 20.000 g, nur das Filament
gross_gramsBody, optional: 0 bis 40.000 g, Spule mit Tara. Die Tara muss bekannt sein.
Idempotency-KeyKopf, optional: 1 bis 128 sichtbare ASCII-Zeichen. Idempotency-Key

curl -X POST "https://spooly.eu/api/v1/spools/7f3c2a10-5e1b-4c8e-9a44-2d6b1f0c7e21/weight" \
  -H "Authorization: Bearer $SPOOLY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: waage-2026-11-01-0815" \
  -d '{"gross_grams":542}'

Antwort 200

{
  "change_id": 381,
  "spool": {
    "id": "7f3c2a10-5e1b-4c8e-9a44-2d6b1f0c7e21",
    "number": 1,
    "title": "Jade White",
    "name": null,
    "manufacturer": "Bambu Lab",
    "material": "PLA Matte",
    "finish": "matt",
    "color_hex": "#E8E9DF",
    "color_name": "Jade White",
    "remaining_grams": 300,
    "spool_size_grams": 1000,
    "empty_spool_grams": 250,
    "fill_level": "low",
    "location": "Schrank 01 · Fach vorne · Platz 3",
    "location_id": "loc_3c9b7e1a5d60",
    "place": 3,
    "archived": false,
    "price": 19.99,
    "notes": null
  },
  "slot": null,
  "old_grams": 342,
  "new_grams": 300,
  "replayed": false,
  "task": null,
  "printer": null,
  "stock_empty": null,
  "summary": "Spule #1 Jade White: 342 auf 300 g"
}

Nachfüllen

POST/spools/{spool_id}/refill

Addiert Gramm. Das Ergebnis darf nicht über der Spulengröße liegen.

Parameter

spool_idPfad: Die id der Spule, nicht ihre Nummer
gramsBody: Über 0 bis 20.000 g
Idempotency-KeyKopf, optional: 1 bis 128 sichtbare ASCII-Zeichen. Idempotency-Key

curl -X POST "https://spooly.eu/api/v1/spools/7f3c2a10-5e1b-4c8e-9a44-2d6b1f0c7e21/refill" \
  -H "Authorization: Bearer $SPOOLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"grams":250}'

Antwort 200

{
  "change_id": 381,
  "spool": {
    "id": "7f3c2a10-5e1b-4c8e-9a44-2d6b1f0c7e21",
    "number": 1,
    "title": "Jade White",
    "name": null,
    "manufacturer": "Bambu Lab",
    "material": "PLA Matte",
    "finish": "matt",
    "color_hex": "#E8E9DF",
    "color_name": "Jade White",
    "remaining_grams": 592,
    "spool_size_grams": 1000,
    "empty_spool_grams": 250,
    "fill_level": null,
    "location": "Schrank 01 · Fach vorne · Platz 3",
    "location_id": "loc_3c9b7e1a5d60",
    "place": 3,
    "archived": false,
    "price": 19.99,
    "notes": null
  },
  "slot": null,
  "old_grams": 342,
  "new_grams": 592,
  "replayed": false,
  "task": null,
  "printer": null,
  "stock_empty": null,
  "summary": "Spule #1 Jade White: 342 auf 592 g"
}

Archivieren

POST/spools/{spool_id}/archive

Die Spule verlässt den aktiven Bestand, ihr Druckverlauf bleibt. Während eines laufenden Drucks geht das nicht. Die API antwortet dann mit 409 spool_in_print.

Parameter

spool_idPfad: Die id der Spule, nicht ihre Nummer
Idempotency-KeyKopf, optional: 1 bis 128 sichtbare ASCII-Zeichen. Idempotency-Key

curl -X POST "https://spooly.eu/api/v1/spools/7f3c2a10-5e1b-4c8e-9a44-2d6b1f0c7e21/archive" \
  -H "Authorization: Bearer $SPOOLY_KEY"

Antwort 200

{
  "change_id": 381,
  "spool": {
    "id": "7f3c2a10-5e1b-4c8e-9a44-2d6b1f0c7e21",
    "number": 1,
    "title": "Jade White",
    "name": null,
    "manufacturer": "Bambu Lab",
    "material": "PLA Matte",
    "finish": "matt",
    "color_hex": "#E8E9DF",
    "color_name": "Jade White",
    "remaining_grams": 342,
    "spool_size_grams": 1000,
    "empty_spool_grams": 250,
    "fill_level": "low",
    "location": "Schrank 01 · Fach vorne · Platz 3",
    "location_id": "loc_3c9b7e1a5d60",
    "place": 3,
    "archived": true,
    "price": 19.99,
    "notes": null
  },
  "slot": null,
  "old_grams": null,
  "new_grams": null,
  "replayed": false,
  "task": null,
  "printer": null,
  "stock_empty": null,
  "summary": "Spule #1 Jade White archiviert"
}

Zurückholen

POST/spools/{spool_id}/restore

Holt eine archivierte Spule zurück in den aktiven Bestand.

Parameter

spool_idPfad: Die id der Spule, nicht ihre Nummer
Idempotency-KeyKopf, optional: 1 bis 128 sichtbare ASCII-Zeichen. Idempotency-Key

curl -X POST "https://spooly.eu/api/v1/spools/7f3c2a10-5e1b-4c8e-9a44-2d6b1f0c7e21/restore" \
  -H "Authorization: Bearer $SPOOLY_KEY"

Antwort 200

{
  "change_id": 381,
  "spool": {
    "id": "7f3c2a10-5e1b-4c8e-9a44-2d6b1f0c7e21",
    "number": 1,
    "title": "Jade White",
    "name": null,
    "manufacturer": "Bambu Lab",
    "material": "PLA Matte",
    "finish": "matt",
    "color_hex": "#E8E9DF",
    "color_name": "Jade White",
    "remaining_grams": 342,
    "spool_size_grams": 1000,
    "empty_spool_grams": 250,
    "fill_level": "low",
    "location": "Schrank 01 · Fach vorne · Platz 3",
    "location_id": "loc_3c9b7e1a5d60",
    "place": 3,
    "archived": false,
    "price": 19.99,
    "notes": null
  },
  "slot": null,
  "old_grams": null,
  "new_grams": null,
  "replayed": false,
  "task": null,
  "printer": null,
  "stock_empty": null,
  "summary": "Spule #1 Jade White zurückgeholt"
}

Umlagern

POST/spools/{spool_id}/move

Das Ziel kommt aus GET /locations. location_id null nimmt die Spule aus dem Ort. Mit place liegt sie auf diesem Platz, ohne place liegt sie im Ort ohne Platz.

Parameter

spool_idPfad: Die id der Spule, nicht ihre Nummer
location_idBody: Kennung des Lagerorts oder null
placeBody, optional: Platznummer von 1 bis places des Lagerorts. Ist der Platz belegt, kommt 409 place_taken.
Idempotency-KeyKopf, optional: 1 bis 128 sichtbare ASCII-Zeichen. Idempotency-Key

curl -X POST "https://spooly.eu/api/v1/spools/7f3c2a10-5e1b-4c8e-9a44-2d6b1f0c7e21/move" \
  -H "Authorization: Bearer $SPOOLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"location_id":"loc_3c9b7e1a5d60","place":3}'

Antwort 200

{
  "change_id": 381,
  "spool": {
    "id": "7f3c2a10-5e1b-4c8e-9a44-2d6b1f0c7e21",
    "number": 1,
    "title": "Jade White",
    "name": null,
    "manufacturer": "Bambu Lab",
    "material": "PLA Matte",
    "finish": "matt",
    "color_hex": "#E8E9DF",
    "color_name": "Jade White",
    "remaining_grams": 342,
    "spool_size_grams": 1000,
    "empty_spool_grams": 250,
    "fill_level": "low",
    "location": "Schrank 01 · Fach vorne · Platz 3",
    "location_id": "loc_3c9b7e1a5d60",
    "place": 3,
    "archived": false,
    "price": 19.99,
    "notes": null
  },
  "slot": null,
  "old_grams": null,
  "new_grams": null,
  "replayed": false,
  "task": null,
  "printer": null,
  "stock_empty": null,
  "summary": "Spule #1 Jade White umgelagert"
}