preflightSchedule

POST

/api/v1/schedules/preflight

curl --request POST \
  --url https://example.com/api/v1/schedules/preflight \
  --header 'Content-Type: application/json' \
  --cookie tilecast_session=<tilecast_session> \
  --data '{ "scheduleId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "proposedSchedule": { "name": "example", "description": "example", "playlistId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "layoutId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "displayAction": { "type": "display_power_on", "input": "example", "volume": 1, "brightness": 1 }, "type": "one_time", "timezone": "example", "priority": 1, "enabled": true, "startDate": "2026-04-15", "endDate": "2026-04-15", "oneTimeStart": "2026-04-15T12:00:00Z", "oneTimeEnd": "2026-04-15T12:00:00Z", "dailyStart": "example", "dailyEnd": "example", "daysOfWeek": [ 1 ], "targets": [ { "type": "screen", "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "name": "example" } ] } }'

Read-only inspection of a proposed schedule. Requires an authenticated user with the read scope; every role may call it, and the targets must be inside the caller’s screen scope. The server expands every targeted screen and Display Group, finds the draft’s next occurrence in its own timezone, and evaluates precedence on each screen at that instant with the same resolver Players use. A draft that is disabled is simulated as enabled; draftEnabled reports its real state. Counts describe the whole target set; the screens and competitors lists are bounded. Pass scheduleId when editing a saved schedule so its stored copy does not compete with the draft. A scoped account sees a competing schedule’s name and ID only when all of that schedule’s targets are inside its scope; other competitors keep their counts and reasons but carry no name and a placeholder ID. The result describes the next occurrence only, never every future occurrence. Use previewSchedule to inspect one exact screen at an exact time.

Authorizations

• sessionCookie
• userBearer

Request Body^required

Media typeapplication/json

object

scheduleId

string format: uuid

proposedSchedule

required

object

name

required

string

description

string

playlistId

string format: uuid

layoutId

string format: uuid

displayAction

A bounded Display Control action. A schedule may contain one action instead of a playlist or Layout. The server validates that only the field belonging to the selected type is present.

object

type

required

string

Allowed values: display_power_on display_power_off display_set_input display_set_volume display_mute display_unmute display_set_brightness

input

string

/^[A-Za-z0-9._:-]{1,32}$/

volume

integer

<= 100

brightness

integer

<= 100

type

required

string

Allowed values: one_time weekly

timezone

required

string

priority

required

integer

enabled

required

boolean

startDate

string | null format: date

endDate

string | null format: date

oneTimeStart

string | null format: date-time

oneTimeEnd

string | null format: date-time

dailyStart

string | null

dailyEnd

string | null

daysOfWeek

Array<integer>

targets

required

Array<object>

object

type

required

string

Allowed values: screen group

id

required

string format: uuid

name

string

Responses

200

Aggregated next-occurrence precedence result

Media typeapplication/json

object

data

required

object

draftEnabled

required

boolean

checkedAt

The instant evaluated. Absent when the draft never runs again.

string format: date-time

running

required

True when checkedAt is the current time inside an occurrence that has already started.

boolean

targetScreenCount

required

integer

winningScreenCount

required

integer

losingScreenCount

required

integer

unsupportedScreenCount

required

integer

competitors

required

Array<object>

object

scheduleId

required

string format: uuid

name

required

string

priority

required

integer

presentationType

required

string

Allowed values: playlist layout display_control

affectedScreenCount

required

integer

>= 1

outranksDraftScreenCount

required

integer

reason

required

string

Allowed values: active_takeover active_quick_present assigned_fallback schedule_highest_precedence schedule_disabled schedule_not_active schedule_lower_priority schedule_less_specific schedule_earlier_start schedule_stable_id_tiebreak no_active_takeover no_active_quick_present no_assignment

competitorsTruncated

required

boolean

screens

required

Screens where the draft does not win, bounded. Wins are counted in winningScreenCount, never listed.

Array<object>

object

screenId

required

string format: uuid

name

required

string

outcome

required

string

Allowed values: superseded unsupported

reason

string

Allowed values: active_takeover active_quick_present assigned_fallback schedule_highest_precedence schedule_disabled schedule_not_active schedule_lower_priority schedule_less_specific schedule_earlier_start schedule_stable_id_tiebreak no_active_takeover no_active_quick_present no_assignment

winnerScheduleId

string format: uuid

winnerName

string

screensTruncated

required

boolean

issues

required

Array<object>

object

code

required

string

Allowed values: display_control_unsupported no_upcoming_run

severity

required

string

Allowed values: blocking warning

screenCount

integer

>= 1

Example

{
  "data": {
    "competitors": [
      {
        "presentationType": "playlist",
        "reason": "active_takeover"
      }
    ],
    "screens": [
      {
        "outcome": "superseded",
        "reason": "active_takeover"
      }
    ],
    "issues": [
      {
        "code": "display_control_unsupported",
        "severity": "blocking"
      }
    ]
  }
}

400

Malformed body or an unknown field

401

Authentication required

403

Scope or target scope requirement not met

404

A referenced Playlist, Layout, or target was not found

409

The presentation conflicts with a target

422

Schedule or target validation failed