spooly.eu/docs/api

API reference

The REST API reads and changes spools, slots, prints, maintenance and statistics of your own account. Everything comes as JSON, only the spreadsheet link returns CSV. It delivers no payment or customer data, and it does not control printers.

Open as text

On this page

Base URL and sign-in

Every request goes to the base URL and carries a key in the header. Keys and sign-in explains how to create one.

The examples read the key from the environment variable SPOOLY_KEY.

Base URL

https://spooly.eu/api/v1

Header

Authorization: Bearer spk_dein_schluessel

Formats

Requests and responses are JSON in UTF-8.
Timestamps are ISO 8601 in UTC, for example 2026-10-30T14:02:00Z.
Weights are in grams, money is in the currency of the account (currency from GET /me).
Identifiers are strings. Treat them as opaque: their format differs by entity.
A missing value is null.

Paginated lists

Spools, prints and the maintenance log come in pages. total gives the full count. Increase offset by limit until you reach total.

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

Response 200

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

Response to changes

Every change responds in the same format. change_id is its entry in the change list of the connection, summary is a sentence for humans. It also carries what changed: spool, slot, task or printer, and for weight old_grams and new_grams.

You can undo weight, slots and completed maintenance in the app, not through the API.

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

Idempotency-Key

Send your own Idempotency-Key with every change if your program retries after an interruption. The same key with the same content runs only once. You then get the response of the first call again, with replayed set to true.

The same key with different content returns 422 idempotency_conflict. So use a new key for each change, for example a UUID. Allowed are 1 to 128 visible ASCII characters.

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

The schema describes all endpoints, parameters and responses in machine-readable form. Use it to generate a client for your language or to give your AI the exact description.

Download the OpenAPI schema

/api/v1/openapi.json

What the API does not deliver

Customer and company data from orders.
Credentials for printers and accounts.
Payment data.
Permanent deletion. Archiving and restoring work.
Controlling printers.
Your account and your subscription.

Responses contain only fields from a fixed list. A new column in the database never shows up in the API on its own. AI assistants get the same data through MCP.