# API.md
# tvctl HTTP API Specification

`tvctl` exposes a loopback-only HTTP API for tool builders at `/v1/...`.
This file captures the v1 surface promised by the design bundle so the
repository has a dedicated API spec from day one.

For browser-based tools, CORS is opt-in via daemon config.

## Base URL

`http://127.0.0.1:7272/v1`

## Response Envelope

Successful responses:

```json
{ "ok": true, "data": { "...": "..." } }
```

Error responses:

```json
{
  "ok": false,
  "error": {
    "code": "device_not_found",
    "message": "No device with id 'living-room' exists.",
    "hint": "Run tvctl device list to see known devices."
  }
}
```

## Planned Routes

- `GET /devices`
- `POST /devices/discover`
- `GET /devices/{id}`
- `DELETE /devices/{id}`
- `GET /devices/{id}/state`
- `GET /devices/{id}/apps`
- `POST /devices/{id}/apps/launch`
- `POST /devices/{id}/apps/stop`
- `POST /devices/{id}/apps/refresh`
- `POST /devices/{id}/remote/key`
- `POST /devices/{id}/remote/sequence`
- `POST /devices/{id}/dev/install`
- `POST /devices/{id}/dev/reload`
- `GET /devices/{id}/dev/logs`
- `GET /daemon/status`
- `GET /config`
- `PATCH /config`
- `POST /config/reload`

## API Rules

- All routes return the standard JSON envelope.
- `error.code` values are stable machine contracts.
- `error.hint` is optional but recommended for user-actionable failures.
- Devices may be addressed by UUID or friendly name.
- Path targets must be URL-encoded by clients (for example `Living Room TV` -> `Living%20Room%20TV`).
- User-supplied friendly names are trimmed; `/` and `%` are rejected (`invalid_device_name`).
- Platform-specific field names must not leak past the adapter layer.
- Browser clients require `daemon.cors_enabled = true` and explicit `daemon.cors_allowed_origins`.

## Dashboard Example

An endpoint coverage dashboard is included at:

`examples/http-dashboard/`