Quelle: https://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.

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

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.

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

```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: 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](https://spooly.eu/api/v1/openapi.json)

`/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](https://spooly.eu/docs/ai).