spooly.eu/docs/api

API-Referenz

Mit der REST-API liest du Spulen, Slots, Drucke, Wartung und Statistik deines eigenen Kontos und änderst sie. Alles kommt als JSON, nur der Tabellen-Link als CSV. Zahlungs- und Kundendaten liefert sie nicht, und Drucker lässt sie nicht steuern.

Als Text öffnen

Auf dieser Seite

Basis-URL und Anmeldung

Jede Anfrage geht an die Basis-URL und trägt einen Schlüssel im Kopf. Wie du ihn anlegst, steht unter Schlüssel und Anmeldung.

Die Beispiele lesen den Schlüssel aus der Umgebungsvariable SPOOLY_KEY.

Basis-URL

https://spooly.eu/api/v1

Kopf

Authorization: Bearer spk_dein_schluessel

Formate

Anfragen und Antworten sind JSON in UTF-8.
Zeitpunkte kommen als ISO 8601 in UTC, zum Beispiel 2026-10-30T14:02:00Z.
Gewichte sind in Gramm, Geld in der Währung des Kontos (currency aus GET /me).
Kennungen sind Zeichenketten. Lies nichts aus ihrem Aufbau heraus, er unterscheidet sich je Sache.
Fehlt ein Wert, steht null da.

Seitenweise Listen

Spulen, Drucke und der Wartungsverlauf kommen seitenweise. total nennt die Gesamtzahl. Erhöh offset um limit, bis du total erreichst.

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

Antwort 200

{
  "items": [
    "…"
  ],
  "total": 230,
  "limit": 100,
  "offset": 100
}

Antwort auf Änderungen

Jede Änderung antwortet im selben Format. change_id ist ihr Eintrag in der Änderungsliste der Verbindung, summary ein Satz für Menschen. Dazu kommt, was sich geändert hat: spool, slot, task oder printer, beim Gewicht old_grams und new_grams.

Zurücknehmen kannst du Gewicht, Slots und erledigte Wartung in der App, über die API geht das nicht.

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

Idempotency-Key

Schick bei jeder Änderung einen eigenen Idempotency-Key mit, wenn dein Programm nach einem Abbruch wiederholt. Derselbe Schlüssel mit demselben Inhalt läuft nur einmal. Die Antwort des ersten Aufrufs kommt dann noch einmal, mit replayed auf true.

Derselbe Schlüssel mit anderem Inhalt ergibt 422 idempotency_conflict. Nimm deshalb je Änderung einen neuen Key, zum Beispiel eine UUID. Erlaubt sind 1 bis 128 sichtbare ASCII-Zeichen.

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: 9e3c7a52-1d48-4b6f-8e0a-52f7b3c1d96e" \
  -d '{"gross_grams":742}'

OpenAPI-Schema

Das Schema beschreibt alle Endpunkte, Parameter und Antworten maschinenlesbar. Damit erzeugst du einen Client für deine Sprache oder gibst deiner KI die genaue Beschreibung.

OpenAPI-Schema herunterladen

/api/v1/openapi.json

Was die API nicht liefert

Kunden- und Firmendaten aus Aufträgen.
Zugangsdaten zu Druckern und Konten.
Zahlungsdaten.
Endgültiges Löschen. Archivieren und Zurückholen gehen.
Drucker steuern.
Dein Konto und dein Abo.

Antworten enthalten nur Felder aus einer festen Liste. Eine neue Spalte in der Datenbank erscheint nie von selbst in der API. Für KI-Assistenten gibt es dieselben Daten über MCP.