API Documentation

Use the Stagemonitor API to control your monitors programmatically.

Authentication

All API requests require your project ID. This ID is shown in your admin panel and serves as your API key.

Important: Keep your project ID secret. Anyone with access to it can control your Stagemonitor.

Base URL

https://stagemonitor.app/api/v2/

Endpoints

GET Set Countdown

Set a new countdown timer.

URL

/api/v2/countdown/?id={PROJECT_ID}&hh={HOURS}&mm={MINUTES}&ss={SECONDS}

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Your project ID
`hh`	integer	Yes	Hours (0-23)
`mm`	integer	Yes	Minutes (0-59)
`ss`	integer	Yes	Seconds (0-59)
`redir`	boolean	No	Set to "true" to redirect back to referrer

Example

# Set a 10 minute countdown
GET https://stagemonitor.app/api/v2/countdown/?id=abc123def456&hh=0&mm=10&ss=0

# Response
{"success": true, "message": "Countdown updated"}
            

GET Get Countdown Display

Get the current countdown value formatted for display.

URL

/api/v2/countdown/get.php?id={PROJECT_ID}

Response

Returns plain text with the countdown in HH:MM:SS format.

Example

GET https://stagemonitor.app/api/v2/countdown/get.php?id=abc123def456

# Response (plain text)
00:09:45
            

GET Set Note/Message

Set a note or message to display on the monitor.

URL

/api/v2/note/?id={PROJECT_ID}¬e={MESSAGE}

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Your project ID
`note`	string	Yes	The message to display (URL encoded)

Example

# Set a note
GET https://stagemonitor.app/api/v2/note/?id=abc123def456¬e=Welcome%20to%20the%20event

# Response
{"success": true, "message": "Note updated"}

# Clear the note
GET https://stagemonitor.app/api/v2/note/?id=abc123def456¬e=
            

GET Get Note

Get the current note/message.

URL

/api/v2/note/get.php?id={PROJECT_ID}

Response

Returns plain text with the current note.

Example

GET https://stagemonitor.app/api/v2/note/get.php?id=abc123def456

# Response (plain text)
Welcome to the event
            

Integration Examples

Bitfocus Companion

Use the "HTTP Generic" module with GET requests:

# Button for 5 minute countdown
https://stagemonitor.app/api/v2/countdown/?id=YOUR_PROJECT_ID&hh=0&mm=5&ss=0

# Button for 10 minute countdown
https://stagemonitor.app/api/v2/countdown/?id=YOUR_PROJECT_ID&hh=0&mm=10&ss=0

# Button to set message "LIVE"
https://stagemonitor.app/api/v2/note/?id=YOUR_PROJECT_ID¬e=LIVE

# Button to clear message
https://stagemonitor.app/api/v2/note/?id=YOUR_PROJECT_ID¬e=
        

cURL

# Set 15 minute countdown
curl "https://stagemonitor.app/api/v2/countdown/?id=YOUR_PROJECT_ID&hh=0&mm=15&ss=0"

# Set note
curl "https://stagemonitor.app/api/v2/note/?id=YOUR_PROJECT_ID¬e=Starting%20soon"
        

JavaScript/Fetch

// Set countdown
fetch('https://stagemonitor.app/api/v2/countdown/?id=YOUR_PROJECT_ID&hh=0&mm=10&ss=0')
  .then(r => r.json())
  .then(console.log);

// Set note
fetch('https://stagemonitor.app/api/v2/note/?id=YOUR_PROJECT_ID¬e=' + encodeURIComponent('Hello World'))
  .then(r => r.json())
  .then(console.log);
        

Python

import requests

PROJECT_ID = "YOUR_PROJECT_ID"

# Set countdown
requests.get(f"https://stagemonitor.app/api/v2/countdown/?id={PROJECT_ID}&hh=0&mm=10&ss=0")

# Set note
requests.get(f"https://stagemonitor.app/api/v2/note/?id={PROJECT_ID}¬e=Starting%20soon")
        

WebSocket API

For real-time updates, connect to our WebSocket server:

ws://stagemonitor.app:8080

Subscribe to a project

// Connect and subscribe
const ws = new WebSocket('ws://stagemonitor.app:8080');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'subscribe',
    projectId: 'YOUR_PROJECT_ID',
    role: 'viewer'  // or 'admin' for sending updates
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'update') {
    console.log('Update:', data.updateType, data.value);
  }
};
        

Rate Limits

There are no strict rate limits, but please be reasonable. Recommended:

Countdown updates: Max 1 per second
Note updates: Max 1 per second
Polling: Max 1 request per second per client

Error Responses

HTTP Code	Meaning
`400`	Bad Request - Missing required parameters
`403`	Forbidden - Project has expired
`404`	Not Found - Project does not exist

Need help? Contact us at stagemonitor@oclin.no