DokuHome AssistantZur AppEN

spooly.eu/docs/quickstart

Schnellstart

Vom Schlüssel zum ersten Aufruf in fünf Minuten. Du brauchst ein Terminal mit curl, oder Python mit requests, oder Node.js ab Version 18. Die JavaScript-Beispiele speicherst du als test.mjs und startest sie mit node test.mjs.

Als Text öffnen
Auf dieser Seite

1. Zugang prüfen

Die API gehört zu Spooly Pro, der Trial zählt mit. In der Beta schalte ich Konten einzeln frei.

BetaSchreib mir kurz, was du bauen willst. Ich melde mich, sobald dein Konto frei ist.Oder schreib an support@spooly.eu
Zugang anfragen

2. Schlüssel anlegen

  1. Öffne Spooly im Browser: Einstellungen, Geräte & Schlüssel, „Schlüssel anlegen“. In den Apps geht das nicht. „Geräte & Schlüssel“ gibt es nur im neuen Design. Hast du noch das alte, schaltest du es unter Einstellungen, Darstellung & Sprache auf „Neues Design (Beta)“ um.
  2. Gib ihm einen Namen und wähl die Art „Sonstiges“. Für Schritt 5 schaltest du „Darf auch ändern“ ein.
  3. Kopier den Schlüssel. Spooly zeigt ihn nur dieses eine Mal. Verloren heißt neu anlegen.

Leg ihn als Umgebungsvariable ab. Alle Beispiele dieser Doku lesen ihn von dort, so landet er nicht im Code.

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

3. Erster Aufruf

GET /me zeigt Kontoart, Aufrufe von heute und den Namen des Schlüssels.

Unter Windows schreibst du in der PowerShell curl.exe statt curl (curl ruft dort einen anderen Befehl auf), $env:SPOOLY_KEY statt $SPOOLY_KEY und die ganze Anfrage in eine Zeile, ohne \ am Zeilenende. Für die Änderung in Schritt 5 nimmst du unter Windows besser Python oder JavaScript.

Kommt 401 invalid_key, stimmt der Schlüssel nicht. 403 api_disabled heißt, dein Konto ist noch nicht freigeschaltet. Alle Fehlercodes

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

4. Spulen lesen

Listen kommen seitenweise. total nennt die Gesamtzahl, mit limit und offset blätterst du weiter.

Für Änderungen brauchst du die id der Spule, nicht ihre Nummer.

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

5. Ein Gewicht setzen

Das braucht einen Schlüssel mit „Darf auch ändern“.

Schick einen eigenen Idempotency-Key mit. Bricht die Verbindung ab und dein Programm wiederholt, läuft die Änderung trotzdem nur einmal. Je Änderung ein neuer Key, zum Beispiel eine UUID.

Die Änderung steht danach in der Änderungsliste des Schlüssels, dort kannst du sie zurücknehmen.

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

Wie es weitergeht