REST API Reference
Complete documentation of Medusa's internal HTTP REST API endpoints and payload specifications.
Medusa exposes an internal REST API on port 3001 (or the port defined in SERVER.API.PORT). All endpoints except /api/status require authentication via the Authorization header.
Authorization: Bearer YOUR_AUTHENTICATION_SECRETSystem Endpoints
GET /api/status
Returns high-level health information about Medusa, including active license state, loaded modules, and Discord bot connectivity. This endpoint is public.
Response
{
"product": "Medusa",
"version": "1.0.0.0",
"running": true,
"license": {
"activated": true,
"message": null
},
"modules": {
"loaded": 22,
"failed": 0
},
"bot": {
"id": "1530443442247958639",
"username": "Medusa",
"tag": "Medusa#0000"
},
"server": {
"id": "123456789012345678",
"name": "Zero Development Community"
}
}GET /api/logs
Retrieves streaming console output lines.
Query Parameters
after(number, optional): Returns only logs created after the specified sequential log sequence ID.
Response
{
"entries": [
{
"id": 142,
"time": "2026-09-13T00:00:00.000Z",
"level": "info",
"message": "Loaded 22 modules successfully."
}
]
}Module Endpoints
GET /api/modules
Retrieves the full catalog of modules, indicating active status, version, and author.
Response
[
{
"id": "moderation",
"name": "Moderation",
"version": "1.0.0.0",
"author": "Zero Development",
"enabled": true
}
]POST /api/modules/toggle
Enables or disables an installed module at runtime.
Request Body
{
"id": "music",
"enabled": false,
"actorId": "764868946523324457",
"actorTag": "Admin#0001"
}Response
{
"success": true
}Configuration & Schemas
GET /api/modules/configs
Fetches the full dynamic configuration schema definitions and current stored values for all modules.
POST /api/modules/config
Updates dynamic configuration values for a module group.
Request Body
{
"id": "moderation",
"group": "general",
"values": {
"MUTED_ROLE": "123456789012345678",
"AUTO_DELETE_INFRACTIONS": false
},
"actorId": "764868946523324457",
"actorTag": "Admin#0001"
}GET /api/modules/logging
Retrieves all module logging channel targets and schemas.
POST /api/modules/logging
Saves logging channel targets and enabled events for a module.
Commands Management
GET /api/commands
Retrieves all registered commands, their current prefix, execution status, and subcommands.
Response
{
"prefix": "!",
"commands": [
{
"name": "ban",
"description": "Ban a member from the server.",
"module": "moderation",
"enabled": true,
"slash": true,
"prefix": true,
"mention": false,
"customPrefix": ";",
"subcommands": []
}
]
}POST /api/commands
Updates global prefix and per-command execution rules.
POST /api/commands/sync
Forces an immediate re-registration of all application slash commands with the Discord API.
Messages & Embeds
GET /api/messages
Returns all saved embed templates.
POST /api/messages
Creates or updates a saved message template.
DELETE /api/messages/:id
Deletes a saved message template by ID.
POST /api/embeds/send
Dispatches a custom message or embed payload to a Discord channel.
Request Body
{
"channel": "123456789012345678",
"content": "Announcement from the staff team:",
"embed": {
"title": "Scheduled Maintenance",
"description": "Our servers will undergo updates tonight at 02:00 UTC.",
"color": "#22c55e"
},
"buttons": [
{
"label": "Status Page",
"url": "https://status.zerodev.ca",
"style": "Link"
}
]
}Bot Control
POST /api/bot/start
Initializes and connects the Discord client.
POST /api/bot/stop
Disconnects the Discord client from the gateway.
POST /api/bot/restart
Performs a graceful restart of the Discord client session.
POST /api/bot/presence
Updates the bot's custom rich presence and activity status.
Request Body
{
"status": "online",
"activities": [
{
"name": "zerodev.ca",
"type": 3
}
]
}POST /api/bot/profile
Updates the bot username or avatar picture.
Request Body
{
"username": "Medusa Bot",
"avatar": "data:image/png;base64,..."
}