{ "openapi": "3.1.0", "info": { "title": "NEXUS Bot API", "version": "2.2.0", "description": "NEXUS Bot Developer Platform API: OAuth2, scoped API keys, slash commands, interactions, embeds, moderation, channels, roles, files, reactions, voice state and resumable WebSocket Gateway." }, "servers": [ { "url": "/api/v1" } ], "components": { "securitySchemes": { "BotToken": { "type": "http", "scheme": "bearer", "bearerFormat": "nx_bot_...", "description": "Authorization: Bot nx_bot_... (full bot token) or Bot nx_key_... (scoped API key)." }, "OAuth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "/oauth2/authorize.php", "tokenUrl": "/api/oauth2/token.php", "scopes": { "identify": "Read user identity", "guilds": "Read user's guilds", "guilds.join": "Join user to a guild" } } } } }, "schemas": { "Embed": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 256 }, "description": { "type": "string", "maxLength": 4096 }, "url": { "type": "string", "format": "uri" }, "color": { "type": "integer", "minimum": 0, "maximum": 16777215 }, "fields": { "type": "array", "maxItems": 25, "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "inline": { "type": "boolean" } } } } } }, "ActionRow": { "type": "object", "properties": { "type": { "const": "action_row" }, "components": { "type": "array", "maxItems": 5, "items": { "type": "object" } } } } } }, "paths": { "/bot/me.php": { "get": { "summary": "Get current bot application", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ] } }, "/bot/guilds.php": { "get": { "summary": "List installed guilds", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ] } }, "/bot/channels.php": { "get": { "summary": "List guild channels", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "parameters": [ { "name": "server_id", "in": "query", "required": true, "schema": { "type": "integer" } } ] }, "post": { "summary": "Create guild channel", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "server_id", "name" ], "properties": { "server_id": { "type": "integer" }, "name": { "type": "string" }, "type": { "enum": [ "text", "voice", "announcement" ] }, "category_id": { "type": [ "integer", "null" ] }, "topic": { "type": "string" }, "slowmode_seconds": { "type": "integer" }, "is_nsfw": { "type": "boolean" } } } } } } }, "patch": { "summary": "Edit guild channel", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "channel_id" ], "properties": { "channel_id": { "type": "integer" }, "name": { "type": "string" }, "category_id": { "type": [ "integer", "null" ] }, "topic": { "type": "string" }, "slowmode_seconds": { "type": "integer" }, "is_nsfw": { "type": "boolean" } } } } } } }, "delete": { "summary": "Delete guild channel", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "channel_id" ], "properties": { "channel_id": { "type": "integer" } } } } } } } }, "/bot/members.php": { "get": { "summary": "List guild members", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "parameters": [ { "name": "server_id", "in": "query", "required": true, "schema": { "type": "integer" } } ] } }, "/bot/messages.php": { "get": { "summary": "List channel messages", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "parameters": [ { "name": "channel_id", "in": "query", "required": true, "schema": { "type": "integer" } } ] }, "post": { "summary": "Create rich message", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "channel_id": { "type": "integer" }, "content": { "type": "string" }, "embeds": { "type": "array", "items": { "$ref": "#/components/schemas/Embed" } }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/ActionRow" } }, "reply_to": { "type": [ "integer", "null" ] } }, "required": [ "channel_id" ] } } } }, "description": "Supports content, rich embeds, buttons/select menus, and replies." } }, "/bot/message.php": { "patch": { "summary": "Edit bot message", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message_id": { "type": "integer" }, "content": { "type": "string" } }, "required": [ "message_id" ] } } } } }, "delete": { "summary": "Delete message", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message_id": { "type": "integer" } }, "required": [ "message_id" ] } } } } } }, "/bot/commands.php": { "get": { "summary": "List global slash commands", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ] }, "put": { "summary": "Bulk upsert global slash commands", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "options": { "type": "array", "items": { "type": "object" } } }, "required": [ "name", "description" ] } } } } } } }, "/bot/command_permissions.php": { "get": { "summary": "Get guild command permission rules", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "parameters": [ { "name": "server_id", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "command_id", "in": "query", "required": true, "schema": { "type": "integer" } } ] }, "put": { "summary": "Replace guild command permission rules", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/bot/interactions.php": { "post": { "summary": "Respond to command/component/modal interaction", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "interaction_id": { "type": "string" }, "type": { "enum": [ "channel_message", "update_message", "modal", "deferred" ] }, "data": { "type": "object" } }, "required": [ "interaction_id", "type" ] } } } } } }, "/bot/presence.php": { "post": { "summary": "Update bot presence", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "online", "idle", "dnd", "offline" ] }, "activity": { "type": "object", "properties": { "type": { "enum": [ "playing", "listening", "watching", "competing", "custom" ] }, "name": { "type": "string" } } } } } } } } } }, "/bot/gateway.php": { "get": { "summary": "HTTP event-feed fallback", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "parameters": [ { "name": "after", "in": "query", "schema": { "type": "integer" } }, { "name": "intents", "in": "query", "schema": { "type": "integer" } } ] } }, "/oauth2/me.php": { "get": { "summary": "Get OAuth2 user identity", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limited" } }, "security": [ { "OAuth2": [] } ] } }, "/oauth2/guilds.php": { "get": { "summary": "Get OAuth2 user guilds", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limited" } }, "security": [ { "OAuth2": [] } ] } }, "/bot/webhooks.php": { "get": { "summary": "List incoming webhooks", "security": [ { "BotToken": [] } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limited" } } }, "post": { "summary": "Create incoming webhook", "security": [ { "BotToken": [] } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limited" } } }, "delete": { "summary": "Delete incoming webhook", "security": [ { "BotToken": [] } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limited" } } } }, "/oauth2/guilds_join.php": { "post": { "summary": "Add the authorized user to a guild where the application is installed", "security": [ { "OAuth2": [ "guilds.join" ] } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limited" } } } }, "/bot/roles.php": { "get": { "summary": "List guild roles", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "parameters": [ { "name": "server_id", "in": "query", "required": true, "schema": { "type": "integer" } } ] }, "post": { "summary": "Create role or assign/remove a role", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "server_id" ], "properties": { "server_id": { "type": "integer" }, "action": { "enum": [ "create", "assign", "remove" ] }, "name": { "type": "string" }, "color": { "type": "string" }, "permissions": { "type": "integer" }, "role_id": { "type": "integer" }, "user_id": { "type": "integer" } } } } } } }, "patch": { "summary": "Edit guild role", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "server_id", "role_id" ], "properties": { "server_id": { "type": "integer" }, "role_id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": "string" }, "permissions": { "type": "integer" } } } } } } }, "delete": { "summary": "Delete guild role", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "server_id", "role_id" ], "properties": { "server_id": { "type": "integer" }, "role_id": { "type": "integer" } } } } } } } }, "/bot/moderation.php": { "post": { "summary": "Kick, ban, timeout or change nickname", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "server_id", "user_id", "action" ], "properties": { "server_id": { "type": "integer" }, "user_id": { "type": "integer" }, "action": { "enum": [ "kick", "ban", "unban", "timeout", "untimeout", "nickname" ] }, "reason": { "type": "string" }, "minutes": { "type": "integer" }, "nickname": { "type": "string" } } } } } }, "description": "Role hierarchy and live bot permissions are enforced server-side." } }, "/bot/reactions.php": { "post": { "summary": "Add bot reaction", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message_id", "emoji" ], "properties": { "message_id": { "type": "integer" }, "emoji": { "type": "string" } } } } } } }, "delete": { "summary": "Remove bot reaction", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message_id", "emoji" ], "properties": { "message_id": { "type": "integer" }, "emoji": { "type": "string" } } } } } } } }, "/bot/files.php": { "post": { "summary": "Send message with files", "description": "Multipart upload, up to 5 files. Requires Send Messages + Attach Files.", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "channel_id", "files" ], "properties": { "channel_id": { "type": "integer" }, "content": { "type": "string" }, "reply_to": { "type": [ "integer", "null" ] }, "files": { "type": "array", "maxItems": 5, "items": { "type": "string", "format": "binary" } } } } } } } } }, "/bot/voice.php": { "get": { "summary": "List visible voice states", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "parameters": [ { "name": "server_id", "in": "query", "required": true, "schema": { "type": "integer" } } ] }, "post": { "summary": "Join, update or leave bot voice state", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Rate limited" } }, "security": [ { "BotToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "properties": { "action": { "enum": [ "join", "state", "leave" ] }, "channel_id": { "type": "integer" }, "is_muted": { "type": "boolean" }, "is_deafened": { "type": "boolean" }, "speaking": { "type": "boolean" } } } } } } } }, "/bot/secrets.php": { "get": { "summary": "Read encrypted application secrets at runtime", "description": "Returns all application secrets or one name. Scoped API keys require secrets.read. Values are encrypted at rest and require NEXUS_BOT_SECRET_KEY on the server.", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "description": "Rate limited" }, "503": { "description": "Secret Vault unavailable" } }, "security": [ { "BotToken": [] } ], "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "type": "string" } } ] } } }, "x-nexus-gateway": { "protocol": "WebSocket", "opcodes": { "0": "DISPATCH", "1": "HEARTBEAT", "2": "IDENTIFY", "6": "RESUME", "9": "INVALID_SESSION", "10": "HELLO", "11": "HEARTBEAT_ACK" }, "features": [ "sequence", "resume", "intents", "sharding", "heartbeat ACK", "private-channel filtering", "message-content redaction", "interaction targeting", "credential IP allowlist" ], "intents": { "1": "GUILDS", "2": "GUILD_MEMBERS", "4": "GUILD_MESSAGES", "8": "MESSAGE_CONTENT", "16": "INTERACTIONS", "32": "PRESENCES", "64": "VOICE_STATES", "128": "GUILD_REACTIONS" } } }