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.