AxyraBot logo
AxyraBot

API Documentation

All endpoints accept and return JSON. POST requests require Content-Type: application/json. Query parameters must be URL-encoded. All endpoints support CORS.

Channel Management

  • POST/joinJoin the bot to a channel. Body: { "login": "channelname" }. Returns 200 ok.
  • POST/partRemove the bot from a channel. Body: { "login": "channelname" }. Returns 200 ok.
  • GET/channelsReturns all channels the bot has joined. Response: { "channels": ["login", ...] }.

Stream Info & Updates

  • GET/stream/infoQuery: login (required). Returns the channel's current stream title and category from Twitch. Response: { "title": "...", "category": "..." }.
  • POST/stream/updateUpdate stream title and/or category. The backend resolves the category name to a Twitch game ID automatically. Body: { "login": "channel", "title": "...", "category": "..." }. Returns 204 No Content.
  • GET/categories/searchSearch Twitch categories/games. Query: q (search term, required), login (required for auth lookup). Response: { "data": [{ "id": "...", "name": "...", "box_art_url": "..." }, ...] }.

Commands API

Default Commands

  • GET/commands/default-settingsQuery: login (required). Returns all built-in commands and their enabled state. Rows missing from the DB default to enabled. Response: { "commands": [{ "name": "!watchtime", "enabled": true }, ...] }.
  • POST/commands/default-settingsEnable or disable a single default command. Body: { "login": "channel", "command": "!watchtime", "enabled": false }.

Custom Commands

  • GET/commands/customQuery: login (required). Response: { "commands": [{ "name": "!hug", "response": "...", "createdBy": "user", "enabled": true, "role": "all" }, ...] }.
  • POST/commands/customToggle a custom command on or off. Body: { "login": "channel", "command": "!hug", "enabled": true }.
  • POST/commands/custom/updateRename a command, change its response, or update its permission level. Body: { "login": "channel", "originalCommand": "!hug", "command": "!hug", "response": "...", "role": "all | broadcaster | moderator | vip" }.
  • POST/commands/custom/deletePermanently delete a custom command. Body: { "login": "channel", "command": "!hug" }.
  • POST/commands/importBulk-import commands from an external provider (e.g. Nightbot). Body: { "login": "channel", "provider": "nightbot", "commands": [{ "name": "!cmd", "response": "..." }, ...] }. Response: { "imported": 5, "provider": "nightbot" }.

Moderation

Blocked Terms

  • GET/moderation/blocked-termsQuery: login (required). Response: { "terms": [{ "id": 1, "term": "badword", "action": "delete | timeout", "timeout_seconds": 60 }, ...] }.
  • POST/moderation/blocked-termsAdd a blocked term. action must be delete or timeout. When using timeout, set timeout_seconds (1–1209600). Body: { "login": "channel", "term": "badword", "action": "timeout", "timeout_seconds": 300 }. Response: { "id": 1 }.
  • POST/moderation/blocked-terms/deleteRemove a blocked term by ID. Body: { "login": "channel", "id": 1 }.

Roles

Roles let broadcasters grant users elevated permissions within AxyraBot. Available roles: Editor, Mod, Regular. Editors can manage a broadcaster's dashboard on their behalf.

  • GET/rolesQuery: login (required). Returns all role assignments for the channel. Response: { "roles": [{ "id": 1, "username": "someuser", "role": "Editor" }, ...] }.
  • POST/rolesAdd or update a user's role (upserts on username). Body: { "login": "channel", "username": "someuser", "role": "Editor" }. Response: { "id": 1 }.
  • POST/roles/deleteRemove a role assignment by ID. Body: { "login": "channel", "id": 1 }.
  • GET/roles/editor-channelsQuery: login (required). Returns all channels where the given username has the Editor role. Response: { "channels": ["broadcaster1", ...] }.

Modules

  • GET/modules/settingsQuery: login (required). Returns all module configurations for the channel. Response: { "modules": [{ "name": "live_announcement", "label": "Go live announcement", "description": "...", "enabled": true, "message": "..." }, ...] }.
  • POST/modules/settingsEnable/disable a module or update its message template. Set resetToDefault: true to clear any custom message and restore the default. Body: { "login": "channel", "module": "live_announcement", "enabled": true, "message": "...", "resetToDefault": false }.

Birthdays

  • GET/birthdays/listQuery: login (required). Returns all stored birthdays for the channel. Response: { "birthdays": [{ "userLogin": "user", "displayName": "User", "month": 3, "day": 14 }, ...] }.
  • GET/birthdays/settingsQuery: login (required). Returns the channel's birthday announcement timezone. Response: { "timezone": "America/New_York" }.
  • POST/birthdays/settingsUpdate the birthday timezone (must be a valid IANA timezone string). Body: { "login": "channel", "timezone": "America/Chicago" }.
  • GET/birthdays/command-messagesQuery: login (required). Returns the custom message templates for birthday commands. Response: { "commands": [{ "name": "!birthday", "message": "..." }, ...] }.
  • POST/birthdays/command-messagesUpdate a birthday command message. Set resetToDefault: true to restore the built-in message. Body: { "login": "channel", "command": "!birthday", "message": "...", "resetToDefault": false }.

User

  • GET/user/avatarQuery: login (required). Returns the Twitch profile picture URL for any user. Response: { "avatar_url": "https://static-cdn.jtvnw.net/..." }.

Audit Logs

  • GET/audit/logsQuery: login (required), limit (optional integer, max 100, default 20). Returns recent activity events for a channel ordered by most recent first. Response: { "logs": [{ "source": "twitch", "category": "stream", "description": "...", "timestamp": "2026-01-01T00:00:00Z" }, ...] }.

Template Variables

Variables can be used in custom command responses and module message templates. The bot substitutes them at runtime when a command fires or an event triggers.

Custom Commands

  • $(user)Login of the user who triggered the command.
  • $(channel)The broadcaster's login for the channel where the command ran.
  • $(touser)The argument after the command (e.g. !hug @someUser → someUser). Falls back to $(user) if no argument is given.
  • $(random.chatter)A random viewer currently in chat. Falls back to a recent-chatter cache, then to $(user) if none are available.
  • $(count)A per-command counter that increments each time that command is used in a channel.

Live Announcement Module

  • $(channel)The broadcaster's login.
  • $(title)Current stream title. Falls back to Untitled stream if empty.
  • $(game)Current Twitch category/game. Falls back to Just Chatting if empty.