DocsHome AssistantOpen the appDE

spooly.eu/docs/quickstart

Quickstart

From key to first call in five minutes. You need a terminal with curl, or Python with requests, or Node.js 18 or later. Save the JavaScript examples as test.mjs and run them with node test.mjs.

Open as text
On this page

1. Check access

The API is part of Spooly Pro, the trial counts. During the beta I enable accounts one by one.

BetaWrite me a short note about what you want to build. I will get back to you once your account is enabled.Or write to support@spooly.eu
Request access

2. Create a key

  1. Open Spooly in the browser: Settings, Devices & keys, “Create key”. This does not work in the apps. “Devices & keys” exists only in the new design. If you still have the old one, switch it to “New design (beta)” under Settings, Appearance & language.
  2. Give it a name and pick the type “Other”. For step 5, turn on “May also change”.
  3. Copy the key. Spooly shows it only once. If you lose it, create a new one.

Store it as an environment variable. All examples in this doc read it from there, so it does not end up in your code.

Terminal (macOS, Linux)
export SPOOLY_KEY="spk_dein_schluessel"
PowerShell (Windows)
$env:SPOOLY_KEY="spk_dein_schluessel"

3. First call

GET /me shows the account type, today’s calls and the name of the key.

On Windows, in PowerShell, write curl.exe instead of curl (curl calls a different command there), $env:SPOOLY_KEY instead of $SPOOLY_KEY, and put the whole request on one line, without \ at the line end. For the change in step 5, Python or JavaScript is the better choice on Windows.

If you get 401 invalid_key, the key is wrong. 403 api_disabled means your account is not enabled yet. All error codes

curl "https://spooly.eu/api/v1/me" \
  -H "Authorization: Bearer $SPOOLY_KEY"
Response 200
{
  "account": "pro",
  "calls_today": 142,
  "daily_limit": 10000,
  "key_name": "Werkstatt",
  "key_kind": "other",
  "account_id": "3f9a1c7e5b2d8a40c6e1f7b2",
  "currency": "EUR"
}

4. Read spools

Lists come in pages. total gives the overall count, and with limit and offset you page on.

To change anything you need the id of the spool, not its number.

curl "https://spooly.eu/api/v1/spools?limit=5" \
  -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": 5,
  "offset": 0
}

5. Set a weight

This needs a key with “May also change”.

Send your own Idempotency-Key. If the connection drops and your program retries, the change still runs only once. Use a new key for each change, for example a UUID.

Afterwards the change appears in the change list of the key, where you can undo it.

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: 4b8e1f0a-6c2d-4e97-9a35-c1d7f2e60b84" \
  -d '{"grams":300}'
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"
}

Where to go next