Metadata-Version: 2.4
Name: pyatv-http
Version: 0.2.0
Summary: HTTP interface for controlling Apple TVs via pyatv
Project-URL: Homepage, https://github.com/hugoh/pyatv-http
Project-URL: Issues, https://github.com/hugoh/pyatv-http/issues
Project-URL: Repository, https://github.com/hugoh/pyatv-http
Author: Hugo Haas
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Home Automation
Requires-Python: >=3.12
Requires-Dist: fastapi>=0.121.0
Requires-Dist: pyatv>=0.18.0
Requires-Dist: uvicorn>=0.38.0
Description-Content-Type: text/markdown

# pyatv-http

An HTTP interface for controlling Apple TVs, built on top of
[pyatv](https://github.com/postlund/pyatv).

## Features

- `GET /<name>/power-state` — reads the current power state without changing it.
- `PUT /<name>/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 <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

```sh
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

```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.<key>]` 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.<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

```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 /<name>/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 `/<name>/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
```
