Medusa/developer documentation/REST API Reference

REST API Reference

Complete reference of internal REST API endpoints exposed by Medusa on port 3001.

Medusa hosts an internal HTTP REST API on port 3001 (or SERVER.API.PORT). Requests require an Authorization: Bearer <SECRET> header matching AUTHENTICATION.SECRET from config.json unless stated otherwise.

System Endpoints

`GET /api/status`

Retrieves overall system health, licensing status, connected Discord bot statistics, and active guild metadata.

Authentication: None (Public)
Query Parameters:
- guildId (string, optional) - Target guild ID for the server object.

Response:

{
    "product": "Medusa",
    "version": "1.0.0.0",
    "running": true,
    "license": {
        "activated": true,
        "message": null
    },
    "limits": {
        "bots": {
            "current": 1,
            "max": 1
        },
        "servers": {
            "current": 1,
            "max": 1
        }
    },
    "statistics": {
        "boots": 4,
        "uptime": 3600,
        "startedAt": "2026-10-26T18:00:00.000Z",
        "memory": 104857600
    },
    "modules": {
        "loaded": 22,
        "failed": 0
    },
    "bot": {
        "username": "Medusa",
        "tag": "Medusa#0000",
        "id": "100000000000000000",
        "avatar": "https://cdn.discordapp.com/avatars/...",
        "ready": true
    },
    "server": {
        "name": "Production Server",
        "id": "200000000000000000",
        "icon": "https://cdn.discordapp.com/icons/..."
    },
    "servers": [
        {
            "id": "200000000000000000",
            "name": "Production Server",
            "icon": "https://cdn.discordapp.com/icons/...",
            "memberCount": 150,
            "joinedAt": 1700000000000,
            "authorized": true,
            "primary": true
        }
    ]
}

`GET /api/logs`

Retrieves live console output entries.

Authentication: Bearer Secret
Query Parameters:
- after (number, optional) - Return entries with sequence ID greater than this value.

Response:

{
    "entries": [
        {
            "id": 104,
            "time": "2026-09-13T21:30:00.000Z",
            "level": "info",
            "message": "Module example loaded."
        }
    ]
}

Module Endpoints

`GET /api/modules`

Returns a catalog of all modules located in the modules/ directory, including version metadata, enable state, and registered subsystem counts.

Authentication: Bearer Secret

Response:

[
    {
        "id": "example",
        "name": "example",
        "version": "1.0.0.0",
        "author": "Zero Development",
        "description": "Example module.",
        "locked": false,
        "enabled": true,
        "loaded": true,
        "failed": false,
        "commands": 1,
        "events": 1,
        "clocks": 1,
        "models": 1,
        "routes": 1,
        "pages": 1,
        "config": 1,
        "lang": 1,
        "logs": 1
    }
]

`POST /api/modules/toggle`

Enables or disables a module at runtime.

Authentication: Bearer Secret

Request Body:

{
    "id": "example",
    "enabled": false,
    "actorId": "100000000000000000",
    "actorTag": "Admin#0001"
}

Response: { "success": true }

`GET /api/modules/configs`

Retrieves all module configuration groups, schemas, and current values.

Authentication: Bearer Secret
Query Parameters:
- guildId (string, optional) - Target guild ID for server-scoped configuration values.

Response:

[
    {
        "id": "example",
        "name": "example",
        "groups": [
            {
                "name": "settings",
                "label": "Example Settings",
                "description": "Module configuration.",
                "preview": "",
                "fields": [
                    {
                        "key": "enabled",
                        "label": "Module Enabled",
                        "type": "boolean",
                        "value": true
                    }
                ]
            }
        ]
    }
]

`POST /api/modules/config`

Saves updated settings values for a specific module configuration group.

Authentication: Bearer Secret

Request Body:

{
    "id": "example",
    "group": "settings",
    "values": {
        "enabled": false
    },
    "guildId": "200000000000000000",
    "actorId": "100000000000000000",
    "actorTag": "Admin#0001"
}

Response: { "success": true, "values": { "enabled": false } }

`GET /api/locales`

Returns the active locale, the secondary (fallback) locale, the base locale ("en"), and all 16 supported languages.

Authentication: Bearer Secret

Response:

{
    "active": "en",
    "secondary": "en",
    "base": "en",
    "supported": [
        { "code": "en", "name": "English", "native": "English", "discord": "en-US" }
    ]
}

`GET /api/modules/langs`

Retrieves phrase and embed schemas with current localized values.

Authentication: Bearer Secret
Query Parameters:
- locale (string, optional) - Target language code.
Response: List of module language groups and fields.

`GET /api/modules/dictionary`

Retrieves the combined web dashboard localization dictionary from all loaded modules.

Authentication: Bearer Secret
Query Parameters:
- locale (string, optional) - Target language code.
Response: Key-value map of module dashboard translations and display names.

`POST /api/modules/lang`

Saves language phrase or embed overrides for a specific locale.

Authentication: Bearer Secret

Request Body:

{
    "id": "example",
    "group": "messages",
    "locale": "en",
    "values": {
        "created": "Item **%name%** created."
    },
    "actorId": "100000000000000000",
    "actorTag": "Admin#0001"
}

Response: { "success": true, "values": { ... } }

`GET /api/modules/logging`

Retrieves logging categories, configured channels, and individual event toggles.

Authentication: Bearer Secret
Query Parameters:
- guildId (string, optional) - Target guild ID for server-scoped logging channels and toggles.
Response: List of module logging definitions.

`POST /api/modules/logging`

Updates channel targets or event toggles. In the channels group, server sets the log server (empty for the current server) and channels are validated against it.

Authentication: Bearer Secret

Request Body:

{
    "id": "example",
    "group": "channels",
    "values": {
        "server": "300000000000000000",
        "itemLogs": "123456789012345678"
    },
    "guildId": "200000000000000000",
    "actorId": "100000000000000000",
    "actorTag": "Admin#0001"
}

Response: { "success": true, "values": { ... } }

Command Endpoints

`GET /api/commands`

Lists all registered commands, global prefix, subcommands, and individual enablement states.

Authentication: Bearer Secret

Response:

{
    "prefix": "!",
    "commands": [
        {
            "name": "manage",
            "description": "Manage system items.",
            "module": "example",
            "moduleName": "example",
            "baselinePermission": "moderator",
            "enabled": true,
            "slash": true,
            "prefix": true,
            "mention": true,
            "customPrefix": "",
            "subcommands": [],
            "subcommandGroups": []
        }
    ]
}

`POST /api/commands`

Saves command configuration and prefix settings.

Authentication: Bearer Secret

Request Body:

{
    "prefix": "!",
    "commands": {
        "manage": {
            "enabled": true,
            "slash": true,
            "prefix": true
        }
    }
}

Response: { "success": true }

`POST /api/commands/sync`

Forces an immediate re-registration of all application slash commands with the Discord API.

Authentication: Bearer Secret
Response: { "success": true }

Discord & Bot Endpoints

`GET /api/discord/servers`

Retrieves a list of all currently connected and authorized Discord servers.

Authentication: Bearer Secret

Response:

[
    {
        "id": "200000000000000000",
        "name": "Production Server",
        "icon": "https://cdn.discordapp.com/icons/...",
        "memberCount": 150,
        "joinedAt": 1700000000000,
        "authorized": true,
        "primary": true
    }
]

`GET /api/discord/resources`

Fetches Discord server resources for form pickers.

Authentication: Bearer Secret
Query Parameters:
- guildId (string, optional) - Target guild ID for channel, category, role, and emoji resources.

Response:

{
    "guildId": "200000000000000000",
    "channels": [
        { "id": "12345", "name": "general", "type": 0, "parentId": null }
    ],
    "categories": [
        { "id": "67890", "name": "Information" }
    ],
    "roles": [
        { "id": "54321", "name": "Admin", "color": "#ef4444", "icon": null }
    ],
    "emojis": [
        { "id": "11111", "name": "check", "animated": false, "markup": "<:check:11111>" }
    ],
    "serverIcon": "https://cdn.discordapp.com/icons/..."
}

`POST /api/bot/start`

Starts the Discord gateway client.

Authentication: Bearer Secret
Response: { "success": true }

`POST /api/bot/stop`

Stops the Discord gateway client session.

Authentication: Bearer Secret
Response: { "success": true }

`POST /api/bot/restart`

Restarts the Discord gateway connection.

Authentication: Bearer Secret
Response: { "success": true }

`POST /api/bot/presence`

Updates bot presence, status, and rotating activity messages.

Authentication: Bearer Secret

Request Body:

{
    "status": "online",
    "type": "Watching",
    "message": "the server"
}

Response: { "success": true }

`POST /api/bot/profile`

Updates the bot username, avatar or banner. Images are data URIs (PNG, JPG, GIF or WEBP). The request body limit is 25 MB.

Authentication: Bearer Secret

Request Body:

{
    "username": "NewBotName",
    "avatar": "data:image/png;base64,...",
    "banner": "data:image/gif;base64,..."
}

Response: Updated bot statistics.

Messages & Embeds

`GET /api/messages`

Lists all saved embed templates.

Authentication: Bearer Secret
Response: Array of saved template records.

`POST /api/messages`

Creates or updates an embed template record.

Authentication: Bearer Secret
Request Body: Template record object.
Response: { "success": true, "message": { ... } }

`DELETE /api/messages/:id`

Deletes a saved embed template by ID.

Authentication: Bearer Secret
Response: { "success": true, "messages": [ ... ] }

`POST /api/embeds/send`

Dispatches a message, embed, or component layout directly to a Discord channel.

Authentication: Bearer Secret

Request Body:

{
    "channel": "123456789012345678",
    "content": "Announcement text",
    "embed": {
        "title": "Header",
        "description": "Body message",
        "color": "#22c55e"
    },
    "buttons": [
        { "style": "link", "label": "Website", "url": "https://zerodev.ca" }
    ]
}

Response: { "success": true }

Custom Pages

`GET /api/pages`

Returns all registered custom dashboard pages.

Authentication: Bearer Secret
Response: Array of custom page descriptors.

Settings & Root Configuration

`GET /api/settings`

Reads all global settings stored in the database.

Authentication: Bearer Secret
Response: Key-value map of settings.

`POST /api/settings`

Updates global settings in memory and database.

Authentication: Bearer Secret
Request Body: Key-value dictionary of settings to update.
Response: { "success": true }

`POST /api/settings/reload`

Forces a reload of all database settings into memory cache.

Authentication: Bearer Secret
Response: { "success": true }

`GET /api/placeholders`

Lists every placeholder key contributed by enabled modules, used by the activity status buttons.

Authentication: Bearer Secret
Response: [{ "key": string, "label": string, "sample": string, "module": string }]

`GET /api/emojis/status`

Reports the progress of the emoji sync for each bot.

Authentication: Bearer Secret
Response: { "running": boolean, "bots": [{ "key": string, "label": string, "phase": "queued" | "removing" | "uploading" | "done", "done": number, "total": number, "failed": number }] }

`POST /api/config`

Updates root config.json properties.

Authentication: Bearer Secret
Request Body: Configuration patch object.
Response: { "success": true }

Bootstrap Endpoints

`POST /api/bootstrap/license`

Validates a license key with the licensing server.

Authentication: Bearer Secret
Request Body: { "key": string, "botId": string, "guildId": string }
Response: { "valid": boolean, "message": string, "owner": { "id": string, "name": string } | null }

`POST /api/bootstrap/modules`

Lists the official modules the license covers (installed free modules plus owned paid ones; every module with Full Source) so the setup wizard can offer Auto-Update Exclusions and Frozen Modules before the license is activated. Falls back to the stored LICENSE_KEY when key is empty.

Authentication: Bearer Secret
Request Body: { "key": string, "botId": string, "guildId": string }
Response: { "modules": [{ "id": string, "name": string }] }

`POST /api/bootstrap/bot`

Checks a bot token against Discord and verifies required privileged intents.

Authentication: Bearer Secret
Request Body: { "token": string }
Response: { "id": string, "application": string, "name": string, "avatar": string, "missing": string[] }

`GET /api/bootstrap/database`

Returns the database credentials already stored in config.json so the setup wizard can offer to autofill them. Returns null once setup is complete or when no database is configured. The password is redacted to "__set__".

Authentication: Bearer Secret
Response: { "TYPE": string, "HOST": string, "PORT": string, "USER": string, "PASSWORD": "__set__" | "", "DATABASE": string } | null

`POST /api/bootstrap/database`

Tests connection parameters against the target database. Returns detected existing bot configuration if present. A PASSWORD of "__set__" uses the password stored in config.json, and /api/bootstrap/finalize resolves it the same way.

Authentication: Bearer Secret
Request Body: { "TYPE": string, "HOST": string, "PORT": string, "USER": string, "PASSWORD": string, "DATABASE": string }
Response: { "ok": true, "existing": { "hasBot": boolean, "botId": string, "token": string, "name": string, "avatar": string, "guildId": string, "licenseKey": string, "serverName": string, "dashboardName": string, "theme": string, "accent": string, "settings": Record<string, string> } | null }

`POST /api/bootstrap/reset`

Drops all tables in the specified database connection to perform a factory reset to a fresh instance.

Authentication: Bearer Secret
Request Body: { "TYPE": string, "HOST": string, "PORT": string, "USER": string, "PASSWORD": string, "DATABASE": string }
Response: { "success": true }

`POST /api/bootstrap/discord`

Verifies Discord OAuth2 client ID and client secret credentials against Discord.

Authentication: Bearer Secret
Request Body: { "clientId": string, "clientSecret": string }
Response: { "ok": true }

`POST /api/bootstrap/finalize`

Completes first-time installation and saves all initial system settings. Returns a launch token that reads the startup logs for the next 10 minutes.

Authentication: Bearer Secret
Request Body: Setup finalization payload.
Response: { "success": true, "token": string }

`GET /api/bootstrap/logs`

Returns console entries written since setup was finalized, so the wizard can show startup progress before anyone has signed in. Requires the token from /api/bootstrap/finalize, which expires after 10 minutes.

Authentication: Bearer Secret
Query: token (launch token), after (last entry id already received)
Response: { "entries": [{ "id": number, "time": string, "level": string, "message": string }] }

PreviousInternal API Specification NextTerms of Service