API Reference

Complete REST API documentation for Holo Bridge. All endpoints require authentication via the X-API-Key header.

Authentication

All API requests require the X-API-Key header with your configured API key.

curl -H "X-API-Key: your_api_key" http://localhost:3000/api/guilds

Response Format

All responses follow a consistent format:

// Success
{
    "success": true,
    "data": { ... }
}

// Error
{
    "success": false,
    "error": "Error message",
    "code": "ERROR_CODE"
}

Guilds

GET /api/guilds

List all guilds the bot is in.

curl -H "X-API-Key: your_key" http://localhost:3000/api/guilds

GET /api/guilds/:guildId

Get details of a specific guild.

curl -H "X-API-Key: your_key" http://localhost:3000/api/guilds/123456789

GET /api/guilds/:guildId/channels

Get all channels in a guild.

GET /api/guilds/:guildId/roles

Get all roles in a guild.

GET /api/guilds/:guildId/emojis

Get all emojis in a guild.

GET /api/guilds/:guildId/bans

Get all bans in a guild.

GET /api/guilds/:guildId/invites

Get all invites in a guild.

Channels

GET /api/channels/:channelId

Get a channel by ID.

POST /api/guilds/:guildId/channels

Create a new channel in a guild.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Channel name (1-100 chars)
`type`	string	Yes	text, voice, category, announcement, stage, forum
`topic`	string	No	Channel topic (max 1024 chars)
`parentId`	string	No	Category ID
`position`	number	No	Channel position
`nsfw`	boolean	No	NSFW flag
`rateLimitPerUser`	number	No	Slowmode (0-21600 seconds)
`bitrate`	number	No	Voice channel bitrate
`userLimit`	number	No	Voice channel user limit (0-99)

PATCH /api/channels/:channelId

Edit a channel. All fields are optional.

DELETE /api/channels/:channelId

Delete a channel.

Threads

Method	Endpoint	Description
POST	`/api/channels/:channelId/threads`	Create a thread
GET	`/api/channels/:channelId/threads`	Get all threads
POST	`/api/channels/:channelId/archive`	Archive a thread
DELETE	`/api/channels/:channelId/archive`	Unarchive a thread
POST	`/api/channels/:channelId/lock`	Lock a thread
DELETE	`/api/channels/:channelId/lock`	Unlock a thread

POST /api/channels/:channelId/clone

Clone a channel. Optionally provide a name in the request body.

GET /api/channels/:channelId/webhooks

Get all webhooks for a channel.

Messages

GET /api/channels/:channelId/messages

Get messages from a channel.

Query Parameters

Parameter	Type	Description
`limit`	number	Number of messages (1-100, default: 50)
`before`	string	Get messages before this ID
`after`	string	Get messages after this ID
`around`	string	Get messages around this ID

GET /api/channels/:channelId/messages/pinned

Get pinned messages in a channel.

GET /api/channels/:channelId/messages/:messageId

Get a specific message by ID.

POST /api/channels/:channelId/messages

Send a message to a channel.

Request Body

Field	Type	Required	Description
`content`	string	No*	Message content (max 2000 chars)
`embeds`	array	No*	Array of embed objects
`replyTo`	string	No	Message ID to reply to
`tts`	boolean	No	Text-to-speech

*Either content or at least one embed is required.

PATCH /api/channels/:channelId/messages/:messageId

Edit a message.

DELETE /api/channels/:channelId/messages/:messageId

Delete a message.

POST /api/channels/:channelId/messages/bulk-delete

Bulk delete messages. Send messageIds array in body.

Reactions

Method	Endpoint	Description
POST	`/api/channels/:channelId/messages/:messageId/reactions/:emoji`	Add reaction
DELETE	`/api/channels/:channelId/messages/:messageId/reactions/:emoji`	Remove reaction
DELETE	`/api/channels/:channelId/messages/:messageId/reactions`	Remove all reactions
GET	`/api/channels/:channelId/messages/:messageId/reactions/:emoji/users`	Get reaction users

Pins

Method	Endpoint	Description
POST	`/api/channels/:channelId/messages/:messageId/pin`	Pin a message
DELETE	`/api/channels/:channelId/messages/:messageId/pin`	Unpin a message

POST /api/channels/:channelId/messages/:messageId/crosspost

Crosspost a message (for announcement channels).

Members

GET /api/guilds/:guildId/members

List all members in a guild.

Query Parameters

Parameter	Type	Description
`limit`	number	Max members to return (default: 1000)

GET /api/guilds/:guildId/members/search

Search members by username/nickname.

Query Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Search query
`limit`	number	No	Max results (default: 20)

GET /api/guilds/:guildId/members/:userId

Get a specific member.

Moderation

Method	Endpoint	Description
POST	`/api/guilds/:guildId/members/:userId/kick`	Kick member
POST	`/api/guilds/:guildId/members/:userId/ban`	Ban member
DELETE	`/api/guilds/:guildId/bans/:userId`	Unban user
POST	`/api/guilds/:guildId/members/:userId/timeout`	Timeout member
DELETE	`/api/guilds/:guildId/members/:userId/timeout`	Remove timeout

Ban Request Body

Field	Type	Description
`reason`	string	Ban reason (max 512 chars)
`deleteMessageSeconds`	number	Seconds of messages to delete (0-604800)

Timeout Request Body

Field	Type	Required	Description
`duration`	number	Yes	Duration in milliseconds
`reason`	string	No	Timeout reason

Member Roles

Method	Endpoint	Description
PATCH	`/api/guilds/:guildId/members/:userId/nickname`	Set nickname
PATCH	`/api/guilds/:guildId/members/:userId/roles`	Modify roles

Modify Roles Request Body

Field	Type	Description
`add`	string[]	Role IDs to add
`remove`	string[]	Role IDs to remove

Roles

GET /api/guilds/:guildId/roles

Get all roles in a guild.

GET /api/guilds/:guildId/roles/search?name=RoleName

Search for a role by name.

GET /api/guilds/:guildId/roles/:roleId

Get a specific role.

POST /api/guilds/:guildId/roles

Create a new role.

Request Body

Field	Type	Description
`name`	string	Role name (max 100 chars)
`color`	number	Color integer (0-16777215)
`hoist`	boolean	Display separately
`mentionable`	boolean	Allow mentions
`permissions`	string	Permission bitfield

PATCH /api/guilds/:guildId/roles/:roleId

Edit a role. Same fields as create, plus position.

DELETE /api/guilds/:guildId/roles/:roleId

Delete a role.

GET /api/guilds/:guildId/roles/:roleId/members

Get all member IDs with a specific role.

PATCH /api/guilds/:guildId/roles/:roleId/permissions

Set role permissions. Send permissions (bitfield string) in body.

Stickers

GET /api/guilds/:guildId/stickers

List all stickers in a guild.

GET /api/guilds/:guildId/stickers/:stickerId

Get a specific sticker.

POST /api/guilds/:guildId/stickers

Create a new sticker.

PATCH /api/guilds/:guildId/stickers/:stickerId

Edit a sticker.

DELETE /api/guilds/:guildId/stickers/:stickerId

Delete a sticker.

Scheduled Events

GET /api/guilds/:guildId/scheduled-events

List all scheduled events.

GET /api/guilds/:guildId/scheduled-events/:eventId

Get a specific event.

POST /api/guilds/:guildId/scheduled-events

Create a new event.

PATCH /api/guilds/:guildId/scheduled-events/:eventId

Edit an event.

DELETE /api/guilds/:guildId/scheduled-events/:eventId

Delete an event.

AutoMod

GET /api/guilds/:guildId/auto-moderation/rules

List all auto-moderation rules.

GET /api/guilds/:guildId/auto-moderation/rules/:ruleId

Get a specific rule.

POST /api/guilds/:guildId/auto-moderation/rules

Create a new rule.

PATCH /api/guilds/:guildId/auto-moderation/rules/:ruleId

Edit a rule.

DELETE /api/guilds/:guildId/auto-moderation/rules/:ruleId

Delete a rule.

Other Resources

Stage Instances

Endpoints: /api/stage-instances (GET, POST, PATCH, DELETE)

Invites

Endpoints: /api/invites/:code (GET, DELETE)

Webhooks

Endpoints: /api/webhooks/:webhookId (GET, PATCH, DELETE)

Emojis

Endpoints: /api/guilds/:guildId/emojis (GET, POST, PATCH, DELETE)

Application Commands (Slash Commands)

Manage Discord Application Commands (Slash Commands) for your bot. Commands can be global (available in all guilds) or guild-specific.

GET /api/commands

List all global application commands.

curl -H "X-API-Key: your_key" http://localhost:3000/api/commands

GET /api/commands/:commandId

Get a specific global command by ID.

POST /api/commands

Create a new global application command.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Command name (1-32 chars, lowercase)
`description`	string	Yes	Command description (1-100 chars)
`type`	number	No	1=CHAT_INPUT (default), 2=USER, 3=MESSAGE
`options`	array	No	Command options (max 25)
`default_member_permissions`	string	No	Permission bitfield
`dm_permission`	boolean	No	Allow in DMs
`nsfw`	boolean	No	Age-restricted command

Example

curl -X POST -H "X-API-Key: your_key" -H "Content-Type: application/json" \
  -d '{"name": "hello", "description": "Says hello"}' \
  http://localhost:3000/api/commands

PATCH /api/commands/:commandId

Edit a global application command. All fields optional.

DELETE /api/commands/:commandId

Delete a global application command.

Guild-Specific Commands

Guild commands are only available in the specified guild. They update instantly (unlike global commands which can take up to an hour).

GET /api/guilds/:guildId/commands

List all commands for a specific guild.

GET /api/guilds/:guildId/commands/:commandId

Get a specific guild command.

POST /api/guilds/:guildId/commands

Create a guild-specific command. Same request body as global commands.

PATCH /api/guilds/:guildId/commands/:commandId

Edit a guild-specific command.

DELETE /api/guilds/:guildId/commands/:commandId

Delete a guild-specific command.