# REST API Reference

URL: https://zerodev.ca/docs/medusa/developer-documentation/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**:
  ```json
  {
      "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**:
  ```json
  {
      "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**:
  ```json
  [
      {
          "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**:
  ```json
  {
      "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**:
  ```json
  [
      {
          "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**:
  ```json
  {
      "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**:
  ```json
  {
      "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**:
  ```json
  {
      "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**:
  ```json
  {
      "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**:
  ```json
  {
      "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**:
  ```json
  {
      "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**:
  ```json
  [
      {
          "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**:
  ```json
  {
      "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**:
  ```json
  {
      "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**:
  ```json
  {
      "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**:
  ```json
  {
      "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 }] }`