Everything the web app and the apps do goes through ZiiX.TV’s HTTP API, and you can use it too: for scripts, home automation or your own client.
The documentation is on your server
Every server has its full API reference at http://<your server>:8470/docs, with a search, examples and a download of the OpenAPI specification. It is made from the same specification as the server itself, so it always matches your version. The link is in the footer of the web app.
Logging in
All requests go to /api. Log in with a username and password to get a 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 the token in the Authorization header with every request:
curl http://nas:8470/api/libraries -H 'Authorization: Bearer <token>'
- A token works for 90 days, or until it is logged out with
POST /api/auth/logoutor under Settings → Devices. - A token acts as its user and sees what that user sees. Endpoints for settings, users and libraries need an administrator.
- Use a separate user for a script, so it can be logged out on its own.
Examples
# The libraries, and the titles in library 2
curl http://nas:8470/api/libraries -H "Authorization: Bearer $TOKEN"
curl http://nas:8470/api/libraries/2/titles -H "Authorization: Bearer $TOKEN"
# Continue watching
curl http://nas:8470/api/continue -H "Authorization: Bearer $TOKEN"
# Mark a title as watched
curl -X PUT http://nas:8470/api/titles/12/watched \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"watched":true}'
# Scan library 2 now (administrators)
curl -X POST http://nas:8470/api/libraries/2/scan -H "Authorization: Bearer $TOKEN"
Playing a file is two steps: POST /api/files/{id}/playback with what the client can play returns how to play it (directly, repackaged or converted) and the address of the stream; PUT /api/files/{id}/progress saves where the user is. The reference has the details.
Live events
GET /api/events is a WebSocket that sends a short JSON message whenever something changes, so a client can update without asking again and again:
{"type":"titles","libraryId":2}
The types are libraries (added, removed, scanning), titles (new or changed titles), metadata, watch (watch history) and views.
Errors
Errors have a stable code for programs and a message for people:
{"code":"unauthorized","error":"log in to use this server"}
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthorized | No token, or the token has run out |
| 403 | forbidden | Needs an administrator |
| 402 | license_required | The server’s trial or license has run out |
| 429 | too_many_attempts | Too many failed logins; wait a few minutes |
| 503 | transcode_busy | The server converts as many videos as it is allowed to |
Limits
- Ten failed logins for one user from one address within five minutes are refused for a while.
- Request bodies are JSON, at most 64 KB.
- Requests from other websites in a browser are refused; scripts with a token are not affected.
Compatibility
New versions of ZiiX.TV add to the API but do not remove or rename what is there, so scripts and older apps keep working after an update.