Alles, was die Web-App und die Apps tun, läuft über die HTTP-API von ZiiX.TV, und du kannst sie auch nutzen: für Skripte, Hausautomation oder einen eigenen Client.
Die Dokumentation liegt auf deinem Server
Jeder Server hat seine vollständige API-Referenz unter http://<your server>:8470/docs, mit Suche, Beispielen und einem Download der OpenAPI-Spezifikation. Sie wird aus derselben Spezifikation erzeugt wie der Server selbst und passt daher immer zu deiner Version. Der Link steht in der Fußzeile der Web-App.
Anmelden
Alle Anfragen gehen an /api. Melde dich mit Benutzername und Passwort an, um ein Token zu bekommen:
curl -X POST http://nas:8470/api/auth/login \
-H 'Content-Type: application/json' \
-d '{"username":"anna","password":"…"}'
{"user":{"id":1,"username":"anna","isAdmin":true},"token":"…"}
Schick das Token bei jeder Anfrage im Header Authorization mit:
curl http://nas:8470/api/libraries -H 'Authorization: Bearer <token>'
- Ein Token gilt 90 Tage oder bis es mit
POST /api/auth/logoutoder unter Einstellungen → Geräte abgemeldet wird. - Ein Token handelt als sein Benutzer und sieht, was dieser Benutzer sieht. Endpunkte für Einstellungen, Benutzer und Mediatheken brauchen einen Administrator.
- Nimm für ein Skript einen eigenen Benutzer, damit es sich separat abmelden lässt.
Beispiele
# Die Mediatheken und die Titel in Mediathek 2
curl http://nas:8470/api/libraries -H "Authorization: Bearer $TOKEN"
curl http://nas:8470/api/libraries/2/titles -H "Authorization: Bearer $TOKEN"
# Weiterschauen
curl http://nas:8470/api/continue -H "Authorization: Bearer $TOKEN"
# Einen Titel als gesehen markieren
curl -X PUT http://nas:8470/api/titles/12/watched \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"watched":true}'
# Mediathek 2 jetzt scannen (Administratoren)
curl -X POST http://nas:8470/api/libraries/2/scan -H "Authorization: Bearer $TOKEN"
Eine Datei abzuspielen geht in zwei Schritten: POST /api/files/{id}/playback mit dem, was der Client abspielen kann, liefert, wie sie abgespielt wird (direkt, neu verpackt oder umgewandelt), und die Adresse des Streams; PUT /api/files/{id}/progress speichert, wo der Benutzer gerade ist. Die Details stehen in der Referenz.
Live-Events
GET /api/events ist ein WebSocket, der eine kurze JSON-Nachricht sendet, sobald sich etwas ändert, damit ein Client sich aktualisieren kann, ohne immer wieder nachzufragen:
{"type":"titles","libraryId":2}
Die Typen sind libraries (hinzugefügt, entfernt, Scan läuft), titles (neue oder geänderte Titel), metadata, watch (Wiedergabeverlauf) und views.
Fehler
Fehler haben einen stabilen Code für Programme und eine Meldung für Menschen:
{"code":"unauthorized","error":"log in to use this server"}
| Status | Code | Bedeutung |
|---|---|---|
| 401 | unauthorized | Kein Token, oder das Token ist abgelaufen |
| 403 | forbidden | Erfordert einen Administrator |
| 402 | license_required | Testphase oder Lizenz des Servers ist abgelaufen |
| 429 | too_many_attempts | Zu viele fehlgeschlagene Anmeldungen; warte ein paar Minuten |
| 503 | transcode_busy | Der Server wandelt bereits so viele Videos um, wie er darf |
Limits
- Nach zehn fehlgeschlagenen Anmeldungen für einen Benutzer von einer Adresse innerhalb von fünf Minuten werden weitere Versuche eine Zeit lang abgelehnt.
- Anfragen haben einen JSON-Body von höchstens 64 KB.
- Anfragen von anderen Websites im Browser werden abgelehnt; Skripte mit Token sind davon nicht betroffen.
Kompatibilität
Neue Versionen von ZiiX.TV erweitern die API, entfernen oder benennen aber nichts Bestehendes um, damit Skripte und ältere Apps nach einem Update weiter funktionieren.