Bot REST API

The Bot REST API lets your bot read and write data using standard HTTP requests. All endpoints live under /api/v1 and require a bot token header. Bots must be installed in a guild to access its channels and members.

Authentication

Every request to /api/v1 must include your bot token in the Authorization header:

Authorization: Bot YOUR_BOT_TOKEN

Bot tokens are 64-character hex strings generated when you create a bot through the developer portal. You can regenerate a token at any time — the old token immediately stops working.

Obtaining a Token

1. Log in to the NexusGuild developer portal
2. Create a new application under My Applications
3. Go to Bot → copy the token
4. To install the bot in a guild, use the invite link or call PUT /api/bots/:botId/servers/:serverId

Bot User

{
  "id":       "snowflake",
  "username": "MyBot",
  "avatar":   "/uploads/avatars/..." // or null,
  "bot":      true
}

Get Channel

{
  "id":        "snowflake",
  "type":      0, // 0=text 2=voice 4=category 5=announcement 11=thread 15=forum
  "guild_id":  "snowflake",
  "name":      "general",
  "topic":     "Channel topic" // or null,
  "position":  0,
  "parent_id": "snowflake" // category ID, or null
}

Get Channel Messages

[
  {
    "id":               "snowflake",
    "channel_id":       "snowflake",
    "author": {
      "id":       "snowflake",
      "username": "SomeUser",
      "avatar":   "/uploads/avatars/...",
      "bot":      false
    },
    "content":          "Hello world",
    "timestamp":        "2026-03-07T12:00:00.000Z",
    "edited_timestamp":  null,
    "attachments":      [],
    "embeds":           [],
    "pinned":           false,
    "type":             0
  }
]

Send Message

fetch(`/api/v1/channels/${channelId}/messages`, {
  method: 'POST',
  headers: {
    'Authorization': `Bot ${token}`,
    'Content-Type':  'application/json',
  },
  body: JSON.stringify({ content: 'Hello from my bot!' }),
})

Edit Message

Delete Message

Bulk Delete Messages

{ "messages": ["id1", "id2", "id3"] }

Add Reaction

Remove Reaction

Get Pinned Messages

Pin a Message

Unpin a Message

Get Guild

{
  "id":                       "snowflake",
  "name":                     "My Server",
  "icon":                     "/uploads/icons/..." // or null,
  "owner_id":                 "snowflake",
  "approximate_member_count":  42
}

Get Guild Channels

List Guild Members

[
  {
    "user": {
      "id":       "snowflake",
      "username": "Alice",
      "avatar":   "/uploads/avatars/...",
      "bot":      false
    },
    "nick":      null,
    "roles":     ["roleSnowflake"],
    "joined_at": "2026-01-01T00:00:00.000Z"
  }
]

Get Guild Member

List Guild Roles

[
  {
    "id":          "snowflake",
    "name":        "Moderator",
    "color":       3447003,       // integer RGB (e.g. 0x3498DB)
    "permissions": "8",           // permission bitmask as string
    "position":    2,
    "mentionable": false,
    "hoist":       false
  }
]

Create Role

Edit Role

Delete Role

Add Role to Member

Remove Role from Member

Managing Bots (Session Auth)

Slash Commands (Session Auth)

Register and manage slash commands per guild. Commands are sent to connected clients and trigger INTERACTION_CREATE gateway events when a user invokes them.

Slash Command Object

{
  "id":          "snowflake",
  "bot_id":      "snowflake",
  "server_id":   "snowflake",
  "name":        "ping",          // unique per bot+server
  "description": "Replies with pong",
  "options":      []               // array of command option objects (see below)
}

Command Options

Options define the arguments a slash command accepts. They are stored in the options array on the command object and shown as type hints in the chat input when a user types the command.

Option Object

Option Types

How arguments are passed to your bot

Users can provide arguments as key:value pairs (e.g. /roll sides:20) or positionally (e.g. /roll 20). The client parses these into typed option objects delivered in the data.options array of the INTERACTION_CREATE event:

// INTERACTION_CREATE data.options example
[
  { "name": "sides", "type": 4, "value": 20 }
]

Responding to Interactions

When a user invokes a slash command, your bot receives an INTERACTION_CREATE gateway event. You must respond within 3 seconds, or use a deferred response.

Immediate Response (Type 4)

{
  "type": 4,           // CHANNEL_MESSAGE_WITH_SOURCE
  "content": "Pong!"
}

Ephemeral Response

{
  "type": 4,
  "content": "Only you can see this.",
  "flags": 64          // EPHEMERAL
}

Deferred Response (Type 5)

// Step 1: Acknowledge immediately
{
  "type": 5            // DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE
}

// Step 2: Send follow-up (within 15 minutes)
fetch(`/api/interactions/${interactionId}/${token}/followup`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ content: 'Done!' }),
})

Interaction Type Constants

Message Flags

Message Components

Messages can include interactive components — currently buttons inside action rows. Pass a components array when sending a message via either the REST API or an interaction callback/followup.

Structure

{
  "content": "Choose an option:",
  "components": [
    {
      "type": 1,          // ACTION_ROW — up to 5 buttons per row
      "components": [
        {
          "type":      2,              // BUTTON
          "style":     1,              // 1=Primary 2=Secondary 3=Success 4=Danger 5=Link
          "label":     "Click me",
          "custom_id": "my_button_1"  // echoed back in the INTERACTION_CREATE event
        }
      ]
    }
  ]
}

Button Styles

Receiving button clicks

When a user clicks a button, your bot receives an INTERACTION_CREATE event with type: 3 (MESSAGE_COMPONENT). The data payload contains the custom_id of the button that was clicked and the message_id of the message it belongs to. Respond using the same callback endpoint as slash commands.

gateway.on('INTERACTION_CREATE', async (interaction) => {
  if (interaction.type !== 3) return; // MESSAGE_COMPONENT

  const { custom_id, message_id } = interaction.data;

  await fetch(
    `/api/interactions/${interaction.id}/${interaction.token}/callback`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ type: 4, content: `You clicked: ${custom_id}` }),
    }
  );
});

Event Subscriptions (Webhook Delivery)

If your bot is not connected to the gateway, you can still receive events via webhook. Register a subscription URL and NexusGuild will POST events to it as they occur. The gateway takes priority — if your bot is connected, webhook delivery is skipped.

PUT Request Body (JSON)

// Example PUT body
{
  "webhook_url":  "https://mybot.example.com/nexus-events",
  "signing_key":  "my-secret-signing-key",
  "events": ["MESSAGE_CREATE", "MESSAGE_UPDATE", "REACT_ADD", "REACT_REMOVE"]
}

Available Event Names

MESSAGE_CREATE MESSAGE_UPDATE MESSAGE_DELETE REACT_ADD REACT_REMOVE MEMBER_JOIN MEMBER_LEAVE CHANNEL_CREATE CHANNEL_UPDATE CHANNEL_DELETE ROLE_UPDATE

Webhook Payload

Your endpoint receives a POST with Content-Type: application/json and two custom headers:

// Webhook body shape
{
  "event":     "MESSAGE_CREATE",
  "data":      { /* same payload as the gateway event */ },
  "timestamp": 1742400000000
}

Verifying the signature (Node.js)

import crypto from 'crypto';

function verifySignature(rawBody, signature, signingKey) {
  const expected = crypto
    .createHmac('sha256', signingKey)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Rate Limiting

The /api/v1 endpoints enforce a sliding-window rate limit of 50 requests per 10 seconds per bot token. Exceeding the limit returns a 429 Too Many Requests response.

429 Response

HTTP/1.1 429 Too Many Requests
Retry-After: 3

{
  "error":       "Too many requests",
  "retry_after": 3    // seconds until the oldest request leaves the window
}

Always check for a 429 status and wait retry_after seconds before retrying.