API Endpoints

FiestaBoard provides a REST API powered by FastAPI. Interactive API documentation is available at http://localhost:4420/api/docs when FiestaBoard is running.

Base URL

http://localhost:4420

When using the default deployment, prefix all paths with /api (e.g. GET http://localhost:4420/api/health).

System Endpoints

Health & Status

Method	Endpoint	Description
GET	/health	Health check, returns service health status
GET	/status	Service status, uptime, and current configuration
GET	/config	Current configuration settings

Display Control

Method	Endpoint	Description
POST	/refresh	Refresh the current display
POST	/force-refresh	Force refresh (bypasses preview cache)
POST	/send-message	Send a custom message to the board

Service Control

Method	Endpoint	Description
POST	/start	Start the display service
POST	/stop	Stop the display service

Page Endpoints

Method	Endpoint	Description
GET	/pages	List all pages
POST	/pages	Create a new page
GET	/pages/{id}	Get a specific page
PUT	/pages/{id}	Update a page
DELETE	/pages/{id}	Delete a page
POST	/pages/{id}/preview	Preview a page (with variables resolved)

Page Fields

When creating or updating a page, the following fields are available:

Field	Type	Description
name	string	Page name (required)
type	string	"template", "single", or "composite"
device_type	string	"flagship" (22×6) or "note" (15×3). Default: "flagship"
template	string[]	Template lines for template-type pages
duration_seconds	number	How long to display (10–3600s, default 300)

Batch Operations

Method	Endpoint	Description
POST	/pages/preview/batch	Preview multiple pages at once
POST	/displays/raw/batch	Get raw display data for multiple pages

Schedule Endpoints

Method	Endpoint	Description
GET	/schedules	List all schedule entries
POST	/schedules	Create a new schedule entry
GET	/schedules/{id}	Get a specific schedule entry
PUT	/schedules/{id}	Update a schedule entry
DELETE	/schedules/{id}	Delete a schedule entry

Plugin Endpoints

Method	Endpoint	Description
GET	/plugins	List all plugins with status
GET	/plugins/{id}	Get plugin details
PUT	/plugins/{id}/config	Update plugin configuration
POST	/plugins/{id}/enable	Enable a plugin
POST	/plugins/{id}/disable	Disable a plugin
GET	/plugins/{id}/data	Get current plugin data
GET	/plugins/{id}/variables	Get available template variables

Settings Endpoints

Method	Endpoint	Description
GET	/settings/all	Get all settings in a single call
GET	/settings/transitions	Get transition animation settings
PUT	/settings/transitions	Update transition settings
GET	/settings/output	Get output target settings
PUT	/settings/output	Update output target
GET	/settings/board	Get board configuration
PUT	/settings/board	Update board configuration

Board Management

Installs with more than one board follow a per-board model: each board has its own active page, schedule, and send routing, addressed by a board_id query param (or body field) on the relevant endpoints below. Omitting board_id always falls back to the primary board (boards[0]), which keeps single-board installs behaving exactly as before. Pages and Collections are not per-board — they're one shared library, and their pickers filter to the boards they're compatible with (see Board Instance Fields for the size model).

Method	Endpoint	Description
PUT	/settings/board	Update board configuration (devices, connection)
POST	/settings/board/add	Add a new board instance
DELETE	/settings/board/{id}	Remove a board instance
GET	/settings/active-page	Get a board's active page id (?board_id=)
PUT	/settings/active-page	Set a board's active page (renders and sends immediately)
POST	/pages/{id}/send	Send a page (?target=board&board_id=)
GET	/board/current-message	Read a board's current display (?board_id=)

PUT /settings/board — request body fields

Field	Type	Description
boards	object[]	Array of BoardInstance objects (V2 format)
devices	string[]	Device type list e.g. ["flagship", "note"] (backward-compatible)
board_type	string	Legacy field — still accepted

PUT /settings/active-page — request body fields

Field	Type	Description
page_id	string | null	Page (or collection) id to activate, or null to clear
board_id	string	Optional. Omitted → primary board (legacy behavior)

Board Instance Fields

Field	Type	Description
id	string	UUID (auto-generated on create)
name	string	Display name for this board
device_type	string	"flagship" (22×6), "note" (15×3), or "note_array" (variable W×H)
board_color	string	"black" or "white"
api_mode	string	"local" or "cloud"
host	string	Board IP address (local mode)
local_api_key	string	Local API key
cloud_key	string	Cloud Read/Write key
note_array_token	string	Cloud API token (note-array boards in cloud mode)
notes_wide / notes_tall	number	Note-array grid dimensions — resolves to (notes_wide × 15) × (notes_tall × 3) characters
enabled	boolean	Whether this board is active
schedule_enabled	boolean	Whether this board follows its schedule (vs. manual mode)
paused	boolean	Whether this board's output is paused

Example Requests

Get Service Status

curl http://localhost:4420/api/status

Send a Message

curl -X POST http://localhost:4420/api/send-message \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello World!"}'

List Plugins

curl http://localhost:4420/api/plugins

Preview a Page

curl -X POST http://localhost:4420/api/pages/1/preview

Interactive Documentation

For a complete interactive API explorer with request/response schemas, visit:

http://localhost:4420/api/docs

This provides a Swagger UI where you can try out any endpoint directly in your browser.

Next Steps

• Docker Setup - Understanding the API architecture
• Plugin Configuration - Configuring plugins via API