pulse-signage/docs/api.md

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.