Skip to content

HTTP API

You can control most of the playback functions of Ontime over HTTP protocol.
This could be handy for integration with third party software, including vMix.

State

The following endpoints allow querying Ontime for its current state

Get Ontime version

Request

Terminal window
GET <localhost:4001>/api/version

Response

{"payload":"3.0.0"}

Get Ontime runtime state

Request

Terminal window
GET <localhost:4001>/api/poll

Response
The response of a poll request is a runtime data object

{"payload": <runtime-data>}

Data from Ontime

With the HTTP API, in addition to controlling the application, you can also retrieve its data.
There is no expected payload for these GET requests

AddressDescription
/data/custom-fieldsGet registered custom fields
/data/dbGet currently loaded project file
/data/httpGet HTTP integration settings
/data/oscGet OSC integration settings
/data/projectGet current project data
/data/rundownGet current rundown
/data/settingsGet current application settings
/data/url-presetsGet currently defined URL Presets
/data/view-settingsGet currently defined settings for views

Change event

Terminal window
GET <localhost:4001>/api/change/<event-id>/<property>/<value>

The change endpoint allows changing some of the properties of a given event (below).
The request should contain a patch of the event to be changed, along with the ID of the event to change.

You can change any field in an event using this endpoint. See below a description of expected values.

PropertyValue type
titlestring
notestring
cuestring (value should be kept under 8 characters)
isPublicboolean
skipboolean
colourstring (# hex colour or named css colour)
customtarget the specific custom field with custom:<fieldname>
timeWarningnumber (in seconds)
timeDangernumber (in seconds)
endActionstring (none / load-next / play-next / stop)
timerTypestring (count-down / count-up / time-to-end / clock / none)
durationnumber (in seconds)
timeStartnumber (in seconds)
timeEndnumber (in seconds)

Example: change title of event

Request

Terminal window
GET <localhost:4001>/api/change/<my-event-id>?title=new-title

Response

{"payload":"success"}

Example: change a custom field

The custom field must exist in the project to be accepted by the API.
See more on custom fields

Request

Terminal window
GET <localhost:4001>/api/change/<my-event-id>?custom:<field-name>=new-value

Response

{"payload":"success"}

Example: change multiple fields

You can change multiple fields in a single request by using adding on more query parameters. \

Request

Terminal window
GET <localhost:4001>/api/change/<my-event-id>?title=new-title&cue=new-cue

Response

{"payload":"success"}

Message

The following endpoints allow controlling the messages Ontime sends to the timer view.
The payload response is the current state of the message data.

Example: change the external message text

Request

Terminal window
GET <localhost:4001>/api/message/external/new text

Response

{
"payload": {
"external": "new text",
"timer": {
"text": "",
"visible": true,
"blink": false,
"blackout": false,
"secondarySource": null
},
}
}

Example: secondary source in the timer view

Request

Show auxiliary timer as secondary field
<localhost:4001>/api/message/timer?secondarySource=aux

Request

Show external message as secondary field
<localhost:4001>/api/message/timer?secondarySource=external

Request

Hide secondary field
# Note: The secondary source can be `aux` or `external`, any other value will assign the property to null (ie: off)
<localhost:4001>/api/message/timer?secondarySource=off

Response

{
"payload": {
"external": "new text",
"timer": {
"text": "",
"visible": true,
"blink": false,
"blackout": false,
"secondarySource": "external"
},
}
}

Example: blackout timer screens

You can remotely blackout every screen that is in the timer view.

Request

Blackout timer screen
<localhost:4001>/api/message/timer?blackout=true

Request

Disable timer screen blackout
GET <localhost:4001>/api/message/timer?blackout=false

Response

{
"payload": {
"external": "",
"timer": {
"text": "",
"visible": true,
"blink": true,
"blackout": false,
"secondarySource": null
},
}
}

Playback

The following endpoints allow controlling the Ontime’s playback.
The payload response is the current state of the message data

Start event

Start loaded event

Request

Terminal window
GET <localhost:4001>/api/start

Response

{"payload":"success"}

Start event at index

Request

Terminal window
GET <localhost:4001>/api/start/index/<event-index>

Response

{"payload":"success"}

Start event with ID

Request

Terminal window
GET <localhost:4001>/api/start/id/<event-id>

Response

{"payload":"success"}

Start event with cue

Request

Terminal window
GET <localhost:4001>/api/start/cue/<event-cue>

Response

{"payload":"success"}

Start next event

Request

Terminal window
GET <localhost:4001>/api/start/next

Response

{"payload":"success"}

Start previous event

Request

Terminal window
GET <localhost:4001>/api/start/previous

Response

{"payload":"success"}

Pause running timer

Request

Terminal window
GET <localhost:4001>/api/pause

Response

{"payload":"success"}

Load event

Load event at index

Request

Terminal window
GET <localhost:4001>/api/load/index/<event-index>

Response

{"payload":"success"}

Load event with ID

Request

Terminal window
GET <localhost:4001>/api/load/index/<event-id>

Response

{"payload":"success"}

Load event with cue

Request

Terminal window
GET <localhost:4001>/api/load/index/<event-cue>

Response

{"payload":"success"}

Load next event

Request

Terminal window
GET <localhost:4001>/api/load/next

Response

{"payload":"success"}

Load previous event

Request

Terminal window
GET <localhost:4001>/api/load/previous

Response

{"payload":"success"}

Reload current event

Request

Terminal window
GET <localhost:4001>/api/reload

Response

{"payload":"success"}

Stop playback

Request

Terminal window
GET <localhost:4001>/api/stop

Response

{"payload":"success"}

Activate Roll mode

Request

Terminal window
GET <localhost:4001>/api/roll

Response

{"payload":"success"}

User added time

Add time

Request

Terminal window
GET <localhost:4001>/api/addtime/add/<value-in-seconds>

Response

{"payload":"success"}

Remove time

Request

Terminal window
GET <localhost:4001>/api/addtime/remove/<value-in-seconds>

Response

{"payload":"success"}

Auxiliary timer

Ontime provides an auxiliary timer which does not affect the current playback.
This can be controlled using the API as shown below

Set auxiliary timer duration

Request

Terminal window
GET <localhost:4001>/api/auxtimer/1/duration/<value-in-seconds>

Set auxiliary timer direction

Auxiliary timer can count up or count down.

Set auxiliary timer to count up

Request

Terminal window
GET <localhost:4001>/api/auxtimer/1/direction/count-up

Set auxiliary timer to count down

Request

Terminal window
GET <localhost:4001>/api/auxtimer/1/direction/count-down

Start auxiliary timer

Request

Terminal window
GET <localhost:4001>/api/auxtimer/1/start

Pause auxiliary timer

Request

Terminal window
GET <localhost:4001>/api/auxtimer/1/pause

Stop auxiliary timer

Request

Terminal window
GET <localhost:4001>/api/auxtimer/1/stop

Add / remove time to auxiliary timer

Request

Terminal window
GET <localhost:4001>/api/auxtimer/1/addtime/<value-in-seconds>