Files

T

44r0n7 000d97fdeb feat: ship HTTP dashboard and harden daemon/API flows

Add the static HTTP dashboard example and wire in the recent daemon/API polish:
CORS-aware API routing, service-install behavior cleanup, safer systemd unit
ExecStart quoting, and friendly-name validation for path-safe targeting.

Also refresh README/API/roadmap docs, remove the temporary claude observations
file, and include the related tests for API/status and daemon validation.

2026-04-18 16:45:12 -04:00

1.8 KiB

Raw Blame History

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:

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

Error responses:

{
  "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/

1.8 KiB Raw Blame History