https://github.com/hugoh/pyatv-http
HTTP interface for controlling Apple TVs via pyatv, with bearer-token auth
https://github.com/hugoh/pyatv-http
apple-tv fastapi home-automation http-api pyatv python rest-api
Last synced: 1 day ago
JSON representation
HTTP interface for controlling Apple TVs via pyatv, with bearer-token auth
- Host: GitHub
- URL: https://github.com/hugoh/pyatv-http
- Owner: hugoh
- License: mit
- Created: 2026-07-22T01:07:54.000Z (3 days ago)
- Default Branch: main
- Last Pushed: 2026-07-22T01:58:54.000Z (2 days ago)
- Last Synced: 2026-07-22T03:24:14.292Z (2 days ago)
- Topics: apple-tv, fastapi, home-automation, http-api, pyatv, python, rest-api
- Language: Python
- Homepage: https://pypi.org/project/pyatv-http/
- Size: 116 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# pyatv-http
An HTTP interface for controlling Apple TVs, built on top of
[pyatv](https://github.com/postlund/pyatv).
## Features
- `GET //power-state` — reads the current power state without changing it.
- `PUT //power-state` (body `{"power_state": "on"}` or `{"power_state":
"off"}`) — checks the Apple TV's current power state and only sends a
command if it differs from the desired state. `POST` is also accepted as an
identical alias, for clients/platforms that can't issue `PUT` requests.
- `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
```sh
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:
```sh
uvx --from pyatv atvremote --id pair --protocol airplay
uvx --from pyatv atvremote --id 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
```sh
uv run pyatv-http gen-config \
--identifier \
--address \
--key living_room
```
`` and `` 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
```toml
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](#api) below). Generate one with e.g.
`python3 -c "import secrets; print(secrets.token_urlsafe(32))"`.
- The `[devices.]` table key (`living_room` above) is the URL path
segment used in requests, e.g. `PUT /living_room/power-state`.
- `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..protocols.]` — one block per paired protocol,
exactly as generated by `gen-config`. Supported protocol names: `airplay`,
`companion`, `dmap`, `mrp`, `raop`.
### 5. Run the server
```sh
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:
```sh
TOKEN=a-long-random-token
curl -X PUT http://localhost:8080/living_room/power-state \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"power_state": "on"}'
curl -X PUT http://localhost:8080/living_room/power-state \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"power_state": "off"}'
# POST is also accepted, identical to PUT, for clients that can only
# issue GET/POST requests:
curl -X POST http://localhost:8080/living_room/power-state \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"power_state": "on"}'
curl http://localhost:8080/living_room/power-state \
-H "Authorization: Bearer $TOKEN"
curl http://localhost:8080/devices \
-H "Authorization: Bearer $TOKEN"
curl http://localhost:8080/health
# Fallback for clients that can't set an Authorization header (see
# "Limited HTTP clients" below): access_token in the query string for GET,
# access_token as a JSON body field for POST. Not available for PUT.
curl "http://localhost:8080/living_room/power-state?access_token=$TOKEN"
curl -X POST http://localhost:8080/living_room/power-state \
-H "Content-Type: application/json" \
-d '{"power_state": "on", "access_token": "'"$TOKEN"'"}'
```
`GET`/`PUT`/`POST //power-state` all return a JSON body:
`{"device": "living_room", "power_state": "on"}`.
`GET /devices` returns the devices available in the config file:
```json
[{"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.
### Limited HTTP clients (e.g. Hubitat Rule Machine)
A lot of home-automation "rule engine" style integrations — Hubitat's Rule
Machine is the one that prompted this — can only fire `GET` and `POST`
requests, and can't attach a custom `Authorization` header to them. Two
things in this API exist specifically to accommodate that:
1. **`POST` is a full alias for `PUT`** on `//power-state`. State
changes normally belong on `PUT` (it's idempotent and semantically
correct — "set this resource to this value"), but any client that can
only do `GET`/`POST` can use `POST` with the exact same body and get
identical behavior.
2. **The bearer token can be passed in-band instead of as a header**, as a
fallback that's only checked when no valid `Authorization` header is
present. This follows [RFC 6750](https://www.rfc-editor.org/rfc/rfc6750)
(OAuth 2.0 Bearer Token Usage) sections 2.2 and 2.3, which define
`access_token` as the parameter name for exactly this case:
- `GET` requests: `?access_token=...` query parameter.
- `POST` requests: `"access_token"` field in the JSON body, alongside
`power_state`.
This fallback is **deliberately not available on `PUT`** — `PUT` stays
the strict, header-only, "do it the correct way" method. If your client
can set a custom header, prefer `PUT` with an `Authorization` header;
the fallback exists only for clients that genuinely can't.
**Security note:** a token in a URL or a JSON body is more likely to end up
somewhere you don't want it — server access logs, browser history, an
intermediate proxy's logs — than one in an `Authorization` header. Only rely
on this fallback when pyatv-http is reachable exclusively on a trusted local
network (the normal setup for a Hubitat hub talking to a LAN service, not
something exposed to the internet), and consider using a token dedicated to
that integration so it can be rotated on its own if it ever leaks.
## Notes
- Each request opens a fresh connection to the Apple TV, checks its current
power state, and only sends the power command 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
```sh
uv sync
uv run pytest # or: mise run test
hk check --all
```