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

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)

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

<localhost:4001>/api/message/timer?secondarySource=aux

Request

<localhost:4001>/api/message/timer?secondarySource=external

Request

# 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

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

Request

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/id/<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

Add / remove time to auxiliary timer

Request

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