API and integrations

Every room has an HTTP API. Start and stop timers, show messages, add time and read the rundown from a script, a show control system or anything that can make a web request. A webhook tells your system when a timer starts or ends.

Get started

The API runs the same room as the control room: a call from your tool shows on every screen at once.

Requests

Every call is https://cliqer.io/api/timer/v1/<room>/<action>. GET, POST, PUT and PATCH all work. Parameters go in the query string, or in a JSON body on POST, PUT and PATCH; the body wins when both have one. Dashes in the action name work too, so add-time is add_time. /api/timer/v0/ takes the same calls.

Send the key in one of these, checked in this order:

curl -X POST https://cliqer.io/api/timer/v1/<room>/add_time \
  -H "Authorization: Bearer $CLIQER_KEY" \
  -H "content-type: application/json" \
  -d '{"timer_id": "<timer>", "amount": "2m"}'

const res = await fetch('https://cliqer.io/api/timer/v1/<room>/add_time', {
  method: 'POST',
  headers: { 'authorization': `Bearer ${process.env.CLIQER_KEY}`, 'content-type': 'application/json' },
  body: JSON.stringify({ timer_id: '<timer>', amount: '2m' }),
})
const { ok, message, data } = await res.json()

import os, requests

r = requests.post(
    "https://cliqer.io/api/timer/v1/<room>/add_time",
    headers={"Authorization": f"Bearer {os.environ['CLIQER_KEY']}"},
    json={"timer_id": "<timer>", "amount": "2m"},
)
print(r.json())

Keys and permissions

Your account API key can do everything on rooms you own. A room can also hold its own keys, each with some of three permissions:

A call that needs a permission the key lacks gets 401. A room key's secret is shown once, when it is made. Using the API at all needs the API in your plan, see Plans and limits.

Actions

timer_id picks a timer by its id; index picks it by position, counting from 1. When both are sent, timer_id wins. Leave both out to act on the current timer.

Amounts are 30s, 5m, 1h, 250ms, or a bare number of seconds. seconds works in place of amount, and a minus sign goes backwards. Switches like on, autostart and replace read 0, false, off and no as off and anything else as on. Leave on out of blackout to toggle it.

Responses

Every answer is JSON: {"ok": true, "message": "<action>", "data": ...} on success, {"ok": false, "message": "...", "code": "..."} on failure.

Rate limit: 100 calls a minute per key; calls without a key count per address. Each answer carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the minute starts again).

Webhooks

The body is {"event", "roomId", "timestamp", "payload"}. The x-cliqer-timestamp header holds the Unix time in seconds, and x-cliqer-signature holds sha256= and the hex HMAC-SHA256 of <timestamp>.<body> keyed with your secret.

# Recompute the signature of a saved body.
printf '%s.%s' "$TIMESTAMP" "$(cat body.json)" \
  | openssl dgst -sha256 -hmac "$WHSEC" -hex

import { createHmac, timingSafeEqual } from 'node:crypto'

export function verify(rawBody: string, timestamp: string, signature: string, secret: string) {
  const want = `sha256=${createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex')}`
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300
  return fresh && want.length === signature.length && timingSafeEqual(Buffer.from(want), Buffer.from(signature))
}

import hashlib, hmac, time

def verify(raw_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    mac = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256)
    fresh = abs(time.time() - int(timestamp)) < 300
    return fresh and hmac.compare_digest("sha256=" + mac.hexdigest(), signature)

Sign the raw body exactly as it arrived, before any JSON parsing. The five minute window is your choice; it stops an old request being replayed.

Delivery is one try with a 5 second timeout. Redirects are not followed, and an address that resolves to a private network is dropped. If a missed event matters, read get_status to catch up.

Short links

GET https://cliqer.io/api/timer/link/<code> turns a short link code into its room: {"ok": true, "data": {"roomId", "link"}}, or 404 Link not found for an unknown, revoked or expired code or a wrong password. For a link with a password, send it in the x-link-password header, never in the address.

Companion and Stream Deck

There is no Companion module or Stream Deck plugin for Cliqer Timer rooms yet. Bitfocus Companion's Generic HTTP module can call the actions above. The Cliqer desktop app's own timer has its REST API and Stream Deck support, see Timer (desktop) and Host timer.

FAQ

Next