Using the API

ZiiX.TV's HTTP API: logging in with a token, the interactive documentation on your server, examples with curl, live events, errors and limits.

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/logout or 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"}
StatusCodeMeaning
401unauthorizedNo token, or the token has run out
403forbiddenNeeds an administrator
402license_requiredThe server’s trial or license has run out
429too_many_attemptsToo many failed logins; wait a few minutes
503transcode_busyThe 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.