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
<localhost:4001>/api/version

Response

{"payload":"3.0.0"}

Get Ontime runtime state

Request

Terminal window
<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 currentluy defined settings for views

Change event

Terminal window
<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)
durationnumber (in seconds)
timeStartnumber (in seconds)
timeEndnumber (in seconds)

Example: change title of event

Request

Terminal window
<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
<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
<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 views.
The payload response is the current state of the message data

Example: change the external message text

Request

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

Response

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

Example: change the external message visibility

Request

Terminal window
<localhost:4001>/api/message/external?visible=true

Response

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

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
<localhost:4001>/api/start

Response

{"payload":"success"}

Start event at index

Request

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

Response

{"payload":"success"}

Start event with ID

Request

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

Response

{"payload":"success"}

Start event with cue

Request

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

Response

{"payload":"success"}

Start next event

Request

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

Response

{"payload":"success"}

Start previous event

Request

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

Response

{"payload":"success"}

Pause running timer

Request

Terminal window
<localhost:4001>/api/pause

Response

{"payload":"success"}

Load event

Load event at index

Request

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

Response

{"payload":"success"}

Load event with ID

Request

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

Response

{"payload":"success"}

Load event with cue

Request

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

Response

{"payload":"success"}

Load next event

Request

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

Response

{"payload":"success"}

Load previous event

Request

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

Response

{"payload":"success"}

Reload current event

Request

Terminal window
<localhost:4001>/api/reload

Response

{"payload":"success"}

Stop playback

Request

Terminal window
<localhost:4001>/api/stop

Response

{"payload":"success"}

Activate Roll mode

Request

Terminal window
<localhost:4001>/api/roll

Response

{"payload":"success"}

User added time

Add time

Request

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

Response

{"payload":"success"}

Remove time

Request

Terminal window
<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
<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
<localhost:4001>/api/auxtimer/1/direction/count-up

Set auxiliary timer to count down

Request

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

Start auxiliary timer

Request

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

Pause auxiliary timer

Request

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

Stop auxiliary timer

Request

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