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.

Notes on requests

All HTTP requests are GET requests. Even if not as semantic, this is to facilitate integrations.
Please mind the correct configuration for IP and Port will depend on your setup.

Any request which successfully changes the Ontime playback will have a status code in the 200 range.

Show me the code

This documentation is generally simplified. In truth, the HTTP API is more complex.
As Ontime uses the HTTP API to manage its data, this changes often.

You can follow the code for a more up-to-date reference: Get data from Ontime Control Ontime

State

The following endpoints allow querying Ontime for its current state

Get Ontime version

Request

GET <localhost:4001>/api/version

Response

{"payload":"3.0.0"}

Get Ontime runtime state

Request

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

Address	Description
/data/custom-fields	Get registered custom fields
/data/db	Get currently loaded project file
/data/http	Get HTTP integration settings
/data/osc	Get OSC integration settings
/data/project	Get current project data
/data/rundown	Get current rundown
/data/settings	Get current application settings
/data/url-presets	Get currently defined URL Presets
/data/view-settings	Get currently defined settings for views

Change event

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.

Property	Value type
title	string
note	string
cue	string (value should be kept under 8 characters)
isPublic	boolean
skip	boolean
colour	string (# hex colour or named css colour)
custom	target the specific custom field with custom:<fieldname>
timeWarning	number (in seconds)
timeDanger	number (in seconds)
endAction	string (none / load-next / play-next / stop)
timerType	string (count-down / count-up / time-to-end / clock / none)
duration	number (in seconds)
timeStart	number (in seconds)
timeEnd	number (in seconds)

Caution

Changing the properties skip endAction duration timeStart timeEnd
cause the rundown to be recalculated and writing to them are therefor therefor throttled

Example: change title of event

Request

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

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

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

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

GET <localhost:4001>/api/start

Response

{"payload":"success"}

Start event at index

Request

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

Response

{"payload":"success"}

Start event with ID

Request

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

Response

{"payload":"success"}

Start event with cue

Request

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

Response

{"payload":"success"}

Start next event

Request

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

Response

{"payload":"success"}

Start previous event

Request

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

Response

{"payload":"success"}

Pause running timer

Request

GET <localhost:4001>/api/pause

Response

{"payload":"success"}

Load event

Load event at index

Request

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

Response

{"payload":"success"}

Load event with ID

Request

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

Response

{"payload":"success"}

Load event with cue

Request

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

Response

{"payload":"success"}

Load next event

Request

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

Response

{"payload":"success"}

Load previous event

Request

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

Response

{"payload":"success"}

Reload current event

Request

GET <localhost:4001>/api/reload

Response

{"payload":"success"}

Stop playback

Request

GET <localhost:4001>/api/stop

Response

{"payload":"success"}

Activate Roll mode

Request

GET <localhost:4001>/api/roll

Response

{"payload":"success"}

User added time

Add time

Request

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

Response

{"payload":"success"}

Remove time

Request

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

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

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

Set auxiliary timer to count down

Request

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

Start auxiliary timer

Request

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

Pause auxiliary timer

Request

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

Stop auxiliary timer

Request

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