Utiliser l'API

L'API HTTP de ZiiX.TV : connexion par jeton, documentation interactive sur votre serveur, exemples avec curl, événements en direct, erreurs et limites.

Tout ce que font l’appli web et les applis passe par l’API HTTP de ZiiX.TV, et vous pouvez l’utiliser vous aussi : pour des scripts, la domotique ou votre propre client.

La documentation est sur votre serveur

Chaque serveur propose sa référence complète de l’API à l’adresse http://<your server>:8470/docs, avec une recherche, des exemples et le téléchargement de la spécification OpenAPI. Elle est générée à partir de la même spécification que le serveur lui-même, elle correspond donc toujours à votre version. Le lien se trouve en bas de page de l’appli web.

Se connecter

Toutes les requêtes vont vers /api. Connectez-vous avec un nom d’utilisateur et un mot de passe pour obtenir un jeton :

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

Envoyez le jeton dans l’en-tête Authorization à chaque requête :

curl http://nas:8470/api/libraries -H 'Authorization: Bearer <token>'
  • Un jeton est valable 90 jours, ou jusqu’à sa déconnexion avec POST /api/auth/logout ou dans Paramètres → Appareils.
  • Un jeton agit au nom de son utilisateur et voit ce que cet utilisateur voit. Les endpoints des paramètres, des utilisateurs et des bibliothèques exigent un administrateur.
  • Utilisez un utilisateur distinct pour un script, afin de pouvoir le déconnecter séparément.

Exemples

# Les bibliothèques, et les titres de la bibliothèque 2
curl http://nas:8470/api/libraries -H "Authorization: Bearer $TOKEN"
curl http://nas:8470/api/libraries/2/titles -H "Authorization: Bearer $TOKEN"

# Reprendre la lecture
curl http://nas:8470/api/continue -H "Authorization: Bearer $TOKEN"

# Marquer un titre comme vu
curl -X PUT http://nas:8470/api/titles/12/watched \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"watched":true}'

# Analyser la bibliothèque 2 maintenant (administrateurs)
curl -X POST http://nas:8470/api/libraries/2/scan -H "Authorization: Bearer $TOKEN"

La lecture d’un fichier se fait en deux étapes : POST /api/files/{id}/playback, avec ce que le client sait lire, indique comment le lire (en direct, réempaqueté ou converti) et l’adresse du flux ; PUT /api/files/{id}/progress enregistre où en est l’utilisateur. La référence donne tous les détails.

Événements en direct

GET /api/events est un WebSocket qui envoie un court message JSON dès que quelque chose change, pour qu’un client puisse se mettre à jour sans redemander sans cesse :

{"type":"titles","libraryId":2}

Les types sont libraries (ajout, suppression, analyse), titles (titres nouveaux ou modifiés), metadata, watch (historique de visionnage) et views.

Erreurs

Les erreurs comportent un code stable pour les programmes et un message pour les humains :

{"code":"unauthorized","error":"log in to use this server"}
StatutCodeSignification
401unauthorizedPas de jeton, ou le jeton a expiré
403forbiddenNécessite un administrateur
402license_requiredL’essai ou la licence du serveur a expiré
429too_many_attemptsTrop de connexions échouées ; patientez quelques minutes
503transcode_busyLe serveur convertit déjà autant de vidéos qu’il y est autorisé

Limites

  • Après dix connexions échouées pour un même utilisateur depuis une même adresse en cinq minutes, les tentatives sont refusées pendant un moment.
  • Le corps des requêtes est en JSON, 64 Ko au maximum.
  • Les requêtes provenant d’autres sites web dans un navigateur sont refusées ; les scripts avec un jeton ne sont pas concernés.

Compatibilité

Les nouvelles versions de ZiiX.TV enrichissent l’API mais ne suppriment ni ne renomment ce qui existe : les scripts et les anciennes applis continuent de fonctionner après une mise à jour.