NexusGuild API Documentation

Welcome to the NexusGuild developer documentation. Here you'll find everything needed to build bots that interact with NexusGuild servers, or to build a custom NexusGuild client.

🤖
Bot REST API
Send messages, manage roles, pin messages, react to content, and more using HTTP requests authenticated with your bot token.
⚡
Bot Gateway
Connect via Socket.io to receive real-time events — messages, member joins, channel changes, and slash command interactions.
đŸ’ģ
Client Guide
Build a first-party NexusGuild client. Learn the session auth flow, socket events, message format, and full REST API surface.
🔐
Permissions
Discord-compatible bitwise permission flags. Full reference with bit values, names, and what each permission controls.

Overview

Base URL

All REST API endpoints are relative to the NexusGuild server base URL:

https://nexusguild.gg

Two API Surfaces

NexusGuild exposes two separate API surfaces depending on your use case:

SurfaceAuth MethodBase PathUse For
Bot REST API Authorization: Bot TOKEN /api/v1 Bot integrations, automation, slash commands
Client REST API Session cookie (express-session) /api Building a NexusGuild client application

Bot Gateway

Real-time events for bots are delivered over a Socket.io namespace at /bot-gateway. Authenticate with your bot token on connection. See the Gateway docs.

IDs & Snowflakes

All entity IDs in NexusGuild — users, servers, channels, messages, roles — are Snowflake IDs: 64-bit integers encoded as strings (VARCHAR(20)). Always treat IDs as strings, never as JavaScript numbers (which lose precision above 53 bits).

ℹī¸
IDs are time-ordered. You can use before and after query params on paginated endpoints to cursor through results.

Snowflake Anatomy

BitsFieldDescription
63–22TimestampMilliseconds since NexusGuild epoch (2009-02-09T00:00:00Z)
21–17Worker IDInternal worker node
16–12Process IDInternal process
11–0IncrementSequence counter per millisecond

Standard Error Codes

All error responses follow the format: {"code": NUMBER, "message": "string"}

HTTPCodeMessage
40050006Cannot send an empty message
40050016Provide 1–100 message IDs (bulk delete)
40050035Invalid form body (missing required field)
40140001401: Unauthorized (missing/invalid token)
40350001Missing Access (bot not in server or channel)
40350003Cannot delete a message authored by another user
40350005Cannot edit a message authored by another user
40350013Missing Permissions
40410003Unknown Channel
40410004Unknown Guild
40410007Unknown Member
40410008Unknown Message
40410011Unknown Role
5000Internal server error

Rate Limits

⚠ī¸
Rate limiting is not yet enforced on NexusGuild API endpoints. Please be respectful — avoid hammering endpoints in tight loops. This will change in a future update.