Overview

Fire effects and manual triggers on a running Sub Control from your own backend.

The server forwards your HTTPS requests to the Sub Control desktop app over a WebSocket and returns the app's response. The app needs to be open and on to receive commands via API.

Base URL for every path in these docs:

https://apidrop.kinkyraven.com/api/v1

Send request bodies as JSON. API errors use an error code and may include a message. Check the code when handling errors. See Errors for response details.

What you can do

  • List the user's effect library and fire a library effect for a number of seconds, or until stopped.
  • List the user's manual triggers and fire, stop or clear them. These run through the app's own rules engine, so cooldowns, chances and lifetimes apply exactly as if the user pressed the button.
  • Do the same to a friend, but only with the triggers that friend set up, and only where they have allowed the key's owner control.
  • Check whether the user's app is online and which of their computers to target.

Friend calls can only fire the friend's manual triggers. Direct effect calls cannot fire Clear, always-on-top Strobe Clear, or browser effects. See Errors for the error codes.

Before the first call

  1. The user creates an API key in the app under Settings → Integrations → API and gives it to you. The key is shown once. Store it per user.
  2. The user's account needs an active supporter subscription from account.kinkyraven.com. Verified creators pass without one.
  3. Sign in to the app and switch on Online connection under Settings → Advanced → Online features.
  4. To fire anything, an effects session must be running in the app.

GET /relay/me checks the key and reports subscription status without requiring a subscription. GET /relay/online reports connected devices. Trigger calls also check that the app has an active effects session.

Walkthrough

KEY="sc_p9Qw..."
BASE="https://apidrop.kinkyraven.com/api/v1"

# Check the account, subscription and rate limits.
curl -s "$BASE/relay/me" -H "Authorization: Bearer $KEY"
# 200 {"user": {...}, "patreon": {"active": true}, "rate_limits": {...}}

# Is the app reachable, and on which computer?
curl -s "$BASE/relay/online" -H "Authorization: Bearer $KEY"
# 200 {"online": true, "clients": [{"client_id": "d4e5...", "name": "Gaming PC", "online": true}]}

# Which manual triggers can I fire?
curl -s "$BASE/relay/rules" -H "Authorization: Bearer $KEY"
# 200 {"rules": [{"id": "r_9f2...", "name": "Bubbles"}]}

# Fire one trigger. Reuse this key when retrying this request.
curl -s -X POST "$BASE/relay/rules/trigger" \
	-H "Authorization: Bearer $KEY" \
	-H "Content-Type: application/json" \
	-H "Idempotency-Key: evt_01JXYZ123" \
	-d '{"rule_id": "r_9f2..."}'
# 200 {"ok": true, "rule_id": "r_9f2...", "fired": true}

# Stop this trigger's effects.
curl -s -X POST "$BASE/relay/rules/stop" \
	-H "Authorization: Bearer $KEY" \
	-H "Content-Type: application/json" \
	-d '{"rule_id": "r_9f2..."}'
# 200 {"ok": true, "rule_id": "r_9f2..."}

Use manual triggers when the user should choose the effects and durations. Your integration chooses which trigger to fire and when. Use library effects when your integration needs to choose an effect and its duration.

API reference

  • Authentication covers keys, subscription requirements and rate limits.
  • Endpoints lists every route, plus how targeting and idempotency work.
  • Errors is the full code list, grouped by the server, relay and app.