Skip to content
Tilecast Docs

createCountdownBarInstance

POST
/api/v1/plugins/countdown-bar/instances
curl --request POST \
  --url https://example.com/api/v1/plugins/countdown-bar/instances \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "message": "example", "scheduleType": "weekly", "targetTime": "example", "daysOfWeek": [ 1 ], "oneTimeAt": "2026-04-15T12:00:00Z", "timezone": "example", "leadTimeSeconds": 1, "completionText": "example", "showConfetti": false, "displayMode": "overlay", "heightPx": 1, "progressFill": "none", "contentPadding": 4, "textScale": 100, "fontId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "urgencyEnabled": false, "startingSoonSeconds": 300, "urgentSeconds": 60, "pulseSeconds": 10, "enabled": true, "priority": 1, "targetScope": "all", "targetIds": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ] }'

Create a Countdown Bar instance. Requires an Owner or Administrator.

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters”
X-CSRF-Token
string

Cookie-backed browser requests only, and only on unsafe methods. Bearer grants never send it.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
required
string
>= 1 characters <= 180 characters
message
required
string
>= 1 characters <= 280 characters
scheduleType
required
Allowed values: weekly one_time
targetTime
string
/^([01][0-9]|2[0-3]):[0-5][0-9]$/
daysOfWeek
required
Array<integer>
unique items
oneTimeAt
string format: date-time
timezone
required
string
>= 1 characters <= 100 characters
leadTimeSeconds
required
integer
>= 60 <= 2592000
completionText
required
string
<= 280 characters
showConfetti
required

Show a short confetti fall from the top of the Player when the countdown reaches zero. This does not require completion text.

boolean
displayMode
required
Allowed values: overlay push
heightPx
required
integer
>= 40 <= 320
progressFill

Background treatment behind the bar text. “drain” starts the bar fully tinted when the lead window opens and retreats the tint leftward as the target approaches, leaving only the bar background at zero. Omitted means “none”.

default: none
Allowed values: none drain
contentPadding

Share of each side left as a gutter, as a percentage of the bar width. Lowering it gives a long message or a larger type size more room. The default 4 matches the bar’s original gutters.

integer
default: 4 <= 40
textScale

Percentage applied to the height-derived type size, so a bar can carry larger text without changing its height. 100 is the original appearance.

integer
default: 100 >= 25 <= 500
fontId

An organization font library family the bar draws with, from GET /api/v1/fonts. Omit it, or send null, to keep the Player’s own face. A Player draws the library family only when it hosts Plugin API 2 and the font service; every other Player keeps its own face. A family that is not in the library is rejected, and the library refuses to remove a family a bar uses.

string format: uuid
urgencyEnabled
required

Enable automatic starting-soon, urgent, and final pulse stages.

boolean
startingSoonSeconds
required
integer
default: 300 >= 2 <= 86400
urgentSeconds
required
integer
default: 60 >= 2 <= 3600
pulseSeconds
required

Final seconds during which the urgent bar pulses and grows by 25 percent.

integer
default: 10 >= 1 <= 60
enabled
required
boolean
priority
required
integer
>= -1000 <= 1000
targetScope
required
Allowed values: all screens sync_groups locations
targetIds
required
Array<string>
<= 250 items unique items

Responses

Section titled “ Responses ”

201

Section titled “201”

Countdown Bar instance created

400

Section titled “400”

Typed configuration or targets are invalid

403

Section titled “403”

Owner or Administrator required