Alt, hvad webappen og apps gør, går gennem ZiiX.TV’s HTTP-API, og du kan også selv bruge det: til scripts, hjemmeautomatisering eller din egen klient.
Dokumentationen ligger på din server
Hver server har sin fulde API-reference på http://<your server>:8470/docs, med søgning, eksempler og download af OpenAPI-specifikationen. Den er lavet ud fra samme specifikation som selve serveren, så den passer altid til din version. Linket står i bunden af webappen.
Log ind
Alle forespørgsler går til /api. Log ind med brugernavn og adgangskode for at få et token:
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":"…"}
Send tokenet i headeren Authorization med hver forespørgsel:
curl http://nas:8470/api/libraries -H 'Authorization: Bearer <token>'
- Et token virker i 90 dage, eller indtil det logges ud med
POST /api/auth/logouteller under Indstillinger → Enheder. - Et token handler som sin bruger og ser det, den bruger ser. Endpoints til indstillinger, brugere og biblioteker kræver en administrator.
- Brug en separat bruger til et script, så det kan logges ud for sig selv.
Eksempler
# Bibliotekerne og titlerne i bibliotek 2
curl http://nas:8470/api/libraries -H "Authorization: Bearer $TOKEN"
curl http://nas:8470/api/libraries/2/titles -H "Authorization: Bearer $TOKEN"
# Fortsæt med at se
curl http://nas:8470/api/continue -H "Authorization: Bearer $TOKEN"
# Markér en titel som set
curl -X PUT http://nas:8470/api/titles/12/watched \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"watched":true}'
# Scan bibliotek 2 nu (administratorer)
curl -X POST http://nas:8470/api/libraries/2/scan -H "Authorization: Bearer $TOKEN"
At afspille en fil sker i to trin: POST /api/files/{id}/playback med det, klienten kan afspille, svarer med, hvordan filen skal afspilles (direkte, pakket om eller omkodet), og adressen på streamen; PUT /api/files/{id}/progress gemmer, hvor brugeren er nået til. Referencen har detaljerne.
Live-hændelser
GET /api/events er en WebSocket, der sender en kort JSON-besked, hver gang noget ændrer sig, så en klient kan opdatere uden at spørge igen og igen:
{"type":"titles","libraryId":2}
Typerne er libraries (tilføjet, fjernet, scanner), titles (nye eller ændrede titler), metadata, watch (historik) og views.
Fejl
Fejl har en fast kode til programmer og en besked til mennesker:
{"code":"unauthorized","error":"log in to use this server"}
| Status | Kode | Betydning |
|---|---|---|
| 401 | unauthorized | Intet token, eller tokenet er udløbet |
| 403 | forbidden | Kræver en administrator |
| 402 | license_required | Serverens prøveperiode eller licens er udløbet |
| 429 | too_many_attempts | For mange mislykkede logins; vent et par minutter |
| 503 | transcode_busy | Serveren omkoder så mange videoer, som den må |
Grænser
- Ti mislykkede logins for én bruger fra én adresse inden for fem minutter afvises i et stykke tid.
- Forespørgslers indhold er JSON, højst 64 KB.
- Forespørgsler fra andre websteder i en browser afvises; scripts med et token berøres ikke.
Kompatibilitet
Nye versioner af ZiiX.TV tilføjer til API’et, men fjerner eller omdøber ikke det, der er, så scripts og ældre apps bliver ved med at virke efter en opdatering.