# Player API Reference

## Overview

Player service base URL: `http://localhost:3001`

This document uses OpenAPI-style sections, but stays in plain markdown.

## Endpoints

### `GET /`
Returns a plain-text landing response for the player service.

### `GET /screen/{slug}`
Returns the rendered player page for a screen.

### `GET /api/screens/{slug}/playlist`
Returns the current playlist payload for a screen.

### `GET /api/screens/{slug}/connections`
### `GET /api/screens/{slug}/clients`
Returns the live player connection snapshot for a screen.

### `POST /api/screens/{slug}/commands`
Sends a command to the player connections for a screen.

Accepted request fields:

- `command` required
- `connectionId` optional
- `clientId` optional
- `blackout` optional when `command=blackout`

Supported commands:

- `refresh`
- `reload`
- `pause`
- `blackout`
- `previous`
- `next`
- `left`
- `right`

If `connectionId` or `clientId` is provided, the command targets a single player connection. Otherwise it is broadcast to all connections for that screen.

## Response Shapes

### Playlist Response

`GET /api/screens/{slug}/playlist` returns an object with:

- `screen`
- `playlist`
- `slides`

### Connections Response

`GET /api/screens/{slug}/connections` and `GET /api/screens/{slug}/clients` return an object with:

- `screen`
- `screenSlug`
- `count`
- `connections`

### Command Response

`POST /api/screens/{slug}/commands` returns an object with:

- `screen`
- `screenSlug`
- `command`
- `connectionId`
- `sent`

## Data Models

### Screen

- `id`
- `name`
- `slug`
- `playlist_id`
- `created_at`
- `modified_at`

### Playlist

- `id`
- `name`
- `fade_between_slides`

### Slide

- `id`
- `title`
- `body`
- `duration_seconds`
- `schedule_mode`
- `schedule_start_datetime`
- `schedule_end_datetime`
- `schedule_start_time`
- `schedule_end_time`
- `schedule_days_json`
- `media_url`
- `media_type`
- `kind`
- `template_id`
- `template`
- `content`

### Connection

- `id`
- `clientId`
- `label`
- `userAgent`
- `viewport`
- `page`
- `currentSlide`
- `paused`
- `blackout`
- `clientIp`
- `remoteAddress`
- `connectedAt`
- `lastSeenAt`

## Notes

- The player API is the only surface documented here.
- Web UI/admin routes are intentionally omitted.