HTTP API

Base URL

The structure of the base URL will be:

http://ip-address-of-host-machine:4001/api/project-id/

For all requests to H2R Graphics, use the following base url, as seen in the Launcher window.

For example…

If the Rundown URL is http://192.168.8.153:4001/rundown/ABCD/

The base URL is http://192.168.8.153:4001/api/ABCD/

Companion

Learn how to take full advantage of this API here: Companion module

Errors

If a request can’t be carried out, the API responds with an error rather than silently doing nothing. You’ll get an error response when:

• The project in the base URL doesn’t exist.
• The graphic ID doesn’t match a graphic in that project.
• The verb on an update request isn’t one the graphic understands.

This makes it much easier to debug an automation or a Companion button that isn’t behaving, as a failed request now tells you what went wrong instead of appearing to succeed.

URIs

Most HTTP methods below will rely on a URI and a JSON object.

Keep in mind that the fastest way to to this information is within the Rundown, by right-clicking on any graphic that you want to show/hide/update.

Run

POST http://base_url/run

Clear all graphics

POST http://base_url/clear

Show a graphic

POST http://base_url/graphic/<graphic-id>/show

Pro tip: Right-click any graphic on your rundown to Copy "Show" URI.

Hide a graphic

POST http://base_url/graphic/<graphic-id>/hide

Pro tip: Right-click any graphic on your rundown to Copy “Hide” URI.

Update contents of a graphic

POST http://base_url/graphic/<graphic-id>/update

body object

Pro tip: Right-click any graphic on your rundown to Copy "Update" URL and to Copy body JSON.

Update score graphic

POST http://base_url/graphic/<graphic-id>/updateScore/<team>/<level>/<type>/<amount>

• team is the number of the team, likely 1 or 2.
• level is the score to update. Likely 1, 2, 3 or 4.
• type is a string depending on how the score should change. Either set, up or down.
• amount is the number to set, increment or decrement to score by.

Example: graphic/1234/updateScore/1/1/up/10

This would affect team 1, level 1, and add 10 points to the score.

Text variables

Update Variable Text

POST http://base_url/updateVariableText/<variable-text-id>

Request Body

text String

Variable list

Select a row on a variable list

POST http://base_url/updateVariableList/1/selectRow/next

Replace next with previous or <number> to select a specific row.

Outputs

Open an output with HTTP

POST http://base_url/output/<output_number>/open

Path Parameters

output_number String - 1, 2, 3 or 4

Speaker Timer

Run/resume a Speaker Timer

POST http://base_url/graphic/<graphic_id>/timer/run

Pause a Speaker Timer

POST http://base_url/graphic/<graphic_id>/timer/pause

Reset a Speaker Timer to it’s original duration

POST http://base_url/graphic/<graphic_id>/timer/reset

Add/remove time from a running Speaker Timer

POST http://base_url/graphic/<graphic_id>/timer/jump/<amount_in_seconds>

• When paused the time will be added/removed from the duration.
• When playing the time will be added/removed from the active time left.

Path Parameters <amount_in_seconds> Number

• 10 would add 10 seconds.
• -10 would subtract 10 seconds.

Set the duration of the Speaker Timer and reset it.

POST http://base_url/graphic/<graphic_id>/timer/duration/<amount_in_seconds>

Lyrics

Next lyric

POST http://base_url/graphic/<graphic_id>/lyric/next

Previous lyric

POST http://base_url/graphic/<graphic_id>/lyric/previous

Back to the start

POST http://base_url/graphic/<graphic_id>/lyric/start