Source: https://spooly.eu/en/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`.

## 1. Check access

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

> Beta: Write 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.

## 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](https://spooly.eu/en/docs/errors)

```bash
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.

```bash
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.

```bash
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

- [API reference](https://spooly.eu/en/docs/api): All 24 endpoints with parameters and examples.
- [Error codes](https://spooly.eu/en/docs/errors): What each code means and what your program should do.
- [Limits](https://spooly.eu/en/docs/limits): Calls per day, simultaneous requests and changes.