Custom API Documentation

API Overview

The BotOfTheSpecter API enables programmatic access to various bot features, allowing developers to build custom integrations, extensions, and applications that interact with the bot's functionality.

Authentication

All API requests require authentication using your unique API key.
This key is essential for all BotOfTheSpecter integrations, including API access, WebSocket server connections, and third-party platform integrations.

Obtaining Your API Key

1. Log in to the BotOfTheSpecter Dashboard
2. Navigate to Dashboard → Profile
3. Locate your API key in the "API Access" section of the Profile page

API Key Regeneration

If you believe your API key has been compromised:

1. Go to Dashboard → Profile
2. Click the regenerate button in the API Key section
3. Important: Regenerating your API key will require a full restart of all BotOfTheSpecter components (Twitch Chat Bot & Overlays). After regenerating you must restart those components via the dashboard.

Webhook Integrations

The API supports webhook integrations with various third-party services.
These integrations allow BotOfTheSpecter to receive real-time notifications from external platforms and trigger appropriate actions in your Twitch chat or stream overlays.

API Endpoints

BotOfTheSpecter's API provides several endpoints to interact with bot features.
Most public endpoints do not require authentication, but the webhook relays, WebSocket triggers, weather/sound data, and the commands listed below still expect your API key as a query parameter (e.g. ?api_key=YOUR_API_KEY).

Bot

• GET /versions — Fetch the beta, stable, and discord bot version numbers
• GET /chat-instructions — Return the AI system instructions used by the Twitch chat bot (?discord flag switches to the Discord-specific instructions file if present)
• GET /api/song — Get the number of remaining song requests for the current reset period
• GET /api/exchangerate — Retrieve the number of remaining exchange rate requests for the current reset period
• GET /api/weather — Retrieve the number of remaining weather API requests for the current day, as well as the time remaining until midnight

Commands

• GET /quotes — Retrieve a random quote from the database of quotes, based on a random author
• GET /fortune — Retrieve a random fortune from the database of fortunes
• GET /kill — Fetch kill command responses for various events.
• GET /joke — Fetch a random joke from a joke API, filtered to exclude inappropriate content.
• GET /sound-alerts — Retrieve a list of all sound alert files available for the authenticated user from the website server
• GET /weather — Retrieve current weather data for a given location and send it to the WebSocket server

Webhooks

• POST /fourthwall — This endpoint allows you to send webhook data from FOURTHWALL to be processed by the bot's WebSocket server
• POST /kofi — This endpoint allows you to receive KOFI webhook events and forward them to the WebSocket server
• POST /patreon — This endpoint allows you to send webhook data from Patreon to be processed by the bot's WebSocket server

WebSocket

Endpoints for interacting with the internal WebSocket server / triggering overlay events:

• GET /websocket/tts — Send a text-to-speech (TTS) event to the WebSocket server, allowing TTS to be triggered via API
• GET /websocket/walkon — Trigger the 'Walkon' event for a specified user via the WebSocket server. Supports .mp3 (audio) and .mp4 (video) walkons
• GET /websocket/deaths — Trigger the 'Deaths' event with custom death text for a game via the WebSocket server
• GET /websocket/sound_alert — Trigger a sound alert for the specified sound file via the WebSocket server
• GET /websocket/stream_online — Send a 'Stream Online' event to the WebSocket server to notify that the stream is live
• GET /websocket/stream_offline — Send a 'Stream Offline' event to the WebSocket server to notify that the stream is offline
• POST /SEND_OBS_EVENT — Send a 'OBS EVENT' to the WebSocket server to notify the system of a change in the OBS Connector

Heartbeats

• GET /heartbeat/websocket — Retrieve the current heartbeat status of the WebSocket server
• GET /heartbeat/api — Retrieve the current heartbeat status of the API server
• GET /heartbeat/database — Retrieve the current heartbeat status of the database server

Using the API

To use the BotOfTheSpecter API include your API key as a URL query parameter on every request.
Example: https://api.botofthespecter.com/quotes?api_key=YOUR_API_KEY.
Do not expose the key in public client-side code; treat it like a secret and rotate it if you suspect compromise.

curl "https://api.botofthespecter.com/quotes?api_key=YOUR_API_KEY"

fetch('https://api.botofthespecter.com/quotes?api_key=YOUR_API_KEY')
.then(r => r.json()).then(console.log);

import requests

resp = requests.get('https://api.botofthespecter.com/quotes?api_key=YOUR_API_KEY')
print(resp.json())

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.botofthespecter.com/quotes?api_key=YOUR_API_KEY');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

// Java 11+ HttpClient
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
	.uri(URI.create("https://api.botofthespecter.com/quotes?api_key=YOUR_API_KEY"))
	.GET()
	.build();
HttpResponse<String> resp = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());