spooly.eu/docs/api/spools

Spools

Read, create, update, weigh, refill, archive and move spools. Permanent deletion is not possible.

On this page

List spools

GET/spools

Sorted by spool number. fill_level follows the warning thresholds of the account, as in the app: low, crit or null. Every field you can write has the same name when you read it. Read only: id, number, title (display name as in the app), fill_level, location (location as text, as in the app) and archived. material is the material with its variant as in the app, such as PLA Basic. For multicolor spools color_hex holds several colors separated by “; ”.

Parameters

limitQuery, optional: 1 to 500, default 100
offsetQuery, optional: 0 to 1,000,000, default 0
archivedQuery, optional: false: active spools (default), true: archived

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

Response 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
}

Get one spool

GET/spools/{spool_id}

Parameters

spool_idPath: The id of the spool, not its number

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

Response 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
}

Create a spool

POST/spools

Responds with 201. Without remaining_grams the spool is full.

Parameters

color_hexBody: #RRGGBB
materialBody: 1 to 40 characters, the material with its variant as in the app, such as PLA Basic, PLA+ or PETG HF
spool_size_gramsBody: Above 0 up to 20,000 g
nameBody, optional: Up to 80 characters
color_nameBody, optional: Up to 60 characters
manufacturerBody, optional: Up to 60 characters
finishBody, optional: matt, shiny, satin, silk, metallic, transparent, glow_in_dark, sparkle, marble, wood or rainbow
remaining_gramsBody, optional: 0 to 20,000 g, not more than the spool holds
empty_spool_gramsBody, optional: Tare, 0 to 2,000 g
priceBody, optional: 0 to 100,000
notesBody, optional: Up to 1,000 characters
location_idBody, optional: Identifier from GET /locations
placeBody, optional: Place in the location, 1 to places, only with location_id
Idempotency-KeyHeader, optional: 1 to 128 visible ASCII characters. 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"}'

Response 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"
}

Update a spool

PATCH/spools/{spool_id}

Only the fields you send, at least one. Unknown fields return 422. color_hex, material and spool_size_grams cannot be null, you clear the others with null. A place of null only removes the place. Weight goes through /weight and /refill.

Parameters

spool_idPath: The id of the spool, not its number
name, color_hex, color_name, material, manufacturer, finish, spool_size_grams, empty_spool_grams, price, notes, location_id, placeBody, optional: Same rules as when creating
Idempotency-KeyHeader, optional: 1 to 128 visible ASCII characters. 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"}'

Response 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"
}

Set remaining weight

POST/spools/{spool_id}/weight

Exactly one of the two weights. 0 g archives the spool, as in the app.

Parameters

spool_idPath: The id of the spool, not its number
gramsBody, optional: 0 to 20,000 g, the filament only
gross_gramsBody, optional: 0 to 40,000 g, spool including tare. The tare must be known.
Idempotency-KeyHeader, optional: 1 to 128 visible ASCII characters. 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}'

Response 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"
}

Refill

POST/spools/{spool_id}/refill

Adds grams. The result cannot exceed the spool size.

Parameters

spool_idPath: The id of the spool, not its number
gramsBody: Above 0 up to 20,000 g
Idempotency-KeyHeader, optional: 1 to 128 visible ASCII characters. 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}'

Response 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"
}

Restore

POST/spools/{spool_id}/restore

Brings an archived spool back into the active stock.

Parameters

spool_idPath: The id of the spool, not its number
Idempotency-KeyHeader, optional: 1 to 128 visible ASCII characters. Idempotency-Key

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

Response 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"
}

Move

POST/spools/{spool_id}/move

The destination comes from GET /locations. A location_id of null takes the spool out of its location. With place it goes onto that place, without place it sits in the location without a place.

Parameters

spool_idPath: The id of the spool, not its number
location_idBody: Identifier of the location, or null
placeBody, optional: Place number from 1 to places of the location. If the place is taken, you get 409 place_taken.
Idempotency-KeyHeader, optional: 1 to 128 visible ASCII characters. 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}'

Response 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"
}