The Quadraviz API

TL;DR — https://api.quadraviz.com/v1, authenticated with Authorization: Bearer qv_…. Read what's on air, play scenes, fire triggers, set values.

#Before you start

You need an API key. Every request carries it as a bearer token:

bash

curl https://api.quadraviz.com/v1/whoami \
  -H "Authorization: Bearer qv_YOUR_KEY"

The base URL is versioned from day one. /v1 will keep behaving the way it does today, so anything you wire into a rack stays wired.

#Start with whoami

GET /whoami

Returns what the key is and what it may do:

json

{
  "orgId": "org_7f3a…",
  "role": "operator",
  "scopes": ["read", "control"],
  "channelId": "chan_91b2…"
}

Worth making this the first call in any integration. A misconfigured panel then tells you this key can't control on startup, instead of failing on a button press twenty minutes into a show. An empty channelId means the key can act on every channel.

#Reading

All of these need the read permission.

#List your channels

GET /channels

json

{
  "channels": [
    {
      "id": "chan_91b2…",
      "name": "Studio A",
      "format": "1920x1080",
      "liveSceneId": "scn_4d1c…",
      "previewSceneId": "scn_88fa…",
      "viewers": 2
    }
  ]
}

viewers is how many outputs are connected right now — the fastest answer to is anything actually showing this? A key locked to one channel sees only that channel.

GET /channels/:id returns one of these.

#Read what is on air

GET /channels/:id/state
GET /channels/:id/state?mode=preview

json

{
  "channelId": "chan_91b2…",
  "mode": "live",
  "sceneId": "scn_4d1c…",
  "viewers": 2,
  "binds": {
    "lowerThird/name": "Jordan Vale",
    "lowerThird/role": "Analyst"
  }
}

The values come back resolved exactly as a connecting overlay would resolve them, Smart Inputs included. That is what makes it usable for feedbacks: a button that lights up when a lower third is showing is reading the same value the graphic is.

#Scenes and animations

GET /scenes
GET /animations

Scenes come back as id and name. Animations come back with the trigger names they respond to — which is exactly the list a control surface needs to lay out as buttons.

#Controlling

All of these need the control permission, and all of them are POST.

Each takes a target of "live" or "preview".

#Play

bash

curl -X POST https://api.quadraviz.com/v1/channels/$CHANNEL/play \
  -H "Authorization: Bearer $KEY"

Takes what is cued in preview to air. Same as pressing Play in the controller, auto-play events included.

Optionally fire triggers as it goes:

json

{ "autoplay": [{ "name": "showIn", "type": 0 }] }

#Load a scene

bash

curl -X POST https://api.quadraviz.com/v1/channels/$CHANNEL/scene \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"sceneId": "scn_88fa…", "target": "preview"}'

#Fire a trigger

bash

curl -X POST https://api.quadraviz.com/v1/channels/$CHANNEL/trigger \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"bind": "showIn", "target": "live"}'

Use the names from GET /animations.

#Set a value

bash

curl -X POST https://api.quadraviz.com/v1/channels/$CHANNEL/bind \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"bind": "lowerThird/name", "text": "Jordan Vale", "target": "live"}'

Send text for text, boolean for a toggle.

#When something goes wrong

Every failure has the same shape:

json

{
  "error": {
    "code": "missing_scope",
    "message": "This API key does not have the 'control' permission."
  }
}

Branch on code, not on the message. Messages get reworded; codes don't.

Status	Code	What it means
401	`unauthorized`	No key, a malformed header, or one we don't recognise.
401	`key_revoked`	Someone revoked it. Make a new one.
401	`key_expired`	It passed its expiry date.
403	`missing_scope`	The key lacks the permission this endpoint needs.
403	`wrong_channel`	The key is locked to a different channel. Check your wiring.
404	`not_found`	No such channel in this organisation.
400	`bad_request`	A required field is missing. The message names it.
400	`bad_target`	`target` must be `live` or `preview`.
400	`request_failed`	The channel couldn't do this — usually nothing is cued.
503	`unavailable`	We couldn't verify the key. Retry; don't rotate the key.

A 404 on a channel means "not in this organisation" as well as "doesn't exist" — we don't confirm that somebody else's channel exists.

#A working example

Confirm the key, find a channel, put its cued scene on air:

bash

BASE=https://api.quadraviz.com/v1
AUTH="Authorization: Bearer $KEY"

curl -s $BASE/whoami -H "$AUTH"
curl -s $BASE/channels -H "$AUTH"
curl -s -X POST $BASE/channels/$CHANNEL/play -H "$AUTH"

#Next steps

Webhooks — Have us call you when something changes
API keys — Permissions and channel locks