pyatv-http 0.1.2

HTTP interface for controlling Apple TVs via pyatv

pyatv-http

An HTTP interface for controlling Apple TVs, built on top of pyatv.

Features

• POST /<name>/turnOn and POST /<name>/turnOff — checks the Apple TV's current power state and only sends a command if it differs from the desired state.
• GET /<name>/powerState — reads the current power state without changing it.
• GET /devices — lists the devices available in the config file.
• GET /health — unauthenticated liveness check, for load balancers/uptime monitors.
• Every other request requires a bearer token, configured as a list of accepted tokens in the config file.
• Config-driven: one TOML file lists the port to listen on, accepted API tokens, and the paired devices.
• Pairing stays out-of-band, via pyatv's own atvremote CLI; a pyatv-http gen-config helper turns a paired device's stored credentials into a config snippet.

Setup

1. Find your Apple TV

uvx --from pyatv atvremote scan

This lists every Apple TV on the network along with its identifiers, IP address, and which protocols it supports (AirPlay, Companion, etc).

2. Pair with atvremote

Power control uses the Companion protocol, and pyatv-http talks to the device over AirPlay for the initial handshake, so pair both:

uvx --from pyatv atvremote --id <device-identifier> pair --protocol airplay
uvx --from pyatv atvremote --id <device-identifier> pair --protocol companion

Follow the on-screen PIN prompt for each. Credentials are stored in pyatv's storage file (default ~/.pyatv.conf).

3. Generate a config entry

uv run pyatv-http gen-config \
  --identifier <device-identifier> \
  --address <device-ip-or-hostname> \
  --key living_room

<device-identifier> and <device-ip-or-hostname> come from the scan output in step 1; --key is whatever short name you want to use in URLs (--name sets the human-readable display name too, defaulting to --key).

This prints a [devices.living_room] TOML block built from the stored pairing. Paste it into your config file (see below). If the identifier doesn't match any paired device, the command lists the identifiers it does have on file.

4. Write the config file

port = 8080

[auth]
tokens = ["a-long-random-token"]

[devices.living_room]
name = "Living Room"
identifier = "AA:BB:CC:DD:EE:FF"
address = "10.0.0.5"

[devices.living_room.protocols.airplay]
identifier = "AA:BB:CC:DD:EE:FF"
credentials = "..."

[devices.living_room.protocols.companion]
identifier = "11:22:33:44:55:66"
credentials = "..."

• port — port the HTTP server listens on. Optional, defaults to 8080.
• [auth].tokens — required, non-empty list of bearer tokens accepted on every request (see API below). Generate one with e.g. python3 -c "import secrets; print(secrets.token_urlsafe(32))".
• The [devices.<key>] table key (living_room above) is the URL path segment used in requests, e.g. POST /living_room/turnOn.
• identifier — the device's main pyatv identifier (from atvremote scan).
• address — the Apple TV's IP address or hostname; used to connect directly instead of relying on mDNS discovery at request time.
• [devices.<key>.protocols.<protocol>] — one block per paired protocol, exactly as generated by gen-config. Supported protocol names: airplay, companion, dmap, mrp, raop.

5. Run the server

uv run pyatv-http serve --config config.toml

--config is optional; if omitted, it defaults to $XDG_CONFIG_HOME/pyatv-http/config.toml, falling back to ~/.config/pyatv-http/config.toml when $XDG_CONFIG_HOME isn't set.

By default the server binds 0.0.0.0; pass --host to bind a specific interface.

API

Every request must include one of the configured tokens as a bearer token:

TOKEN=a-long-random-token

curl -X POST http://localhost:8080/living_room/turnOn \
  -H "Authorization: Bearer $TOKEN"

curl -X POST http://localhost:8080/living_room/turnOff \
  -H "Authorization: Bearer $TOKEN"

curl http://localhost:8080/living_room/powerState \
  -H "Authorization: Bearer $TOKEN"

curl http://localhost:8080/devices \
  -H "Authorization: Bearer $TOKEN"

curl http://localhost:8080/health

turnOn/turnOff/powerState return a JSON body: {"device": "living_room", "power_state": "on"}.

GET /devices returns the devices available in the config file:

[{"device": "living_room", "name": "Living Room"}]

GET /health (no token required) returns {"status": "ok"}.

Status	Meaning
200	Command sent (or no-op, if the device was already in that state)
401	Missing or invalid bearer token
404	No device configured under that name
504	Device could not be found/reached on the network
502	pyatv raised an error while connecting or sending the command

Interactive API docs

FastAPI auto-generates interactive documentation for the running server:

• GET /docs — Swagger UI (use the "Authorize" button to set your bearer token, then try requests directly from the browser).
• GET /redoc — ReDoc view of the same schema.
• GET /openapi.json — the raw OpenAPI schema.

These three routes are not themselves behind the bearer-token check.

Notes

• Each request opens a fresh connection to the Apple TV, checks its current power state, and only sends turnOn/turnOff if it differs from the desired state — there's no persistent connection or background polling.
• Pairing is entirely out-of-band via atvremote; this project never performs the pairing handshake itself.

Development

uv sync
uv run pytest   # or: mise run test
hk check --all