Grotti HTTP-API (`/api/v1`)

Stand für Android/App-Clients und Integrationen. Nutzer-Anleitungen bleiben unter docs/Anleitung-*.md.

Auth

Weg	Header / Cookie	CSRF
Session	Cookie nach `POST /auth/login`	`X-CSRF-Token` bei mutierenden API-Calls
Bearer	`Authorization: Bearer grt_…`	nicht nötig

Token ausstellen

Eingeloggt: POST /tokens {name, role?} → Klartext einmalig in token
Ohne Session (App): POST /auth/token {username, password, device_name?, role?} → 201 mit token + user (Rate-Limit wie Login)

Öffentlich ohne Login: /auth/status, /auth/login, /auth/token, /auth/setup, /version.

Rollen: operator ≤ admin. Admin-only u. a. Benutzer, Backup, volle Einstellungen, Drucker anlegen.

Medien mit Query-Token (nur GET): ?token=grt_… für Kamera, Live-Vorschau, Datei-Vorschau (/dateien/<id>/vorschau), Projekt-Assets.

Fehler

{"error": "Text", "code": "kurzcode"}

HTTP-Status: 400/401/403/404/409/429/503. Bild-Endpunkte liefern bei fehlendem Bild ebenfalls dieses JSON (nicht nur leeren 404).

Pagination

Listen akzeptieren limit / offset wo sinnvoll. Antwort bleibt ein JSON-Array; Gesamtzahl im Header X-Total-Count.

Ohne limit liefern /dateien und /spulen die volle Liste (Web-UI).

Bestätigung

Mutierende Druckaktionen brauchen oft "confirm": true:

POST /senden, POST /druck-queue, POST /ablauf
POST /projekte/<id>/einreihen, POST /auftraege/<id>/einreihen
POST /drucker/<host>/abraeumen
steuern mit emergency_stop, clear_error, exclude_object

Server-Info

GET /version → {name, version, api: 1, features: [...]}.

SSE Live

GET /stream (Session-Cookie oder Bearer). Events:

Event	Bedeutung
`ping`	Keepalive (~15 s), Payload `{}`
`drucker`	Live-Zustand der Drucker geändert
`queue`	Druckwarteschlange geändert
`senden`	Sende-Auftrag geändert
`ereignis`	Neues Ereignis / Aktivität
`aufgaben`	Offene Aufgaben (Platte …)

Ohne Stream: Client pollt /drucker?live=1, /jetzt, /druck-queue.

Push an Geräte

Grotti sendet kein FCM. Empfohlen: ntfy (Topic unter Einstellungen). Die App kann denselben Topic abonnieren; Secrets (ntfy-Token) bleiben serverseitig.

Wichtige Ressourcen

Bereich	Pfade
Drucker	`GET /drucker?live=1`, `POST /drucker/<host>/pause\|fortsetzen\|abbrechen` (Alias `resume`/`cancel`), `…/steuern`, `…/abraeumen`
Dateien	`GET /dateien?family=&material=&project_id=&host=&q=&limit=&offset=`, Upload multipart, `…/vorschau`, `…/pfad`
Senden / Queue	`POST /senden`, `GET /senden-zuletzt?host=&file_id=`, `GET\|POST /druck-queue?host=&status=`, `POST /ablauf`
Projekte	`GET\|POST /projekte`, `GET /projekte/<id>`, `…/laeufe`, `POST …/einreihen`, Assets
Aufträge	`GET\|POST /auftraege`, Positionen, `…/einreihen`
Material	`GET /spulen?aktiv=1`, Akte, Einlegen
Protokoll	`GET /laeufe`, `GET /laeufe/<id>`, `GET /statistik?project_id=`
Kamera	`GET /kamera?host=`, `…/stream`

Pfadnamen sind überwiegend deutsch. Aktionen: deutsch + englische Alias für Pause/Resume/Cancel.

MCP

python -m grotti.mcp_server nutzt dieselbe REST-API (Teilmenge). Siehe docs/internal/MCP.md.

3.3 KiB Raw Permalink Blame History

Grotti HTTP-API (/api/v1)